Tianyi Cui
4535bfab75
Session.append pushes the event BEFORE notifying session/event listeners,
so a throwing listener leaves the event in the log while the line after
the append (a boolean flag) never runs. Both turn-balance decisions were
gated on such flags, so a throwing listener could strand an open turn or
skip a durability checkpoint.
- loop.ts: the outer catch decided "turn/end owed" from `turnStarted`.
A throwing listener on the turn/start append left turn/start logged but
the flag false → catch rethrew and skipped turn/end → permanently open
turn (violating ADR 0017). Now decided from the log (this turn's
turn/start present), so the turn is always balanced; only a genuine
pre-push failure (non-serializable trigger — turn/start never logged) is
rethrown to the runLoop backstop. Removed the now-dead `turnStarted`.
- agent.ts inject(): the idle one-shot-turn flush was gated on a
`turnRecorded` flag set after append('turn/end'); a throwing turn/end
listener skipped the flush, losing the balanced in-memory injection turn
on crash. Now the flush decision is read from the log, the synthetic
turn/end append contains a throwing listener (turn stays balanced), and
a failing idle flush is reported via agent/error (step 0 convention) AND
the logger — mirroring the loop's post-turn/end flush path — with a
throwing agent/error listener contained.
Rewrote the test that encoded the old (buggy) "turn/start listener throw
is rethrown, no turn/end" semantics to assert the balanced-turn contract,
and added regressions for the throwing-turn/end-listener flush and the
agent/error report. Updated Agent.inject JSDoc.
dsh-agent
Agent interface, registry, and agent/* event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the Agent handle defined here — it has zero loop dependency, so the loop is swappable.
Service: AgentRegistry (ctx key: agents)
Tracks live agents so UI, hook, and orchestrator plugins can find them without importing the concrete loop package.
Public API
ctx.agents.register(agent: Agent): () => voidRegister a live agent. Disposed with the calling fiber.ctx.agents.get(id: string): Agent | undefinedctx.agents.list(): Agent[]
Events
The full agent/* event taxonomy is declared via declaration merging in dsh-agent (not dsh-agent-loop), so plugins depend only on this package.
Lifecycle (emit)
agent/created,agent/disposed— registration/deregistrationagent/status— idle / running / disposed transitionagent/queued— message entered inbox (source-resolved, steering flag)
Turn/step boundaries (emit)
agent/turn-start,agent/turn-end(carriesTurnEndReason)agent/step-start,agent/step-end
Interception seams (waterfall)
agent/request— mutateGenerateOptionsbefore the model call (hooks, compaction, model switching, tool filtering)agent/step-result— post-process the assembled assistant message before tool dispatch (validates what the log records)agent/turn-continuation— override the continue/stop decision (force-continue /loop, force-stop budget guard)
Streaming + tool (emit)
agent/stream-chunk— raw chunk from the model (token-level UI/log feed)agent/steering— steering content injected mid-turnagent/error— step/turn error
Agent interface (types.ts)
The handle every plugin programs against:
agent.send(content, options?)— queue a message; starts a turn when idleagent.steer(content, options?)— steer a running turn (inject between steps); behaves likesendwhen idleagent.inject(content, options?)— inject in-session context (context/message event); next request sees it. While running it joins the open turn; while idle it is wrapped in a one-shotinjectionturn so every event stays turn-enclosed (ADR 0017)agent.abort(reason?)— abort the in-flight stepagent.session,agent.status,agent.options,agent.id
Extension points
- Agent creation:
AgentLoop.create()is the concrete implementation (indsh-agent-loop). Replace the loop by implementingAgentand registering viactx.agents.register(). - Event listeners: all
agent/*events are declared here — no dependency on the loop package needed.
What is NOT here (TODO)
- Sub-agent spawn/fork — seam on
AgentLoop.create(), semantics deferred.