Merge latest origin/master into compact-post-step-overflow-recovery

# Conflicts: # docs/agent-lifecycle.md # docs/architecture.md # docs/cookbook/extension-cookbook.i18n.yaml # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/event-producer-consumer.md # docs/rfc/INDEX.md # docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md # docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml # docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md # docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md # docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md # docs/rfc/implemented/feature/2026-07-07-session-prefix.md # packages/compact/compact-basic/README.md # packages/compact/compact-basic/src/config.ts # packages/compact/compact-basic/src/index.ts # packages/compact/compact-basic/src/summarizer.ts # packages/compact/compact-basic/tests/compact-basic.spec.ts # packages/compact/compact-basic/tests/compact-loop-repro.spec.ts # packages/compact/compact/README.md # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-loop/src/loop.ts # packages/core/agent-loop/tests/cancel.spec.ts # packages/llm/llm-deepseek/src/adapter.ts # packages/llm/llm-pi-ai/README.md # packages/llm/llm-pi-ai/src/stream.ts # packages/llm/llm-pi-ai/tests/convert.spec.ts # packages/llm/llm/README.md # packages/llm/llm/src/index.ts # packages/llm/llm/tests/service.spec.ts # scripts/gen-doc-graphs.ts
2026-07-19 12:06:23 +08:00
parent 231aeabe55 383a305bd4
commit 7be78c7d4c
814 changed files with 42348 additions and 10067 deletions
--- a/packages/cordis/tool-cordis/package.json
+++ b/packages/cordis/tool-cordis/package.json
@@ -33,6 +33,7 @@
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-scope": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -54,9 +54,9 @@ export interface TypeApiEntry {
 export const SERVICE_API: readonly ServiceApiEntry[] = [
  {
    key: 'agentLoop',
-    summary: 'Concrete ReactLoopAgent factory and driver service.',
+    summary: 'Concrete agent factory and driver service.',
    methods: [
-      'create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): ReactLoopAgent',
+      'create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): Agent',
      'async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>',
      'async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>',
    ],
@@ -69,10 +69,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      'async create(options: CreateAgentOptions): Promise<AgentHandle>',
      'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
      'register(agent: Agent): () => void',
-      'enter(agent: Agent): () => void',
+      'enter(agent: Agent, owner: Agent | undefined): () => void',
      'announce(agent: Agent): void',
-      'get(id: AgentId): Agent | undefined',
+      'get(id: SessionId): Agent | undefined',
+      'isOwnedBy(id: SessionId, owner: Agent): boolean',
      'list(): Agent[]',
+      'roots(): Agent[]',
    ],
  },
  {
@@ -91,6 +93,15 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      'abstract start(spec: BashExecSpec): BashProcess',
    ],
  },
+  {
+    key: 'bashEnv',
+    summary: 'Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables.',
+    methods: [
+      'register(contributor: BashEnvContributor): () => void',
+      'collect(execution: ToolExecution): DshEnvironment',
+      'list(): BashEnvVariableInfo[]',
+    ],
+  },
  {
    key: 'codeRuntime',
    summary: 'Registers one `ctx.codeRuntime` implementation.',
@@ -103,15 +114,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
    summary: 'Abstract compaction service.',
    methods: [
      'abstract compactIfNeeded( agent: CompactAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>',
-      'abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
+      'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
    ],
  },
  {
    key: 'fs',
    summary: 'Abstract filesystem provider.',
    methods: [
-      'abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>',
+      'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
      'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
+      'abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>',
      'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
      'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
      'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>',
@@ -123,8 +135,9 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
    key: 'llm',
    summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
    methods: [
-      'registerAdapter(models: string[], adapter: LlmAdapter): () => void',
-      'models(): string[]',
+      'registerAdapter(providers: string[], adapter: LlmAdapter): () => void',
+      'listProviders(): LlmProviderInfo[]',
+      'async listModels(provider: string): Promise<LlmModelInfo[]>',
      'stream(options: GenerateOptions): AsyncIterable<StreamChunk>',
    ],
  },
@@ -149,6 +162,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
    key: 'sessionPersistence',
    summary: 'Durable append-only session storage.',
    methods: [
+      'abstract locate(meta: SessionHeader): SessionLocation | undefined',
      'abstract create(meta: SessionHeader): Promise<void>',
      'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
      'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
@@ -157,10 +171,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'sessionQuery',
-    summary: 'Live-preferred logical-corpus and exact-event read service.',
+    summary: 'Live-preferred logical-corpus exact-read and relationship-tracing service.',
    methods: [
      'listSessions(): Promise<SessionRecord[]>',
      'async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>',
+      'async traceSession(sessionId: SessionId): Promise<SessionLineageTrace>',
+      'async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>',
      'async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>',
    ],
  },
@@ -188,6 +204,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      'async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>',
    ],
  },
