Files

T

Tianyi Cui 7702a33531 docs(AGENTS): rewrite the root standing orders to the 1,500-word budget

Applies the documentation standard to its biggest offender. Every rule
survives as one to three lines plus a link to its durable home; the
stories, duplicate statements, and re-narrations go:

- Situational clusters evict to new homes: docs/testing.md (tiers,
  with-key policy, real-over-mock, world-verification, real-entry-path
  guards), docs/defensive-patterns.md (the bug-class rules), and
  docs/cookbook/responding-to-pr-review-on-a-stack.md (the stacked-PR
  review procedure).
- Doc-authoring rules consolidate into docs/AGENTS.md § Writing rules
  (current-state-never-history, md-wrap, ts-block compilation, @mode,
  catalog same-change, pair same-change).
- packages/README.md drops to the group table + the extension-vs-bundle
  dependency rule; the hand ASCII graph yields to the generated
  module-graph.md; group READMEs are the canonical per-package map.
- packages/AGENTS.md keeps only its packages-specific rules (export
  shape, ctx.get, real-Loader coverage); examples/AGENTS.md repoints
  its with-key-policy link; rfc/README.md loses a narrated-history
  aside; dsh-code-review / dsh-find-simplifications / verify-md-wrap
  references follow the moved content.
- Budget manifest ratchets: AGENTS.md 8200 -> 1500 (now 1,495 words),
  packages/README.md 1900 -> 600, packages/AGENTS.md 600 -> 450; the
  two new eviction docs join the budget set (testing 800, defensive
  550); docs/AGENTS.md raises 1000 -> 1250 for the absorbed writing
  rules (the one justified increase). The doc-tiers RFC's deferred list
  prunes the two items this change ships.

2026-07-04 14:22:47 +08:00

5.2 KiB

Raw Blame History

RFC: Keep one public stop primitive

Status: implemented (proposed 2026-06-20; accepted in amended form — whenIdle() retained)

Implementation note (scope narrowed from the original proposal). This RFC proposed removing BOTH abort() and whenIdle() from the public Agent handle. Only abort() was removed. Validating the premise against the code (AGENTS.md "RFCs are proposals, not golden truth") found whenIdle() to be a load-bearing quiescence primitive, not dead surface: it is the settle signal in several ACP tests (packages/ui/acp/tests/{edges,turns,dispose}.spec.ts) and is backed by a deliberate loop contract (settle waiters without a status transition; handle the replacement-turn race). The RFC's suggested migration — have consumers observe the running→idle transition by hand — is exactly the brittle hand-rolled path the defensive patterns warns against ("Async state is not synchronous state"). Deleting a clean primitive to push every consumer onto that is a net loss, so whenIdle() stays. abort() was genuinely dead public surface (no production caller; the loop aborts its own AbortController directly), so it was removed as proposed. The text below is amended to describe what shipped.

Problem

The public Agent handle exposed two overlapping ways to stop in-flight work: abort(reason?) and cancel(reason?). abort() killed only the in-flight step and left queued work alone; cancel() clears queued and steering work, aborts the running step, and handles the pre-step race. In production, ACP uses cancel() for session/cancel, while lifecycle owners tear down agents through AgentHandle.dispose(). No production caller needed bare abort().

The abort()/cancel() distinction is real — abort() preserves queued prompts and steering while cancel() drops them — but no shipping code called the public abort() verb. The loop's own stop paths (cancel() and disposal) abort the current AbortController directly rather than routing through Agent.abort(). Most tests that called abort() interrupt an empty queue and switch to cancel(reason); the steering re-delivery test that deliberately depends on queue preservation drives the in-flight AbortController directly, because cancel() would drop the queued steering it is trying to prove survives a step abort. The no-argument abort() default reason ('aborted') is deleted with the verb rather than preserved by accident; cancel() keeps its own 'cancelled' default.

The extra surface area made the loop carry a public verb that is mostly a teardown internal: abort() had to be documented as distinct from queue-aware cancellation even though a UI cancellation almost always wants the broader operation.

Proposal

Keep cancel() as the only public stop primitive on Agent. Lifecycle owners use AgentHandle.dispose() to stop and unregister an agent; non-owners use cancel() to abandon current and queued work. The implementation keeps a private abort controller, but it is not part of the plugin-facing Agent contract.

whenIdle() is retained as the public quiescence-observation primitive (resolve once the agent settles out of running, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop completing without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public seam (packages/ui/acp/tests, packages/core/agent-loop/tests); the production ACP bridge owns its agents and tears them down through AgentHandle.dispose(), so packages/ui/acp/src itself has no whenIdle() call.

Delete public abort(), the tests that exercise it as standalone API, and the docs that describe step-only abort as an embedding feature. Empty-queue abort tests migrate to cancel(reason) where they still prove cancellation behavior; tests whose subject is the loop's internal AbortController behavior drive that controller directly via an in-package typed cast to the private field; tests that only pin the removed no-arg abort() default go away with the method. The disposer remains async and still waits for the loop to stop.

Acceptance criteria

Agent exposes no public abort(); cancel(), whenIdle(), and steer() remain part of the surface.
ACP cancellation continues to call cancel().
Agent teardown continues to await quiescence through handle disposal, and whenIdle() still resolves on quiescence for non-owner observers.
Tests cover cancellation and disposal as the two supported stop paths.

What we give up

A future plugin cannot abort only the current model/tool step while preserving queued prompts through the public interface. If that use case becomes real, it should return with a named consumer and a narrower contract. Today it is latent generality that keeps a private loop mechanic public.

This RFC only removes the redundant stop verb. Mid-turn steering remains an intentional message path; quiescence observation remains via whenIdle(). The resulting public surface is send(), steer(), inject(), cancel(), whenIdle(), status, options, session, and identity.

5.2 KiB Raw Blame History