Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(subsystems): open core.md on agent creation/ownership and the Agent contract; enforce a complete folder index

Browse Source 
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.
This commit is contained in:
Tianyi Cui
2026-08-03 16:34:00 +08:00
parent aa0ca6c836
commit a2aa567371
46 changed files with 1126 additions and 1034 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
scripts/gen-cordis-catalog.ts
View File

@@ -154,16 +154,17 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
export const LINK_MAP: Readonly<Record<string, string>> = {
Agent: 'core.md',
AgentCancelCause: 'core.md',
AgentFactory: 'core.md',
AgentHandle: 'core.md',
AgentOptions: 'core.md',
AgentStatus: 'core.md',
ContentBlock: 'llm-streaming.md',
ContinuationDecision: 'core.md',
ContinuationStop: 'core.md',
CreateAgentOptions: 'core.md',
GenerateOptions: 'llm-streaming.md',
InboxItem: 'core.md',
InboxPlacement: 'core.md',
MessageId: 'llm-streaming.md',
HookContext: 'core.md',
ResumeAgentOptions: 'core.md',
SettleReason: 'core.md',
AdapterRegistrationHandle: 'llm-streaming.md',
DirectoryRegistrationHandle: 'llm-streaming.md',
@@ -188,7 +189,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
PreparedReferencedMessage: 'session-reference.md',
SessionReferenceCandidate: 'session-reference.md',
SessionReferenceInput: 'session-reference.md',
SessionEvent: 'core.md',
SessionEvent: 'session.md',
SessionId: 'core.md',
SessionStartSource: 'core.md',
SessionLogSnapshot: 'session-query.md',
@@ -410,18 +411,15 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
/** Project types deliberately documented outside the subsystems catalog. */
export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
z: 'schemastery schema constructor is owned by vendor/schemastery (vendored upstream)',
BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
ConsumeTokenRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
InsertTextRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
ManualCompactAgentContext: 'manual compaction service input is owned by packages/compact/compact/src/index.ts',
CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
DomainImpl: 'domain implementation contract is owned by packages/storage/storage-domain/README.md',
CommandExecution: 'executor return contract is owned by packages/interaction/commands/src/index.ts',
'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
@@ -437,7 +435,6 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
SubagentRunEndInfo: 'event payload contract is owned by packages/subagent/subagent/src/types.ts',