+  {
+    key: 'spillStore',
+    summary: 'Abstract spill storage service.',
+    methods: [
+      'abstract saveText(input: SaveTextSpill): Promise<SpillRef>',
+    ],
+  },
  {
    key: 'subagents',
    summary: 'Named provider registry and capability-checked start surface.',
@@ -239,6 +262,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      'guard(guard: ToolGuard): () => void',
      'get(name: string, scope?: ScopeKey): ToolDefinition | undefined',
      'schemas(scope?: ScopeKey): ToolSchema[]',
+      'executionMode(exec: ToolExecutionInput): ToolExecutionMode',
      'async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>',
    ],
  },
@@ -271,6 +295,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [

 /** Every harness event, sorted by name. */
 export const EVENT_API: readonly EventApiEntry[] = [
+  {
+    name: 'agent-loop/config-start-failed',
+    mode: 'emit',
+    signature: '\'agent-loop/config-start-failed\'(sessionId: SessionId, error: unknown): void',
+    summary: 'A declarative agent entry failed before it could publish a live agent.',
+  },
  {
    name: 'agent/created',
    mode: 'emit',
@@ -523,7 +553,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
 export const TYPE_API: readonly TypeApiEntry[] = [
  {
    name: 'Agent',
-    declaration: 'export interface Agent {\n    readonly id: AgentId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: SendOptions): void;\n    cancel(reason?: string): void;\n    whenIdle(): Promise<void>;\n}',
+    declaration: 'export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: InjectOptions): void;\n    cancel(reason?: string): void;\n    whenIdle(): Promise<void>;\n}',
  },
  {
    name: 'AgentFactory',
@@ -533,13 +563,9 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'AgentHandle',
    declaration: 'export interface AgentHandle {\n    agent: Agent;\n    dispose(): Promise<void>;\n}',
  },
-  {
-    name: 'AgentId',
-    declaration: 'export type AgentId = Branded<\'AgentId\'>;',
-  },
  {
    name: 'AgentOptions',
-    declaration: 'export interface AgentOptions {\n    model?: string;\n}',
+    declaration: 'export interface AgentOptions {\n    provider?: string;\n    model?: string;\n}',
  },
  {
    name: 'AgentStatus',
@@ -585,13 +611,29 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'AssembledSection',
    declaration: 'export interface AssembledSection {\n    name: string;\n    text: string;\n}',
  },
+  {
+    name: 'AssistantProvenance',
+    declaration: 'export interface AssistantProvenance {\n    provider: string;\n    model: string;\n    replayState?: unknown;\n}',
+  },
+  {
+    name: 'BashEnvContributor',
+    declaration: 'export interface BashEnvContributor {\n    name: string;\n    variables: Readonly<Record<DshEnvironmentKey, BashEnvVariable>>;\n    resolve(execution: ToolExecution): Readonly<Partial<Record<DshEnvironmentKey, string>>>;\n}',
+  },
+  {
+    name: 'BashEnvVariable',
+    declaration: 'export interface BashEnvVariable {\n    description: string;\n}',
+  },
+  {
+    name: 'BashEnvVariableInfo',
+    declaration: 'export interface BashEnvVariableInfo extends BashEnvVariable {\n    contributor: string;\n    key: DshEnvironmentKey;\n}',
+  },
  {
    name: 'BashExecRequest',
-    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    sandboxMode?: SandboxMode | undefined;\n}',
+    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    stdoutMaxBytes?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxMode?: SandboxMode | undefined;\n}',
  },
  {
    name: 'BashExecSpec',
-    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    sandboxMode: SandboxMode | undefined;\n}',
+    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    stdoutMaxBytes: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxMode: SandboxMode | undefined;\n}',
  },
  {
    name: 'BashProcess',
@@ -647,7 +689,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'CompactAgentContext',
-    declaration: 'export interface CompactAgentContext {\n    session: Session;\n    options: {\n        model?: string;\n    };\n}',
+    declaration: 'export interface CompactAgentContext {\n    session: Session;\n    options: {\n        provider?: string;\n        model?: string;\n    };\n}',
  },
  {
    name: 'CompactionResult',
@@ -673,9 +715,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'ContentBlockType',
    declaration: 'export type ContentBlockType = keyof ContentBlockMap;',
  },
