simplify(agent): drop the unused public Agent.abort(), keep whenIdle()

The public Agent handle exposed abort() (step-only) and cancel() (queue-aware).
No production caller used abort() — ACP maps session/cancel to cancel(), and
lifecycle owners tear down via AgentHandle.dispose(); the loop's own stop paths
abort their per-step AbortController directly. So abort() is latent generality
that keeps a private loop mechanic public.

RFC-premise correction: the public-agent-stop-surface RFC proposed removing
whenIdle() too. Implementation found whenIdle() load-bearing — a real
quiescence primitive with a deliberate loop contract (settle-without-transition,
the replacement-turn race) and ACP test consumers; its proposed replacement
("observe the running->idle transition") is exactly the async-state race
AGENTS.md warns against. So only abort() is removed; whenIdle() stays. The RFC
is amended on the way to implemented/ to record the narrowed scope, and the new
AGENTS.md "RFCs are proposals, not golden truth" principle (PR1) gets its
worked example.

- Remove Agent.abort() from the interface + the ReactLoopAgent impl; the no-arg
  'aborted' default goes with it (cancel() keeps its 'cancelled' default).
- Migrate tests: empty-queue abort() -> cancel(reason); the two review-fixes
  tests whose subject is the in-flight step's AbortController drive that
  controller directly via the private currentAbort field (cancel() would clear
  the inbox and destroy the queued steering one of them proves survives a step
  abort). The no-arg-default test is dropped (cancel()'s default is already
  covered in cancel.spec.ts).
- Resulting public stop surface: cancel() + whenIdle(). Update agent/agent-loop
  READMEs, architecture.md, core.md type-equiv, the extension cookbook, the
  lifecycle RFC (short note), and the proposed ACP RFC.

Implements docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md

packages/core/agent-loop/README.md

@@ -68,7 +68,7 @@ forever:
 
 Error containment: a throwing plugin ends the **turn**, never the loop. Dispose mid-turn emits `agent/status('disposed')` and ends with reason `disposed`. A step that hits the model's output-token ceiling makes the turn end `max-tokens` (the rule: any `max-tokens` step in the turn surfaces as `max-tokens`; `disposed`/`aborted`/`error` still take precedence) — distinct from a clean `completed` stop.
 
-Cancellation: `agent.abort()` aborts only the in-flight step; `agent.cancel()` is the broad verb — it clears the queued + steering FIFOs, aborts the in-flight step, and drives a turn-scoped marker the driver checks at every point a turn could start or continue (right after the idle wait, after the `running` flip, before each step, and at the continuation gate) so a turn about to start is dropped. A cancelled turn ends `aborted`; a queued-but-not-started prompt never runs and cannot be batched into the cancelled turn. The marker is reset once per loop iteration, so a cancel governs exactly one turn and never leaks onto a later prompt.
+Cancellation: `agent.cancel()` is the single public stop primitive — it clears the queued + steering FIFOs, aborts the in-flight step, and drives a turn-scoped marker the driver checks at every point a turn could start or continue (right after the idle wait, after the `running` flip, before each step, and at the continuation gate) so a turn about to start is dropped. A cancelled turn ends `aborted`; a queued-but-not-started prompt never runs and cannot be batched into the cancelled turn. The marker is reset once per loop iteration, so a cancel governs exactly one turn and never leaks onto a later prompt. (The loop still aborts its own per-step `AbortController` directly on disposal and from `cancel()`; that controller is loop-internal, not a public verb.)
 
 ### What is NOT here
 

packages/core/agent-loop/src/agent.ts

@@ -191,10 +191,6 @@ export class ReactLoopAgent implements Agent {
     }
   }
 
