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

Files

Tianyi Cui c4bc6e0e38 feat(agent): add queue-aware Agent.cancel() primitive

abort() only kills the in-flight step, so a queued-but-not-yet-started prompt
ran to completion after a cancel and a prompt accepted right after could be
batched into the cancelled turn (the loop merges queued messages into one turn).
This closes TODO(rfc010-cancel-prestep) with a distinct cancel() verb.

cancel() clears the queued + steering FIFOs, aborts the in-flight step, and
drives a turn-scoped marker on the LoopHandle that the driver checks at EVERY
point a turn could start or continue:
- right after the idle wait (window 1): drop the about-to-run turn and settle
  whenIdle() waiters directly (no running→idle transition fires, and no
  agent/status is emitted, so an ACP listener can't see a spurious idle that
  resolves a freshly-queued prompt as cancelled);
- after the synchronous setStatus('running') emit (window 2): a running listener
  can cancel in the gap before runTurn;
- in the step-start window (before runStep, after setAbort): a synchronous
  turn-start/step-start listener can cancel before any AbortController exists;
- at the continuation gate: a cancel during the continuation waterfall (the
  finished step's controller already cleared) ends the turn aborted.

The marker is ARMED only when there is something to cancel (running, an
in-flight step, or queued/steering work) — an idle no-op cancel cannot leave it
set to drop a later prompt — and RESET unconditionally once per loop iteration,
so it governs exactly one turn and never leaks onto the next prompt (even when a
send() lands in the cancelled turn's flush window).

ACP session/cancel now maps to agent.cancel() (keeping the synchronous
settlePrompt). Teardown/disconnect still use abort('disposed') until PR D, so
the ACP README narrows the remaining best-effort window to teardown only.

Tests (agent-loop/cancel.spec.ts) cover every window unit-level (the F1 hang
guard: a whenIdle() waiter registered before a pre-step cancel resolves; the F2
leak guard: idle cancel then a prompt runs; mid-step, continuation, both
pre-step windows, turn-start-listener, steering-cleared, marker-reset). ACP
turns.spec.ts adds the through-bridge tests with NO intervening whenIdle (idle
cancel→prompt runs; mid-stream cancel→immediate next prompt runs) and updates
the stale pre-step test to the queue-aware guarantee. The existing cancel
snapshot golden is byte-identical (it drives the new cancel() path end-to-end
through the real subprocess), so no new golden is needed. 100% coverage.

2026-06-20 04:51:32 +08:00

src

feat(agent): add queue-aware Agent.cancel() primitive

2026-06-20 04:51:32 +08:00

tests

feat(agent): add queue-aware Agent.cancel() primitive

2026-06-20 04:51:32 +08:00

package.json

feat: migrate to pnpm

2026-06-16 14:55:37 +08:00

README.md

feat(agent): add queue-aware Agent.cancel() primitive

2026-06-20 04:51:32 +08:00

tsconfig.json

Add abstract service interface packages

2026-06-11 10:54:06 +08:00

README.md

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 — record an already-constructed agent. Disposed with the calling fiber.
ctx.agents.get(id: string): Agent | undefined
ctx.agents.list(): Agent[]

Factory seam (creation)

Agent creation is provided by whichever plugin implements AgentFactory (phase 1: dsh-agent-loop), registered via setFactory. This keeps creation on the dsh-agent interface so consumers (UI, the ACP bridge) program against ctx.agents without depending on the concrete loop package.

ctx.agents.setFactory(factory: AgentFactory): () => void — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
ctx.agents.create(options: CreateAgentOptions): Agent — construct, start, AND register a new agent on a caller-supplied sessionId (with optional meta.cwd). Distinct from register (which only records). Throws if no factory is registered.
ctx.agents.resume(options: ResumeAgentOptions): Promise<Agent> — load a persisted session (session persistence) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.

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); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot injection turn so every event stays turn-enclosed (the turn-enclosure invariant)
agent.abort(reason?) — abort the in-flight step (the narrow, step-only verb)
agent.cancel(reason?) — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP session/cancel maps to this. Idle with nothing pending → a safe no-op.
agent.whenIdle() — resolve once the agent reaches quiescence after settling out of running (idle → immediately; disposed → awaits the loop exit), the signal a teardown awaits (abort() then await whenIdle()). Observes the transition without disposing the agent.
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.

README.md

dsh-agent

Service: AgentRegistry (ctx key: agents)

Public API

Factory seam (creation)

Events

Lifecycle (emit)

Turn/step boundaries (emit)

Interception seams (waterfall)

Streaming + tool (emit)

Agent interface (types.ts)

Extension points

What is NOT here (TODO)

Service: `AgentRegistry` (ctx key: `agents`)

Agent interface (`types.ts`)