+  {
+    name: 'ContextEnvelope',
+    declaration: 'export type ContextEnvelope = \'context\' | \'raw\';',
+  },
  {
    name: 'CreateAgentOptions',
-    declaration: 'export interface CreateAgentOptions {\n    readonly agentId: AgentId;\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
+    declaration: 'export interface CreateAgentOptions {\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
  },
  {
    name: 'CreateSessionOptions',
@@ -689,6 +735,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'DiffResultView',
    declaration: 'export interface DiffResultView {\n    card: \'diff\';\n    title?: string;\n    diffs: FileDiff[];\n}',
  },
+  {
+    name: 'DshEnvironment',
+    declaration: 'export type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>;',
+  },
+  {
+    name: 'DshEnvironmentKey',
+    declaration: 'export type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`;',
+  },
  {
    name: 'EpochHeader',
    declaration: 'export interface EpochHeader {\n    config: LlmCallConfig;\n    system?: string;\n    tools?: ToolSchema[];\n    messagePrefix?: Message[];\n}',
@@ -725,6 +779,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'FsInfo',
    declaration: 'export interface FsInfo {\n    version: FsVersion;\n    type: \'file\' | \'directory\' | \'other\';\n    size?: number;\n}',
  },
+  {
+    name: 'FsPathInfo',
+    declaration: 'export interface FsPathInfo {\n    version: FsVersion;\n    type: \'file\' | \'directory\' | \'symlink\' | \'other\';\n    size?: number;\n}',
+  },
  {
    name: 'FsTarget',
    declaration: 'export interface FsTarget {\n    targetKey: FsTargetKey;\n    displayPath: string;\n}',
@@ -747,7 +805,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'GenerateOptions',
-    declaration: 'export interface GenerateOptions {\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n}',
+    declaration: 'export interface GenerateOptions {\n    provider: string;\n    model: string;\n    messages: Message[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<\'SessionId\'>;\n}',
  },
  {
    name: 'GenericCallView',
@@ -759,15 +817,31 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'HookContext',
-    declaration: 'export interface HookContext {\n    content: ContentBlock[];\n    source: MessageSource;\n}',
+    declaration: 'export interface HookContext {\n    content: ContentBlock[];\n    source: MessageSource;\n    envelope?: ContextEnvelope;\n    meta?: JsonValue;\n}',
+  },
+  {
+    name: 'InjectOptions',
+    declaration: 'export interface InjectOptions extends SendOptions {\n    envelope?: ContextEnvelope;\n    meta?: JsonValue;\n}',
+  },
+  {
+    name: 'JsonValue',
+    declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n    [key: string]: JsonValue;\n};',
  },
  {
    name: 'LlmCallConfig',
-    declaration: 'export interface LlmCallConfig {\n    model: string;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}',
+    declaration: 'export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}',
+  },
+  {
+    name: 'LlmModelInfo',
+    declaration: 'export interface LlmModelInfo {\n    provider: string;\n    id: string;\n    name: string;\n    description?: string;\n}',
+  },
+  {
+    name: 'LlmProviderInfo',
+    declaration: 'export interface LlmProviderInfo {\n    id: string;\n    name: string;\n}',
  },
  {
    name: 'Message',
-    declaration: 'export interface Message {\n    role: \'system\' | \'user\' | \'assistant\';\n    content: ContentBlock[];\n}',
+    declaration: 'export interface Message {\n    role: \'system\' | \'user\' | \'assistant\';\n    content: ContentBlock[];\n    provenance?: AssistantProvenance;\n}',
  },
  {
    name: 'MessageSource',
@@ -799,7 +873,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'ResumeAgentOptions',
-    declaration: 'export interface ResumeAgentOptions {\n    readonly agentId: AgentId;\n    readonly resumeSessionId: SessionId;\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
+    declaration: 'export interface ResumeAgentOptions {\n    readonly resumeSessionId: SessionId;\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
  },
  {
    name: 'SandboxEnforcement',
@@ -813,6 +887,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'SandboxPolicy',
    declaration: 'export interface SandboxPolicy {\n    mode: ConfinedSandboxMode;\n    workspaceRoot: string;\n}',
  },