-  abort(reason?: string): void {
-    this.currentAbort?.abort(reason ?? 'aborted')
-  }
-
   cancel(reason?: string): void {
     // Arm-gate: only mark a cancellation when there is actually work to cancel —
     // a running turn, an in-flight step, or queued/steering work. An idle cancel
@@ -233,7 +229,7 @@ export class ReactLoopAgent implements Agent {
    * running→idle/disposed transition, resolving on `idle` directly (the turn
    * fully ended) or chaining {@link done} on `disposed` (wait for the loop to
    * actually exit). Implements the {@link Agent.whenIdle} contract used by
-   * teardown (`abort()` then `await whenIdle()`).
+   * teardown (handle disposal aborts in-flight work, then awaits `whenIdle()`).
    */
   whenIdle(): Promise<void> {
     if (this._status === 'disposed') return this.done

packages/core/agent-loop/src/loop.ts

@@ -435,7 +435,7 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
         if (handle.isDisposed()) {
           reason = { kind: 'disposed' }
         } else if (abort.signal.aborted) {
-          /* v8 ignore next -- abort.signal.reason always set by agent.abort() which provides a default */
+          /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
           reason = { kind: 'aborted', reason: String(abort.signal.reason ?? 'aborted') }
         } else {
           failTurn(error)
@@ -590,7 +590,7 @@ async function runStep(
   // --- Model call (streaming-first; raw chunks are the replay record) ---
   const assembler = new BlockAssembler()
   for await (const chunk of ctx.llm.stream(request)) {
-    /* v8 ignore next -- signal.reason always set by agent.abort() which provides a default */
+    /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
     if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
     session.append('assistant/chunk', { turn, step, chunk })
     ctx.emit('agent/stream-chunk', agent, turn, step, chunk)
@@ -633,7 +633,7 @@ async function runStep(
   // isError results, so abort is re-checked around every call here.
   const toolCalls = message.content.filter(block => block.type === 'tool-call')
   for (const call of toolCalls) {
-    /* v8 ignore next -- signal.reason always set by agent.abort() which provides a default */
+    /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
     if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
     session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments })
     let parsedArguments: unknown
@@ -664,7 +664,7 @@ async function runStep(
     })
     // signal CAN flip during the await above (abort() inside a tool);
     // the analyzer can't see through the await boundary.
-    /* v8 ignore start -- signal.reason default unreachable via agent.abort() */
+    /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
     /* v8 ignore stop */

packages/core/agent-loop/tests/agent.spec.ts

@@ -288,7 +288,7 @@ describe('ReactLoopAgent', () => {
     expect(settled).toBe(false)
 
     await waitForStatus(ctx, agent, 'running')
-    agent.abort('done')
+    agent.cancel('done')
     await idle
     expect(settled).toBe(true)
     expect(agent.status).toBe('idle')
@@ -430,20 +430,4 @@ describe('ReactLoopAgent', () => {
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('agent/status listener threw on idle'))
     warn.mockRestore()
   })
-
-  it('abort() resolves reason to "aborted" when no reason provided', async () => {
-    const adapter = new MockAdapter(['hang'])
-    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
-
-    const reasons: { kind: string; reason?: string }[] = []
-    ctx.on('agent/turn-end', (_agent, _turn, reason) => void reasons.push(reason))
-
-    send(agent, 'go')
-    await new Promise(r => setTimeout(r, 30))
-    agent.abort() // no reason string
-    await waitForIdle(ctx, agent)
-
-    expect(reasons[0]).toMatchObject({ kind: 'aborted', reason: 'aborted' })
-  })
 })

packages/core/agent-loop/tests/loop.spec.ts

@@ -318,7 +318,7 @@ describe('agent loop', () => {
     expect(adapter.requests[0]!.model).toBe('other-model')
   })
 
-  it('abort() mid-stream ends the turn with reason aborted', async () => {
+  it('cancel() mid-stream ends the turn with reason aborted', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -327,10 +327,10 @@ describe('agent loop', () => {
     ctx.on('agent/turn-end', (_agent, _turn, reason) => void reasons.push(reason))
 
     send(agent, 'go')
-    // wait until the stream is hanging, then abort
+    // wait until the stream is hanging, then cancel
     await new Promise(r => setTimeout(r, 30))
     expect(agent.status).toBe('running')
-    agent.abort('user interrupt')
+    agent.cancel('user interrupt')
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }])

packages/core/agent-loop/tests/review-fixes.spec.ts

@@ -92,7 +92,7 @@ describe('HIGH: session log records what agent/step-result actually produced', (
 })
 
 describe('HIGH: abort during tool execution ends the turn', () => {
-  it('abort() inside a tool prevents both remaining tools and the next model step', async () => {
+  it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => {
     const adapter = new MockAdapter([
       // model asks for two tool calls in one step
       [
@@ -113,7 +113,11 @@ describe('HIGH: abort during tool execution ends the turn', () => {
       parameters: {},
       async execute() {
         executed.push('aborter')
-        agent.abort('user interrupt')
+        // Fire the in-flight step's AbortController directly (the loop registers
+        // it on the agent). This is the bare step-abort path — distinct from
+        // cancel(), which would also clear the inbox; here the subject is the
+        // loop's response to its running step being aborted mid-tool.
+        ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt')
         return [{ type: 'text', text: 'done' }]
       },
     }))
@@ -228,7 +232,12 @@ describe('HIGH: steering from late extension points is never stranded', () => {
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     agent.steer([{ type: 'text', text: 'redirect' }])
-    agent.abort('user interrupt')
+    // Abort ONLY the in-flight step, via its AbortController directly — NOT
+    // cancel(), which clears the inbox and would drop the queued steering this
+    // test proves survives a step abort. There is no public step-only abort
+    // verb (cancel() is the only public stop primitive), so reach the private
+    // controller the loop registered.
+    ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt')
     await waitForIdle(ctx, agent)
 
     // a new turn ran with the steering content delivered as a message

packages/core/agent/README.md

@@ -56,9 +56,8 @@ 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](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md))
-- `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.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. The single public stop primitive. 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 (a lifecycle owner disposes the handle, which aborts in-flight work then awaits this). Observes the transition without disposing the agent.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`
 
 ### Extension points

packages/core/agent/src/types.ts

@@ -79,12 +79,8 @@ export interface Agent {
    */
   inject(content: ContentBlock[], options?: SendOptions): void
 
-  /** Abort the in-flight step (if any); the turn ends with reason 'aborted'. */
-  abort(reason?: string): void
-
   /**
-   * Cancel ALL pending work for the agent — the narrower {@link abort} kills
-   * only the in-flight step. `cancel()`:
+   * Cancel ALL pending work for the agent. `cancel()`:
    *
    * - clears the queued FIFO (un-started prompts never run) and the steering
    *   FIFO (steering for the cancelled turn is dropped, not re-enqueued);
@@ -104,11 +100,11 @@ export interface Agent {
   /**
    * Resolve once the agent has reached quiescence after settling out of
    * `running`, or immediately if it is already idle with no queued work. The
-   * quiescence signal a teardown awaits: `agent.abort()` then
-   * `await agent.whenIdle()` guarantees queued/running work has fully stopped
-   * before the caller proceeds (a closing ACP connection, a disposing UI
-   * plugin), rather than returning while the driver is still streaming or about
-   * to start a queued turn.
+   * quiescence signal a teardown awaits: a lifecycle owner disposes the agent
+   * through its `AgentHandle` (which aborts in-flight work then awaits this), so
+   * the caller proceeds only after queued/running work has fully stopped (a
+   * closing ACP connection, a disposing UI plugin) rather than returning while
+   * the driver is still streaming or about to start a queued turn.
    *
    * "Quiescence", not merely "status changed": a disposed agent emits
    * `agent/status('disposed')` from inside its disposer, BEFORE the driver loop

packages/core/agent/tests/agent.spec.ts

@@ -13,7 +13,6 @@ function stubAgent(rawId: string): Agent {
     send() {},
     steer() {},
     inject() {},
-    abort() {},
     cancel() {},
     whenIdle() { return Promise.resolve() },
   }