A capability is not one tool function
DSH calls a replaceable capability a capability seam. A complete seam has at least three roles: a Service Definition declares the interface, a Service Provider implements it, and a Consumer exposes it to the model, UI, or another runtime caller.
Shell, for example, is more than a Bash tool. It also needs a shell service, a local or remote provider, and a model-facing tool that consumes the service. Separating these roles lets the provider change without forking the Consumer.
Services make direct calls; Events enable interception
When one owner should perform an operation, a Consumer calls a service method. When several Plugins need to observe, wrap, or apply policy, the capability exposes typed events.
DSH separates durable session events, in-flight agent events, and capability events. Session events enter the log and can be replayed; the other domains coordinate a live request, tool, or policy without pretending to be durable facts.
Consumer -> ctx.<service> -> Provider
|
+-> typed events -> policy / telemetry / wrappersWaterfalls can delegate or take ownership
A Cordis waterfall event is around-middleware. A listener calls next() to delegate downstream and may wrap the returned value. Returning without next() deliberately short-circuits the chain.
DSH uses waterfalls for interceptable paths such as agent requests, LLM streaming, and tool execution. A listener that only observes or annotates must delegate; a policy that owns a reject or replacement decision may short-circuit.
Scopes let one process host different Agents
A Context can isolate a named service. An implementation provided below the child Context does not affect its parent, and registrations for one Agent can shadow global defaults.
DSH can therefore compose different tools, prompt sections, providers, or policies for different Agents inside one Host. The difference belongs to an explicit Context instead of scattered if/else checks at every call site.
Design all three roles before adding a capability
A model tool that embeds I/O, policy, and implementation in one function is difficult to reuse from another UI, Agent, or provider. Define the seam first, then decide which Plugins own the Definition, Provider, and Consumer roles.
This structure lets the DSH ecosystem share composable interfaces instead of accumulating isolated commands.