+  {
+    name: 'SaveTextSpill',
+    declaration: 'export interface SaveTextSpill {\n    owner: SpillOwner;\n    source: SpillSource;\n    suggestedName: string;\n    content: string;\n}',
+  },
  {
    name: 'ScopeKey',
    declaration: 'export type ScopeKey = object;',
@@ -827,7 +905,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'SessionEventMap',
-    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: E /* …truncated — full shape in source */',
+    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        provenance: AssistantProvenance;\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource; /* …truncated — full shape in source */',
  },
  {
    name: 'SessionEventReadRequest',
@@ -841,6 +919,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'SessionEventSurface',
    declaration: 'export type SessionEventSurface = \'current\' | \'shadowed\' | \'log-only\';',
  },
+  {
+    name: 'SessionEventTrace',
+    declaration: 'export interface SessionEventTrace {\n    target: SessionEventRecord;\n    replacedBy?: number;\n    replacementChain: number[];\n    replacedEventSeqs: number[];\n    sourceEventSeqs: number[];\n    derivedEventSeqs: number[];\n}',
+  },
+  {
+    name: 'SessionEventTraceRequest',
+    declaration: 'export interface SessionEventTraceRequest {\n    sessionId: SessionId;\n    seq: number;\n}',
+  },
  {
    name: 'SessionEventType',
    declaration: 'export type SessionEventType = keyof SessionEventMap;',
@@ -861,6 +947,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'SessionId',
    declaration: 'export type SessionId = Branded<\'SessionId\'>;',
  },
+  {
+    name: 'SessionLineageNode',
+    declaration: 'export interface SessionLineageNode {\n    session: SessionRecord;\n    descendants: SessionLineageNode[];\n}',
+  },
+  {
+    name: 'SessionLineageTrace',
+    declaration: 'export type SessionLineageTrace = {\n    target: SessionRecord;\n    ancestors: SessionRecord[];\n    descendants: SessionLineageNode[];\n} & ({\n    complete: true;\n    root: SessionRecord;\n} | {\n    complete: false;\n    unresolvedParentId: SessionId;\n});',
+  },
+  {
+    name: 'SessionLocation',
+    declaration: 'export interface SessionLocation {\n    readonly kind: string;\n    readonly path: string;\n}',
+  },
  {
    name: 'SessionRecord',
    declaration: 'export interface SessionRecord {\n    header: SessionHeader;\n    live: boolean;\n    persisted: boolean;\n}',
@@ -897,9 +995,25 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'SkillSummary',
    declaration: 'export interface SkillSummary {\n    readonly name: string;\n    readonly description: string;\n    readonly whenToUse?: string;\n    readonly disableModelInvocation?: boolean;\n    readonly source: SkillSource;\n    readonly provider: string;\n    readonly resourceBase?: SkillResourceBase;\n}',
  },
+  {
+    name: 'SpillLocator',
+    declaration: 'export type SpillLocator = Branded<\'SpillLocator\'>;',
+  },
+  {
+    name: 'SpillOwner',
+    declaration: 'export interface SpillOwner {\n    sessionId: SessionId;\n}',
+  },
+  {
+    name: 'SpillRef',
+    declaration: 'export interface SpillRef {\n    locator: SpillLocator;\n    bytes: number;\n    retrievalHint: string;\n}',
+  },
+  {
+    name: 'SpillSource',
+    declaration: 'export interface SpillSource {\n    toolName: string;\n    callId: CallId;\n    label: string;\n}',
+  },
  {
    name: 'StreamChunk',
-    declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n};',
+    declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n    replayState?: unknown;\n};',
  },
  {
    name: 'StructuredOutputSchema',
@@ -931,7 +1045,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'SubagentRun',
-    declaration: 'export interface SubagentRun {\n    readonly id: AgentId;\n    readonly result: Promise<SubagentResult>;\n    dispose(): Promise<void>;\n    sendMessage?(content: ContentBlock[]): void;\n    resume?(content: ContentBlock[]): Promise<SubagentRun>;\n}',
+    declaration: 'export interface SubagentRun {\n    readonly id: SessionId;\n    readonly localAgent: Agent | undefined;\n    readonly result: Promise<SubagentResult>;\n    dispose(): Promise<void>;\n    sendMessage?(content: ContentBlock[]): void;\n    resume?(content: ContentBlock[]): Promise<SubagentRun>;\n}',
  },
  {
    name: 'SubagentStartRequest',
@@ -1001,10 +1115,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'TerminalResultView',
    declaration: 'export interface TerminalResultView {\n    card: \'terminal\';\n    title?: string;\n    output?: string;\n    exitCode?: number;\n    signal?: string;\n}',
  },
