mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Tianyi Cui b0bc0b5792 feat(agent-loop): turn-enclosure invariant + post-turn error model

Every session event now lives inside a turn (between turn/start and its
turn/end). The loop records queued user/message events AFTER turn/start;
an idle agent.inject() wraps its context/message in a one-shot injection
turn. This makes the turn the single durability/replay boundary so a
persistence backend can treat anything after the last turn/end as a
crash tail without dropping legitimate between-turn context.

A failure once the turn is already closed (rejecting session/flush, a
throwing agent/turn-end listener) has no in-turn position for a session
error event, so it is reported via agent/error + logger only; the turn
stays balanced. failTurn appends an error event only while the turn is
open.

The dsh-invariants plugin enforces turn-enclosure via a default case:
every non-boundary event type — including plugin-added merge-extensible
keys — must sit inside an open turn or it throws.

Documented in ADR 0017 + architecture.md.

2026-06-15 20:56:17 +08:00

2.7 KiB

Raw Blame History

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): () => void Register a live agent. Disposed with the calling fiber.
ctx.agents.get(id: string): Agent | undefined
ctx.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/deregistration
agent/status — idle / running / disposed transition
agent/queued — message entered inbox (source-resolved, steering flag)

Turn/step boundaries (emit)

agent/turn-start, agent/turn-end (carries TurnEndReason)
agent/step-start, agent/step-end

Interception seams (waterfall)

agent/request — mutate GenerateOptions before 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-turn
agent/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 idle
agent.steer(content, options?) — steer a running turn (inject between steps); behaves like send when idle
agent.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-shot injection turn so every event stays turn-enclosed (ADR 0017)
agent.abort(reason?) — abort the in-flight step
agent.session, agent.status, agent.options, agent.id

Extension points

Agent creation: AgentLoop.create() is the concrete implementation (in dsh-agent-loop). Replace the loop by implementing Agent and registering via ctx.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.

2.7 KiB Raw Blame History