Tianyi Cui
a2aa567371
core.md claimed to be the packages/core reference but opened on repo-wide type patterns and never documented the ownership vocabulary: AgentHandle, CreateAgentOptions, ResumeAgentOptions, and AgentFactory were TYPE_LINK_EXEMPTIONS pointing at a package README, invisible to the folder that calls itself the type reference. The page now reads spine map -> creation and ownership (AgentHandle pasted; the options and factory summarized with links into the generated registry section) -> the Agent handle (AgentStatus, AgentOptions, SteeringOutcome, SteeringReceipt, and SettleReason now pasted; the one settlement prose wall split by topic; delivery vocabulary ordered as a message travels) -> initiator -> interception -> a Sessions summary -> the ToolDefinition pointer -> an explicitly framed repo-wide patterns tail (the ...Map pattern, branded ids). The duplicate SessionEvent paste is gone -- session.md owns it and LINK_MAP follows -- the four ownership types moved from TYPE_LINK_EXEMPTIONS into LINK_MAP -> core.md, and three dead LINK_MAP entries (ContinuationDecision, ContinuationStop, HookContext) no longer name types absent from the source tree. The "what this page owns" meta-section folds into the intro. The subsystems README index silently lost tasks.md and session-reference.md on both language sides during a base absorption; the rows are restored and scripts/project-doc-site.spec.ts now fails when any page misses either side of the index (proven red on a removed row). tools.md links ToolSchema to its llm-streaming.md declaration instead of calling it core; subagent.md links AgentHandle and CreateAgentOptions.seed to the new section. A new Agent Note records the package-anchored page-scoping decision; the 2026-06-20 catalog note marks its spine-vs-seam rule superseded as the page-scoping rule while keeping the type-equiv mechanism current, and docs/AGENTS.md cites the new note.
4.1 KiB
Agent Note: Package-anchored subsystem pages and thin group READMEs
Status: implemented
English | 中文
Problem
The subsystems catalog scoped its front page by the spine-vs-seam rule: a type was "core" if the loop holds, derives, streams, or logs it on every turn. That rule selected types, not packages, so as the folder grew to forty-plus pages the front page became a cross-package grab-bag: LLM conversation vocabulary sat above the agent contracts, the creation/ownership vocabulary (AgentHandle, CreateAgentOptions, ResumeAgentOptions, AgentFactory) was documented nowhere in the folder because the generator exempted it to a package README, and a reader could not predict which page documents a type from where the type lives. Package-group READMEs meanwhile had no common shape — some carried sectioned tables, stray design essays, or trailing paragraphs that belonged on a subsystem page.
Decision
Every docs/subsystems/ page anchors to the package or package group that declares its vocabulary, and page membership follows the repository layout: core.md is the packages/core page (creation and ownership, the Agent handle with its delivery/cancellation/interception contracts, pointers to the group's dedicated pages), llm-streaming.md owns packages/llm end-to-end, and so on. Repo-wide type patterns (…Map → derived-union, branded ids) stay on core.md in an explicitly framed closing section rather than interleaved with the package content. This supersedes the spine-vs-seam rule as the page-scoping rule; the placement heuristic that survives is simpler: a type is documented where its declaring package's page is, and machinery keeps living with its machinery.
Every type a generated signature references must resolve somewhere in the folder: the agent ownership vocabulary moved from the generator's TYPE_LINK_EXEMPTIONS into LINK_MAP → core.md, so exemptions are reserved for genuinely service-local or vendored shapes. Each pasted declaration has one home (SessionEvent lives on session.md; core.md summarizes and links).
Every packages/<group>/README.md pair is a thin front door in one shape: a why-first intro paragraph, a package table (Package / Role / ctx key), and a closing pointer to the owning subsystems page. Load-bearing prose that outgrows that shape relocates to the owning subsystems page rather than being deleted.
The subsystems README indexes every page in the folder on both language sides; scripts/project-doc-site.spec.ts enforces one table row per page, so a page added by a later PR (or absorbed in a merge) cannot silently miss the index.
Alternatives considered
Keep the spine-vs-seam scoping rule. It answered "is this type core?" per type, which is why the front page accumulated types from four packages while missing half of packages/core/agent's public surface. Predictability by repository layout won.
A flat single-document catalog. Already rejected in the original catalog note; the growth to forty-one pages confirmed that verdict.
Document ownership vocabulary only in package READMEs (the exemption status quo). This left AgentHandle and the create/resume options invisible to the folder that claims to be the type reference, and the generated Types: footers could not link them.
Consequences
- Which page documents a type is predictable from
packages/<group>/; the subsystems README is a complete index enforced by test. - Generated signature footers link the agent ownership vocabulary instead of silently exempting it.
verify-type-equiv's 1:1 manifest keeps each paste single-homed; the duplicateSessionEventpaste is gone.- The original catalog note remains the owner of the
ts type-equivdrift-gate mechanism; only its page-scoping rule is superseded here.