-  {
-    name: 'TodoItem',
-    declaration: 'export interface TodoItem {\n    content: string;\n    status: \'pending\' | \'in_progress\' | \'completed\';\n}',
-  },
  {
    name: 'TokenMeasurement',
    declaration: 'export interface TokenMeasurement {\n    readonly logRevision: number;\n    readonly baseline: TokenMeasurementBaseline;\n    readonly surfaceDeltaTokens: number;\n    readonly totalTokens: number;\n    readonly surfaceTokens: number;\n    readonly nodes: readonly TokenSurfaceNode[];\n}',
@@ -1035,7 +1145,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'ToolDefinition',
-    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
+    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    isConcurrencySafe?(args: unknown): boolean;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
  },
  {
    name: 'ToolErrorInfo',
@@ -1053,9 +1163,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'ToolExecutionInput',
    declaration: 'export interface ToolExecutionInput {\n    readonly callId: CallId;\n    readonly name: string;\n    readonly arguments: unknown;\n    readonly agent?: Agent;\n    readonly parent?: ToolExecutionToken;\n    signal?: AbortSignal;\n}',
  },
+  {
+    name: 'ToolExecutionMode',
+    declaration: 'export type ToolExecutionMode = {\n    kind: \'parallel\';\n} | {\n    kind: \'exclusive\';\n};',
+  },
  {
    name: 'ToolExecutionResult',
-    declaration: 'export interface ToolExecutionResult {\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContext?: HookContext;\n    meta?: unknown;\n}',
+    declaration: 'export interface ToolExecutionResult {\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContexts?: HookContext[];\n    meta?: unknown;\n}',
  },
  {
    name: 'ToolExecutionToken',
@@ -1085,6 +1199,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'ToolResultView',
    declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;',
  },
+  {
+    name: 'ToolRunContext',
+    declaration: 'export interface ToolRunContext extends ToolExecution {\n    deferContext(context: HookContext): void;\n}',
+  },
  {
    name: 'ToolSchema',
    declaration: 'export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}',
@@ -1147,7 +1265,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'WorkflowPhase',
-    declaration: 'export interface WorkflowPhase {\n    title: string;\n    detail?: string;\n    model?: string;\n}',
+    declaration: 'export interface WorkflowPhase {\n    title: string;\n    detail?: string;\n    provider?: string;\n    model?: string;\n}',
  },
  {
    name: 'WorkflowResult',
--- a/packages/cordis/tool-cordis/tests/integration.spec.ts
+++ b/packages/cordis/tool-cordis/tests/integration.spec.ts
@@ -1,11 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as ToolCordis from '../src/index.ts'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import { REVERSE_TOOL_CODE } from './helpers.ts'
@@ -20,18 +18,14 @@ import { REVERSE_TOOL_CODE } from './helpers.ts'

 async function harness(adapter: MockAdapter): Promise<Context> {
  const ctx = new Context()
-  await ctx.plugin(LlmService)
-  await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt)
-  await ctx.plugin(ToolRegistry)
-  await ctx.plugin(AgentRegistry)
+  await mountAgentLoopTestDependencies(ctx)
  await ctx.plugin(AgentLoop, { agents: [] })
  await ctx.plugin(ToolCordis)
  ctx.llm.registerAdapter(['mock'], adapter)
  return ctx
 }

-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
  return new Promise((resolve) => {
    const dispose = ctx.on('agent/status', (subject, status) => {
      if (subject === agent && status === 'idle') {
@@ -51,7 +45,7 @@ describe('cordis tools through the agent loop', () => {
      textResponse('Done.'),
    ])
    const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-cordis'), { model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('it-cordis'), { provider: 'mock', model: 'mock' })

    agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
    await waitForIdle(ctx, agent)
--- a/packages/cordis/tool-cordis/tests/mount.spec.ts
+++ b/packages/cordis/tool-cordis/tests/mount.spec.ts
@@ -175,9 +175,13 @@ describe('cordis_mount', () => {
    // The registered schema is canonical JSON Schema derived from the DSL:
    // the required array survived, integer became number, extra is optional.
    const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')!
-    const parameters = schema.parameters as { properties: Record<string, { type: string; enum?: string[] }>; required?: string[] }
+    const parameters = schema.parameters as {
+      properties: Record<string, { type: string; enum?: string[]; default?: unknown }>
+      required?: string[]
+    }
    expect(parameters.required).toEqual(['text'])
    expect(parameters.properties.count!.type).toBe('number')
+    expect(parameters.properties.count!.default).toBe(1)
    expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow'])
    // Arg validation enforces the normalized spec: text required, extra not.
    expect((await call(ctx, 'json_schema_tool', { count: 2 })).isError).toBe(true)