Merge remote-tracking branch 'origin/master' into xtr/durable-inbox-recovery
# Conflicts: # docs/config-catalog.i18n.yaml # docs/config-catalog.md # docs/config-catalog.zh.md # docs/event-producer-consumer.i18n.yaml # docs/event-producer-consumer.md # docs/event-producer-consumer.zh.md # docs/module-graph.i18n.yaml # docs/module-graph.md # docs/module-graph.zh.md # packages/api/session-controller/src/control.ts # packages/context/agent-instructions/tests/agent-instructions.spec.ts # packages/test-support/agent-loop-testkit/package.json
This commit is contained in:
commit
700d5407fb
1292 files changed
+21476
-11274
No files matched your search
+1
-1
@@ -54,7 +54,7 @@ When the gate goes red:
|
||||
2. **Condense** content that belongs here but can be shorter.
|
||||
3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
|
||||
|
||||
Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 675 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,150, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
|
||||
Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
|
||||
|
||||
## The slop checklist
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/api-gateway.md
|
||||
api-gateway.md: 43b00bcff3da0adb1d53ac25534b65366bc42611
|
||||
api-gateway.zh.md: bb2711220fd75ef0119e1188c22a0af5ad4169a8
|
||||
api-gateway.md: 0c64fdf6a528ea6564915a06abb237fd65b91e66
|
||||
api-gateway.zh.md: 43bf87865de70a7921502c4105ce1777bc30394e
|
||||
+2
-2
@@ -124,13 +124,13 @@ The Connection performs the unified trust check for `/api` before the HTTP bridg
|
||||
|
||||
For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code.
|
||||
|
||||
The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard `agentFor()` semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. Resume failures and ownership fences pass through unchanged as existing RPC errors rather than being collapsed into the Gateway's `internal` error.
|
||||
The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `gateway/lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard resolver semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. A resume failure and an ownership fence raise a `RemoteError` carrying their own code, `session/not-found` or `session/agent-busy`, which the Gateway encodes onto the wire unchanged; only an unclassified throw folds into `gateway/internal`.
|
||||
|
||||
Unloading a Client contribution removes its descriptors and concrete methods together, aborts its in-flight calls, and makes stale method handles retained by external code reject further calls. A strict endpoint withdrawn on the Host also does not degrade to SRC inference, preventing a hot unload from silently weakening validation.
|
||||
|
||||
## SRC development fallback
|
||||
|
||||
When the Host starts from source through `node --import tsx/esm`, it does not execute the Typert compiler plugin. Standard decorator initializers still record the method name and invocation mode in a module-private `WeakMap`, while `TypertRemoteService` or `bindTypertRemote()` supplies the explicit service binding; the Gateway can therefore construct a weaker temporary descriptor without starting a `ts.Program`.
|
||||
When the Host starts from source through `node --import tsx/esm`, it does not execute the Typert compiler plugin. Standard decorator initializers still record the method name and invocation mode in a versioned descriptor on the Service prototype, while `TypertRemoteService` or `bindTypertRemote()` supplies the explicit service binding; the Gateway can therefore construct a weaker temporary descriptor without starting a `ts.Program`. The descriptor's stable string property name lets `remoteMethods()` read markers written by another installed copy of the protocol package.
|
||||
|
||||
The SRC fallback parses simple parameter names from the live function. When a parameter name matches the `parameter` of a registered lookup, such as `agent` or `session`, it uses the lookup's `agentId` or `sessionId` wire field and resolves the object on the Host; other parameters are checked only for cycle-free, JSON-safe data with no special prototype. `@RemoteScope` directly uses the wire field of a registered Host Context provider. SRC does not read TypeScript types, generate Zod schemas, infer optional parameters, or support destructuring, default values, rest parameters, or duplicate parameter names.
|
||||
|
||||
|
||||
@@ -124,13 +124,13 @@ Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查,再在共
|
||||
|
||||
Gateway 每次调用都从当前注册表解析描述符和实时服务,不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致,先用 codec 校验 wire 值,再通过注册的 lookup 或 Context 提供方解析对象或接收者,最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。
|
||||
|
||||
lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver;`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载;没有提供方时调用仍以 `lookup-unavailable` 失败,配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 `agentFor()` 语义:复用 live Agent,自动恢复普通冷会话,对并发恢复去重,并拒绝由 subagent routing 拥有的 identity;`session` lookup 返回该 Agent 的 Session。恢复失败和 ownership fence 通过既有 RPC error 原样返回,不折叠为 Gateway 的 `internal` 错误。
|
||||
lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver;`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载;没有提供方时调用仍以 `gateway/lookup-unavailable` 失败,配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 resolver 语义:复用 live Agent,自动恢复普通冷会话,对并发恢复去重,并拒绝由 subagent routing 拥有的 identity;`session` lookup 返回该 Agent 的 Session。恢复失败与 ownership fence 抛出携带自有码的 `RemoteError`(`session/not-found` 或 `session/agent-busy`),Gateway 原样编码上 wire;只有未归类的 throw 才折成 `gateway/internal`。
|
||||
|
||||
Client 卸载一个贡献时会一起移除描述符和具体方法,中止其进行中的调用,并使外部仍持有的陈旧方法句柄拒绝继续调用。Host 上已经注册过的严格 endpoint 被撤回后也不会降级到 SRC 推断,以免热卸载悄然降低校验强度。
|
||||
|
||||
## SRC 开发回退
|
||||
|
||||
Host 通过 `node --import tsx/esm` 从源码启动时不会执行 Typert 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到模块私有 `WeakMap`,`TypertRemoteService` 或 `bindTypertRemote()` 则提供显式服务 binding;Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。
|
||||
Host 通过 `node --import tsx/esm` 从源码启动时不会执行 Typert 编译插件。标准 decorator 初始化器仍会把方法名和调用模式记录到 Service 原型上的带版本描述符中,`TypertRemoteService` 或 `bindTypertRemote()` 则提供显式服务 binding;Gateway 因而可以在不启动 `ts.Program` 的情况下构造一个较弱的临时描述符。描述符使用稳定的字符串属性名,因此 `remoteMethods()` 能读取协议包另一个已安装副本写入的标记。
|
||||
|
||||
SRC 回退从运行中函数解析简单参数名。参数名与某个已注册 lookup 的 `parameter` 相同,例如 `agent` 或 `session`,就使用其 `agentId` 或 `sessionId` wire 字段并在 Host 解析对象;其他参数只检查值是否为无循环、无特殊 prototype 的 JSON-safe 数据。`@RemoteScope` 直接使用已注册 Host Context 提供方的 wire 字段。SRC 不读取 TypeScript 类型,不生成 Zod schema,不推断可选参数,也不支持解构、默认值、rest 或重复参数名。
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/config-catalog.md
|
||||
config-catalog.md: 332e28193562d6ce16786cb39fe3dace562b8c86
|
||||
config-catalog.zh.md: 7cdeb82ae5611e3f4f1991dcf51ab4a26f687726
|
||||
config-catalog.md: 9e93c2f055787dde71b396b2a63e33ad3ae3367b
|
||||
config-catalog.zh.md: 9ff351e2c384dbf2c1e2f1d2efab3f57125095ca
|
||||
+34
-31
@@ -31,7 +31,7 @@ export interface AcpConfig {
|
||||
|
||||
Depends on: `Stream` (`@agentclientprotocol/sdk`)
|
||||
|
||||
Source: [`packages/acp/acp/src/index.ts:74`](../packages/acp/acp/src/index.ts)
|
||||
Source: [`packages/acp/acp/src/index.ts:75`](../packages/acp/acp/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-agent-default-model"></a>
|
||||
|
||||
@@ -111,7 +111,7 @@ export interface Config {
|
||||
|
||||
Depends on: [`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md)
|
||||
|
||||
Source: [`packages/core/agent-loop/src/index.ts:312`](../packages/core/agent-loop/src/index.ts)
|
||||
Source: [`packages/core/agent-loop/src/index.ts:313`](../packages/core/agent-loop/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-agent-presets"></a>
|
||||
|
||||
@@ -157,7 +157,7 @@ export interface PresetRoot {
|
||||
export type PresetTrust = 'system' | 'user'
|
||||
```
|
||||
|
||||
Source: [`packages/preset/agent-presets/src/preset.ts:54`](../packages/preset/agent-presets/src/preset.ts)
|
||||
Source: [`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts)
|
||||
|
||||
<a id="deepseek-aidsh-agent-spine-demo"></a>
|
||||
|
||||
@@ -285,12 +285,12 @@ Requires: `typert`
|
||||
```ts config-catalog
|
||||
/** Gateway transport configuration. */
|
||||
export interface Config {
|
||||
/** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 30000 */
|
||||
/** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
|
||||
readonly websocketHeartbeatIntervalMs?: number
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/api/gateway/src/index.ts:117`](../packages/api/gateway/src/index.ts)
|
||||
Source: [`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-api-session-controller"></a>
|
||||
|
||||
@@ -322,7 +322,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/api/settings-controller/src/index.ts:41`](../packages/api/settings-controller/src/index.ts)
|
||||
Source: [`packages/api/settings-controller/src/index.ts:36`](../packages/api/settings-controller/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-attachment-local"></a>
|
||||
|
||||
@@ -714,7 +714,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/experimental/tool-agent-team/src/index.ts:18`](../packages/experimental/tool-agent-team/src/index.ts)
|
||||
Source: [`packages/experimental/tool-agent-team/src/index.ts:17`](../packages/experimental/tool-agent-team/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-file-reference-local"></a>
|
||||
|
||||
@@ -734,7 +734,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/context/file-reference-local/src/index.ts:35`](../packages/context/file-reference-local/src/index.ts)
|
||||
Source: [`packages/context/file-reference-local/src/index.ts:34`](../packages/context/file-reference-local/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-fs-local"></a>
|
||||
|
||||
@@ -805,7 +805,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
|
||||
Source: [`packages/bundle/headless/src/index.ts:33`](../packages/bundle/headless/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-hooks-claude-code"></a>
|
||||
|
||||
@@ -1038,7 +1038,7 @@ export interface DeepSeekCatalogModel {
|
||||
|
||||
Depends on: [`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
|
||||
|
||||
Source: [`packages/llm/llm-deepseek/src/index.ts:124`](../packages/llm/llm-deepseek/src/index.ts)
|
||||
Source: [`packages/llm/llm-deepseek/src/index.ts:125`](../packages/llm/llm-deepseek/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-llm-pi-ai"></a>
|
||||
|
||||
@@ -1381,7 +1381,7 @@ export interface ReplayModelConfig {
|
||||
|
||||
Depends on: [`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
|
||||
|
||||
Source: [`packages/test-support/llm-replay/src/index.ts:918`](../packages/test-support/llm-replay/src/index.ts)
|
||||
Source: [`packages/test-support/llm-replay/src/index.ts:919`](../packages/test-support/llm-replay/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-llm-retry"></a>
|
||||
|
||||
@@ -1588,7 +1588,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/preset/persona/src/index.ts:34`](../packages/preset/persona/src/index.ts)
|
||||
Source: [`packages/preset/persona/src/index.ts:30`](../packages/preset/persona/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-plan-mode"></a>
|
||||
|
||||
@@ -1604,7 +1604,7 @@ export interface PlanModeConfig {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/plan/plan-mode/src/index.ts:64`](../packages/plan/plan-mode/src/index.ts)
|
||||
Source: [`packages/plan/plan-mode/src/index.ts:63`](../packages/plan/plan-mode/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-plugin-package-inventory-deepseek"></a>
|
||||
|
||||
@@ -1620,7 +1620,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/llm/plugin-package-inventory-deepseek/src/index.ts:30`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
|
||||
Source: [`packages/llm/plugin-package-inventory-deepseek/src/index.ts:31`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-pwsh-local"></a>
|
||||
|
||||
@@ -1826,7 +1826,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/session/session-log-deepseek/src/index.ts:22`](../packages/session/session-log-deepseek/src/index.ts)
|
||||
Source: [`packages/session/session-log-deepseek/src/index.ts:23`](../packages/session/session-log-deepseek/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-session-log-export"></a>
|
||||
|
||||
@@ -1845,7 +1845,7 @@ export interface Config {
|
||||
export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
|
||||
```
|
||||
|
||||
Source: [`packages/session-query/session-log-export/src/index.ts:41`](../packages/session-query/session-log-export/src/index.ts)
|
||||
Source: [`packages/session-query/session-log-export/src/index.ts:42`](../packages/session-query/session-log-export/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-session-persistence-jsonl"></a>
|
||||
|
||||
@@ -2067,7 +2067,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/session/session-title/src/index.ts:54`](../packages/session/session-title/src/index.ts)
|
||||
Source: [`packages/session/session-title/src/index.ts:55`](../packages/session/session-title/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-session-title-all-prompts-llm"></a>
|
||||
|
||||
@@ -2117,7 +2117,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/settings/settings-file/src/index.ts:21`](../packages/settings/settings-file/src/index.ts)
|
||||
Source: [`packages/settings/settings-file/src/index.ts:22`](../packages/settings/settings-file/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-shell-env"></a>
|
||||
|
||||
@@ -2145,7 +2145,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/skill/skill/src/index.ts:279`](../packages/skill/skill/src/index.ts)
|
||||
Source: [`packages/skill/skill/src/index.ts:280`](../packages/skill/skill/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-skill-filesystem"></a>
|
||||
|
||||
@@ -2681,7 +2681,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts)
|
||||
Source: [`packages/shell/tool-bash/src/index.ts:33`](../packages/shell/tool-bash/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-bash-persistent"></a>
|
||||
|
||||
@@ -2776,7 +2776,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/goal/tool-goal/src/index.ts:26`](../packages/goal/tool-goal/src/index.ts)
|
||||
Source: [`packages/goal/tool-goal/src/index.ts:25`](../packages/goal/tool-goal/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-jobs"></a>
|
||||
|
||||
@@ -2810,7 +2810,7 @@ export interface Config {
|
||||
export type CompletionDelivery = 'quiet' | 'wakeup'
|
||||
```
|
||||
|
||||
Source: [`packages/jobs/tool-jobs/src/index.ts:32`](../packages/jobs/tool-jobs/src/index.ts)
|
||||
Source: [`packages/jobs/tool-jobs/src/index.ts:31`](../packages/jobs/tool-jobs/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-lsp"></a>
|
||||
|
||||
@@ -2830,7 +2830,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
|
||||
Source: [`packages/lsp/tool-lsp/src/index.ts:57`](../packages/lsp/tool-lsp/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-pwsh"></a>
|
||||
|
||||
@@ -2846,7 +2846,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts)
|
||||
Source: [`packages/shell/tool-pwsh/src/index.ts:51`](../packages/shell/tool-pwsh/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-pwsh-persistent"></a>
|
||||
|
||||
@@ -2890,7 +2890,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/workflow/tool-ralph/src/index.ts:22`](../packages/workflow/tool-ralph/src/index.ts)
|
||||
Source: [`packages/workflow/tool-ralph/src/index.ts:21`](../packages/workflow/tool-ralph/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-session-query"></a>
|
||||
|
||||
@@ -2908,7 +2908,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/session-query/tool-session-query/src/index.ts:29`](../packages/session-query/tool-session-query/src/index.ts)
|
||||
Source: [`packages/session-query/tool-session-query/src/index.ts:28`](../packages/session-query/tool-session-query/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-skill"></a>
|
||||
|
||||
@@ -3012,7 +3012,7 @@ export interface Config {
|
||||
|
||||
Depends on: [`AgentOptions`](subsystems/core.md)
|
||||
|
||||
Source: [`packages/subagent/tool-subagent/src/index.ts:50`](../packages/subagent/tool-subagent/src/index.ts)
|
||||
Source: [`packages/subagent/tool-subagent/src/index.ts:48`](../packages/subagent/tool-subagent/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-subagent-report"></a>
|
||||
|
||||
@@ -3034,7 +3034,7 @@ export interface Config {
|
||||
|
||||
Depends on: [`SubagentReportDelivery`](subsystems/subagent.md)
|
||||
|
||||
Source: [`packages/subagent/tool-subagent-report/src/index.ts:27`](../packages/subagent/tool-subagent-report/src/index.ts)
|
||||
Source: [`packages/subagent/tool-subagent-report/src/index.ts:25`](../packages/subagent/tool-subagent-report/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-terminal"></a>
|
||||
|
||||
@@ -3052,7 +3052,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/terminal/tool-terminal/src/index.ts:36`](../packages/terminal/tool-terminal/src/index.ts)
|
||||
Source: [`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-todo"></a>
|
||||
|
||||
@@ -3156,7 +3156,7 @@ export interface Config {
|
||||
export type ToolPresentationMode = 'native' | 'ptc' | 'both'
|
||||
```
|
||||
|
||||
Source: [`packages/core/tools/src/index.ts:655`](../packages/core/tools/src/index.ts)
|
||||
Source: [`packages/core/tools/src/index.ts:647`](../packages/core/tools/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-typert-loader"></a>
|
||||
|
||||
@@ -3251,7 +3251,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/bundle/web-app/src/index.ts:45`](../packages/bundle/web-app/src/index.ts)
|
||||
Source: [`packages/bundle/web-app/src/index.ts:44`](../packages/bundle/web-app/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-web-fetch-http"></a>
|
||||
|
||||
@@ -3524,6 +3524,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
|
||||
- `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
|
||||
- `@deepseek-ai/dsh-cmdline` ([`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts))
|
||||
- `@deepseek-ai/dsh-code-runtime-python` ([`packages/code-runtime/code-runtime-python/src/index.ts`](../packages/code-runtime/code-runtime-python/src/index.ts))
|
||||
- `@deepseek-ai/dsh-deque` ([`packages/util/deque/src/index.ts`](../packages/util/deque/src/index.ts))
|
||||
- `@deepseek-ai/dsh-experimental-agent-team-profile` ([`packages/experimental/agent-team-profile/src/index.ts`](../packages/experimental/agent-team-profile/src/index.ts))
|
||||
- `@deepseek-ai/dsh-experimental-agent-team-web-profile` ([`packages/experimental/agent-team-web-profile/src/index.ts`](../packages/experimental/agent-team-web-profile/src/index.ts))
|
||||
- `@deepseek-ai/dsh-experimental-webworker-packer` ([`packages/experimental/webworker-packer/src/index.ts`](../packages/experimental/webworker-packer/src/index.ts))
|
||||
@@ -3549,5 +3550,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
|
||||
- `@deepseek-ai/dsh-typert-protocol` ([`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts))
|
||||
- `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-crypto` ([`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-time` ([`packages/util/time/src/index.ts`](../packages/util/time/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-values` ([`packages/util/values/src/index.ts`](../packages/util/values/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-workspace-path` ([`packages/util/workspace-path/src/index.ts`](../packages/util/workspace-path/src/index.ts))
|
||||
- `@deepseek-ai/dsh-win32-process` ([`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts))
|
||||
+34
-31
@@ -33,7 +33,7 @@ export interface AcpConfig {
|
||||
|
||||
依赖:`Stream`(`@agentclientprotocol/sdk`)
|
||||
|
||||
来源:[`packages/acp/acp/src/index.ts:74`](../packages/acp/acp/src/index.ts)
|
||||
来源:[`packages/acp/acp/src/index.ts:75`](../packages/acp/acp/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-agent-default-model"></a>
|
||||
|
||||
@@ -113,7 +113,7 @@ export interface Config {
|
||||
|
||||
依赖:[`AgentOptions`](subsystems/core.zh.md) · [`SessionId`](subsystems/core.zh.md)
|
||||
|
||||
来源:[`packages/core/agent-loop/src/index.ts:312`](../packages/core/agent-loop/src/index.ts)
|
||||
来源:[`packages/core/agent-loop/src/index.ts:313`](../packages/core/agent-loop/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-agent-presets"></a>
|
||||
|
||||
@@ -159,7 +159,7 @@ export interface PresetRoot {
|
||||
export type PresetTrust = 'system' | 'user'
|
||||
```
|
||||
|
||||
来源:[`packages/preset/agent-presets/src/preset.ts:54`](../packages/preset/agent-presets/src/preset.ts)
|
||||
来源:[`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts)
|
||||
|
||||
<a id="deepseek-aidsh-agent-spine-demo"></a>
|
||||
|
||||
@@ -287,12 +287,12 @@ export interface Config {
|
||||
```ts config-catalog
|
||||
/** Gateway transport configuration. */
|
||||
export interface Config {
|
||||
/** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 30000 */
|
||||
/** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
|
||||
readonly websocketHeartbeatIntervalMs?: number
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/api/gateway/src/index.ts:117`](../packages/api/gateway/src/index.ts)
|
||||
来源:[`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-api-session-controller"></a>
|
||||
|
||||
@@ -324,7 +324,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/api/settings-controller/src/index.ts:41`](../packages/api/settings-controller/src/index.ts)
|
||||
来源:[`packages/api/settings-controller/src/index.ts:36`](../packages/api/settings-controller/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-attachment-local"></a>
|
||||
|
||||
@@ -716,7 +716,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/experimental/tool-agent-team/src/index.ts:18`](../packages/experimental/tool-agent-team/src/index.ts)
|
||||
来源:[`packages/experimental/tool-agent-team/src/index.ts:17`](../packages/experimental/tool-agent-team/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-file-reference-local"></a>
|
||||
|
||||
@@ -736,7 +736,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/context/file-reference-local/src/index.ts:35`](../packages/context/file-reference-local/src/index.ts)
|
||||
来源:[`packages/context/file-reference-local/src/index.ts:34`](../packages/context/file-reference-local/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-fs-local"></a>
|
||||
|
||||
@@ -807,7 +807,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
|
||||
来源:[`packages/bundle/headless/src/index.ts:33`](../packages/bundle/headless/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-hooks-claude-code"></a>
|
||||
|
||||
@@ -1040,7 +1040,7 @@ export interface DeepSeekCatalogModel {
|
||||
|
||||
依赖:[`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
|
||||
|
||||
来源:[`packages/llm/llm-deepseek/src/index.ts:107`](../packages/llm/llm-deepseek/src/index.ts)
|
||||
来源:[`packages/llm/llm-deepseek/src/index.ts:125`](../packages/llm/llm-deepseek/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-llm-pi-ai"></a>
|
||||
|
||||
@@ -1383,7 +1383,7 @@ export interface ReplayModelConfig {
|
||||
|
||||
依赖:[`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
|
||||
|
||||
来源:[`packages/test-support/llm-replay/src/index.ts:918`](../packages/test-support/llm-replay/src/index.ts)
|
||||
来源:[`packages/test-support/llm-replay/src/index.ts:919`](../packages/test-support/llm-replay/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-llm-retry"></a>
|
||||
|
||||
@@ -1590,7 +1590,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/preset/persona/src/index.ts:34`](../packages/preset/persona/src/index.ts)
|
||||
来源:[`packages/preset/persona/src/index.ts:30`](../packages/preset/persona/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-plan-mode"></a>
|
||||
|
||||
@@ -1606,7 +1606,7 @@ export interface PlanModeConfig {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/plan/plan-mode/src/index.ts:64`](../packages/plan/plan-mode/src/index.ts)
|
||||
来源:[`packages/plan/plan-mode/src/index.ts:63`](../packages/plan/plan-mode/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-plugin-package-inventory-deepseek"></a>
|
||||
|
||||
@@ -1622,7 +1622,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/llm/plugin-package-inventory-deepseek/src/index.ts:30`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
|
||||
来源:[`packages/llm/plugin-package-inventory-deepseek/src/index.ts:31`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-pwsh-local"></a>
|
||||
|
||||
@@ -1828,7 +1828,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/session/session-log-deepseek/src/index.ts:22`](../packages/session/session-log-deepseek/src/index.ts)
|
||||
来源:[`packages/session/session-log-deepseek/src/index.ts:23`](../packages/session/session-log-deepseek/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-session-log-export"></a>
|
||||
|
||||
@@ -1847,7 +1847,7 @@ export interface Config {
|
||||
export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
|
||||
```
|
||||
|
||||
来源:[`packages/session-query/session-log-export/src/index.ts:41`](../packages/session-query/session-log-export/src/index.ts)
|
||||
来源:[`packages/session-query/session-log-export/src/index.ts:42`](../packages/session-query/session-log-export/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-session-persistence-jsonl"></a>
|
||||
|
||||
@@ -2069,7 +2069,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/session/session-title/src/index.ts:54`](../packages/session/session-title/src/index.ts)
|
||||
来源:[`packages/session/session-title/src/index.ts:55`](../packages/session/session-title/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-session-title-all-prompts-llm"></a>
|
||||
|
||||
@@ -2119,7 +2119,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/settings/settings-file/src/index.ts:21`](../packages/settings/settings-file/src/index.ts)
|
||||
来源:[`packages/settings/settings-file/src/index.ts:22`](../packages/settings/settings-file/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-shell-env"></a>
|
||||
|
||||
@@ -2147,7 +2147,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/skill/skill/src/index.ts:279`](../packages/skill/skill/src/index.ts)
|
||||
来源:[`packages/skill/skill/src/index.ts:280`](../packages/skill/skill/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-skill-filesystem"></a>
|
||||
|
||||
@@ -2683,7 +2683,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts)
|
||||
来源:[`packages/shell/tool-bash/src/index.ts:33`](../packages/shell/tool-bash/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-bash-persistent"></a>
|
||||
|
||||
@@ -2778,7 +2778,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/goal/tool-goal/src/index.ts:26`](../packages/goal/tool-goal/src/index.ts)
|
||||
来源:[`packages/goal/tool-goal/src/index.ts:25`](../packages/goal/tool-goal/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-jobs"></a>
|
||||
|
||||
@@ -2812,7 +2812,7 @@ export interface Config {
|
||||
export type CompletionDelivery = 'quiet' | 'wakeup'
|
||||
```
|
||||
|
||||
来源:[`packages/jobs/tool-jobs/src/index.ts:32`](../packages/jobs/tool-jobs/src/index.ts)
|
||||
来源:[`packages/jobs/tool-jobs/src/index.ts:31`](../packages/jobs/tool-jobs/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-lsp"></a>
|
||||
|
||||
@@ -2832,7 +2832,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
|
||||
来源:[`packages/lsp/tool-lsp/src/index.ts:57`](../packages/lsp/tool-lsp/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-pwsh"></a>
|
||||
|
||||
@@ -2848,7 +2848,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts)
|
||||
来源:[`packages/shell/tool-pwsh/src/index.ts:51`](../packages/shell/tool-pwsh/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-pwsh-persistent"></a>
|
||||
|
||||
@@ -2892,7 +2892,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/workflow/tool-ralph/src/index.ts:22`](../packages/workflow/tool-ralph/src/index.ts)
|
||||
来源:[`packages/workflow/tool-ralph/src/index.ts:21`](../packages/workflow/tool-ralph/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-session-query"></a>
|
||||
|
||||
@@ -2910,7 +2910,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/session-query/tool-session-query/src/index.ts:29`](../packages/session-query/tool-session-query/src/index.ts)
|
||||
来源:[`packages/session-query/tool-session-query/src/index.ts:28`](../packages/session-query/tool-session-query/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-skill"></a>
|
||||
|
||||
@@ -3014,7 +3014,7 @@ export interface Config {
|
||||
|
||||
依赖:[`AgentOptions`](subsystems/core.zh.md)
|
||||
|
||||
来源:[`packages/subagent/tool-subagent/src/index.ts:50`](../packages/subagent/tool-subagent/src/index.ts)
|
||||
来源:[`packages/subagent/tool-subagent/src/index.ts:48`](../packages/subagent/tool-subagent/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-subagent-report"></a>
|
||||
|
||||
@@ -3036,7 +3036,7 @@ export interface Config {
|
||||
|
||||
依赖:[`SubagentReportDelivery`](subsystems/subagent.zh.md)
|
||||
|
||||
来源:[`packages/subagent/tool-subagent-report/src/index.ts:27`](../packages/subagent/tool-subagent-report/src/index.ts)
|
||||
来源:[`packages/subagent/tool-subagent-report/src/index.ts:25`](../packages/subagent/tool-subagent-report/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-terminal"></a>
|
||||
|
||||
@@ -3054,7 +3054,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/terminal/tool-terminal/src/index.ts:36`](../packages/terminal/tool-terminal/src/index.ts)
|
||||
来源:[`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-tool-todo"></a>
|
||||
|
||||
@@ -3158,7 +3158,7 @@ export interface Config {
|
||||
export type ToolPresentationMode = 'native' | 'ptc' | 'both'
|
||||
```
|
||||
|
||||
来源:[`packages/core/tools/src/index.ts:655`](../packages/core/tools/src/index.ts)
|
||||
来源:[`packages/core/tools/src/index.ts:647`](../packages/core/tools/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-typert-loader"></a>
|
||||
|
||||
@@ -3253,7 +3253,7 @@ export interface Config {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/bundle/web-app/src/index.ts:45`](../packages/bundle/web-app/src/index.ts)
|
||||
来源:[`packages/bundle/web-app/src/index.ts:44`](../packages/bundle/web-app/src/index.ts)
|
||||
|
||||
<a id="deepseek-aidsh-web-fetch-http"></a>
|
||||
|
||||
@@ -3525,6 +3525,7 @@ export interface Config {
|
||||
- `@deepseek-ai/dsh-client-web`([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
|
||||
- `@deepseek-ai/dsh-cmdline`([`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts))
|
||||
- `@deepseek-ai/dsh-code-runtime-python`([`packages/code-runtime/code-runtime-python/src/index.ts`](../packages/code-runtime/code-runtime-python/src/index.ts))
|
||||
- `@deepseek-ai/dsh-deque`([`packages/util/deque/src/index.ts`](../packages/util/deque/src/index.ts))
|
||||
- `@deepseek-ai/dsh-experimental-agent-team-profile`([`packages/experimental/agent-team-profile/src/index.ts`](../packages/experimental/agent-team-profile/src/index.ts))
|
||||
- `@deepseek-ai/dsh-experimental-agent-team-web-profile`([`packages/experimental/agent-team-web-profile/src/index.ts`](../packages/experimental/agent-team-web-profile/src/index.ts))
|
||||
- `@deepseek-ai/dsh-experimental-webworker-packer`([`packages/experimental/webworker-packer/src/index.ts`](../packages/experimental/webworker-packer/src/index.ts))
|
||||
@@ -3550,5 +3551,7 @@ export interface Config {
|
||||
- `@deepseek-ai/dsh-typert-protocol`([`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts))
|
||||
- `@deepseek-ai/dsh-typert-registry`([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-crypto`([`packages/util/crypto/src/index.ts`](../packages/util/crypto/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-time`([`packages/util/time/src/index.ts`](../packages/util/time/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-values`([`packages/util/values/src/index.ts`](../packages/util/values/src/index.ts))
|
||||
- `@deepseek-ai/dsh-util-workspace-path`([`packages/util/workspace-path/src/index.ts`](../packages/util/workspace-path/src/index.ts))
|
||||
- `@deepseek-ai/dsh-win32-process`([`packages/subprocess/win32-process/src/index.ts`](../packages/subprocess/win32-process/src/index.ts))
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/cookbook/adding-a-remote-api.md
|
||||
adding-a-remote-api.md: 0f89101e9bc3ff961d465c109f033150e93e04f6
|
||||
adding-a-remote-api.zh.md: 0c5a57b539ecd98cb88790260a3fb8e7b41afff6
|
||||
@@ -0,0 +1,197 @@
|
||||
# Cookbook: adding a Remote API
|
||||
|
||||
English | [中文](adding-a-remote-api.zh.md)
|
||||
|
||||
Adding or changing a `ctx.remote` endpoint takes the five steps on this page: declare the method, declare its failures, register it on the package, consume it on the Client, and test it. Decorator semantics, lookup resolution, the generation pipeline, and the `/api` route are the mechanism and belong to the [API Gateway reference](../api-gateway.md); this page gives the action for each step and the conventions it must satisfy. Why the programming interface looks like this is in the [Typert Remote method calls Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md), and why a failure is one `RemoteError` plus a code table is in the [failure vocabulary Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.md).
|
||||
|
||||
## 1. Declare the API
|
||||
|
||||
The owner is a Host-side Cordis service: extend `TypertRemoteService` so the service key and the wire namespace are bound together, then mark the exposed methods with `@Remote`. Mark the business method itself when its signature already satisfies the wire conventions; write a `remoteExport*` adapter only when the shape has to change (adding `signal`, reordering parameters, exporting another name), and let that adapter call the unrenamed business method. Lookup objects (`Agent`, `Session`) may only occupy top-level parameter positions, and a method that supports cooperative cancellation takes `signal: AbortSignal` as its final parameter.
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
|
||||
|
||||
/** One stored note as a Client reads it. */
|
||||
export interface NoteRow {
|
||||
readonly noteId: string
|
||||
readonly title: string
|
||||
}
|
||||
|
||||
declare module '@deepseek-ai/cordis' {
|
||||
interface Context {
|
||||
notesController: NotesController
|
||||
}
|
||||
}
|
||||
|
||||
export class NotesController extends TypertRemoteService {
|
||||
constructor(ctx: Context) {
|
||||
super(ctx, 'notesController', { namespace: 'notes' })
|
||||
}
|
||||
|
||||
/**
|
||||
* @param agent - lookup parameter the Gateway resolves from its wire identity.
|
||||
* @param signal - carrier cancellation, always the final parameter.
|
||||
* @returns the notes this Agent's session owns.
|
||||
*/
|
||||
@Remote('list')
|
||||
async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
|
||||
return await this.list(agent, signal)
|
||||
}
|
||||
|
||||
/** The in-process API the adapter above delegates to, unchanged by it. */
|
||||
async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
|
||||
signal.throwIfAborted()
|
||||
return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Declare the failures
|
||||
|
||||
A Remote failure is one class, `RemoteError`: merge the domain codes into `RemoteErrorDetailsMap` through declaration merging and `throw new RemoteError(code, message, details)` at the failure point. Do not build a family of domain error classes, and do not write an exit-mapping function; an exception unrelated to this endpoint is not pre-classified, because the Gateway folds it into `gateway/internal`. Write a `catch` only to classify an arbitrary provider exception as one domain code, and attach the original exception as `cause`.
|
||||
|
||||
A code reads `<domain>/<reason>`, and its declaration has four placement rules:
|
||||
|
||||
- One producer only: declare it in the producing package, next to the throw.
|
||||
- Several packages produce it: declare it in the lowest domain package both depend on (`session/not-found` in `core/session`, `workspace/not-found` in `dsh-workspace`).
|
||||
- The carrier codes `gateway/bad-request`, `gateway/cancelled`, and `gateway/internal` are declared in protocol, and the Gateway infrastructure codes in gateway — use them, never copy them.
|
||||
- A local failure that never crosses the wire stays out of the code table; express it with the caller's own type.
|
||||
|
||||
```ts
|
||||
import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
|
||||
|
||||
declare module '@deepseek-ai/dsh-typert-protocol' {
|
||||
interface RemoteErrorDetailsMap {
|
||||
/** No stored note carries that id. */
|
||||
'note/not-found': { readonly noteId: string }
|
||||
/** The store refused an otherwise valid write. */
|
||||
'note/rejected': { readonly noteId: string }
|
||||
}
|
||||
}
|
||||
|
||||
declare const stored: ReadonlyMap<string, string>
|
||||
declare function persist(noteId: string, title: string): Promise<void>
|
||||
|
||||
export async function rename(noteId: string, title: string): Promise<void> {
|
||||
if (!stored.has(noteId)) {
|
||||
throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
|
||||
}
|
||||
try {
|
||||
await persist(noteId, title)
|
||||
} catch (error: unknown) {
|
||||
const message = error instanceof Error ? error.message : String(error)
|
||||
throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Register it on the package
|
||||
|
||||
`@Remote` must live in a Loader entry plugin package; when the owner is an abstract seam, the controller goes in the matching package under `packages/api/`. The manifest gains the two generated entries and the protocol peer dependency, while on the Client side the `@deepseek-ai/dsh-api-remotes` assembly mounts the contribution and re-exports the type vocabulary that consumers need. Which generated artifact each entry points at, and how the generation pipeline is ordered, are in the [API Gateway reference](../api-gateway.md).
|
||||
|
||||
```json
|
||||
{
|
||||
"exports": {
|
||||
"./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
|
||||
"./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
|
||||
},
|
||||
"peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
|
||||
"devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
|
||||
}
|
||||
```
|
||||
|
||||
Rerun `pnpm run build:lib` after changing a signature, the code table, the namespace, or an export name, because that is what hands the Client its new declarations and codecs; changing only an implementation body needs no regeneration.
|
||||
|
||||
## 4. Consume it on the Client
|
||||
|
||||
The calling plugin declares both `remote` and `remote.<namespace>` in its `inject`, and the call site writes `ctx.remote.<namespace>.<method>(...)` directly: no `Pick<ClientRemote, …>` narrowing, no hand-written method signature, no wire relay object. The result is a `RemoteResult<T>`, so branch on `if (!result.ok)` in place and discriminate by `code` rather than `instanceof` — a code branch narrows `details` on its own. An exception-flow site writes `throw result.error` (it is a real Error); whoever catches it uses `isRemoteFailure` to tell a Remote failure from a local defect and rethrows the defect. Do not write a defensive catch: a Remote call does not reject, and an assembly mistake should crash.
|
||||
|
||||
Fixed Host facts come from `ctx.remote.$host`: `home` and `isLoopback` are plain reads with no subscription and no generation counter, and `home` is `undefined` until the first ready frame. Refresh after a reconnect through `ctx.on('connection/reset')` or a domain's own remote event. When the caller aborts a unary call, the outcome is `gateway/cancelled` on the error branch rather than a throw.
|
||||
|
||||
```ts ignore-check
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
|
||||
import type {} from '@deepseek-ai/dsh-api-remotes/client'
|
||||
|
||||
export const inject = ['remote', 'remote.notes']
|
||||
|
||||
declare const ctx: Context
|
||||
|
||||
/** Store-side read: the error branch is handled where the code is meaningful. */
|
||||
export async function noteTitles(): Promise<readonly string[]> {
|
||||
const result = await ctx.remote.notes.list()
|
||||
if (!result.ok) {
|
||||
if (result.error.code === 'note/not-found') return []
|
||||
throw result.error
|
||||
}
|
||||
return result.value.map(row => row.title)
|
||||
}
|
||||
|
||||
/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
|
||||
export async function renderTitles(): Promise<string> {
|
||||
try {
|
||||
return (await noteTitles()).join(', ')
|
||||
} catch (error: unknown) {
|
||||
if (!isRemoteFailure(error)) throw error
|
||||
return `unavailable (${error.code})`
|
||||
}
|
||||
}
|
||||
|
||||
/** Fixed Host facts as plain reads. */
|
||||
export function hostLabel(): string {
|
||||
const { home, isLoopback } = ctx.remote.$host
|
||||
return home ?? (isLoopback ? 'local host' : 'remote host')
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Test it
|
||||
|
||||
On the owner side, assert the code that was thrown: recover the failure with `remoteErrorOf` after catching, then compare `code` and the details fields you care about with `toMatchObject` — never deep-compare the error object with `toEqual`, and never assert `instanceof`.
|
||||
|
||||
```ts
|
||||
import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
|
||||
import { expect, it } from 'vitest'
|
||||
|
||||
declare function rename(noteId: string, title: string): Promise<void>
|
||||
|
||||
it('refuses an unknown note before writing', async () => {
|
||||
const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
|
||||
|
||||
expect(remoteErrorOf(failure)).toMatchObject({
|
||||
code: 'note/not-found',
|
||||
details: { noteId: 'n-404' },
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
A Client-side double returns real instances: take the `RemoteError` and `TestRemote` value imports from `@deepseek-ai/dsh-client-test-runtime`, because a value import from the `api-remotes` facade would load the unbuilt assembly chain. `TestRemote.$host` is a plain field a spec assigns directly.
|
||||
|
||||
```ts ignore-check
|
||||
import { Context } from '@deepseek-ai/cordis'
|
||||
import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
|
||||
import { expect, it } from 'vitest'
|
||||
|
||||
it('renders the failure code the Host reported', async () => {
|
||||
const ctx = new Context()
|
||||
const remote = new TestRemote(ctx, {
|
||||
notes: {
|
||||
list: () => Promise.resolve({
|
||||
ok: false as const,
|
||||
error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
|
||||
}),
|
||||
},
|
||||
})
|
||||
remote.$host = { home: '/home/fixture', isLoopback: true }
|
||||
|
||||
await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
|
||||
})
|
||||
```
|
||||
|
||||
## Verify
|
||||
|
||||
1. `pnpm run build:lib`: mandatory once a signature, the code table, the namespace, or an export name changed, because it produces the Client declarations and codecs.
|
||||
2. `pnpm run typecheck`: both the Host and the Client program, where a code merged into an unreachable package turns red.
|
||||
3. Run both sides' specs by name: `npx vitest run <owner spec> <client spec>`.
|
||||
4. Add a recorded-session snapshot when the endpoint reaches a product-visible surface, per the [testing policy](../testing.md).
|
||||
@@ -0,0 +1,197 @@
|
||||
# 实操手册:新增一个 Remote API
|
||||
|
||||
[English](adding-a-remote-api.md) | 中文
|
||||
|
||||
新增或改动一个 `ctx.remote` 端点按本页五步走:声明方法、声明失败、在包上注册、在 Client 消费、写测试。decorator 语义、lookup 解析、生成管线与 `/api` 路由属于机制,由 [API Gateway 参考](../api-gateway.zh.md)负责;本页给的是每一步的动作与必须遵守的约定。为什么是这套编程面,见 [Typert Remote 方法调用 Agent Note](../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md);为什么失败面是单个 `RemoteError` 加一张码表,见[失败词汇 Agent Note](../../.agents/notes/implemented/architecture/2026-08-28-ctx-remote-failure-vocabulary.zh.md)。
|
||||
|
||||
## 1. 声明 API
|
||||
|
||||
owner 是一个 Host 侧 Cordis 服务:继承 `TypertRemoteService` 把 service 键与 wire namespace 一起绑定,再用 `@Remote` 标注对外暴露的方法。业务方法的签名若已符合 wire 约定就直接标注它本身;只有形态需要调整(补 `signal`、换参数顺序、换导出名)才写一个 `remoteExport*` adapter,由它调用不改名的业务方法。lookup 对象(`Agent`、`Session`)只能占顶层参数位,支持协作式取消的方法把 `signal: AbortSignal` 放在最后一位。
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import type { Agent } from '@deepseek-ai/dsh-agent'
|
||||
import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
|
||||
|
||||
/** One stored note as a Client reads it. */
|
||||
export interface NoteRow {
|
||||
readonly noteId: string
|
||||
readonly title: string
|
||||
}
|
||||
|
||||
declare module '@deepseek-ai/cordis' {
|
||||
interface Context {
|
||||
notesController: NotesController
|
||||
}
|
||||
}
|
||||
|
||||
export class NotesController extends TypertRemoteService {
|
||||
constructor(ctx: Context) {
|
||||
super(ctx, 'notesController', { namespace: 'notes' })
|
||||
}
|
||||
|
||||
/**
|
||||
* @param agent - lookup parameter the Gateway resolves from its wire identity.
|
||||
* @param signal - carrier cancellation, always the final parameter.
|
||||
* @returns the notes this Agent's session owns.
|
||||
*/
|
||||
@Remote('list')
|
||||
async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
|
||||
return await this.list(agent, signal)
|
||||
}
|
||||
|
||||
/** The in-process API the adapter above delegates to, unchanged by it. */
|
||||
async list(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> {
|
||||
signal.throwIfAborted()
|
||||
return await Promise.resolve([{ noteId: `${agent.id}-1`, title: 'draft' }])
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 声明失败
|
||||
|
||||
Remote 失败只有一个类 `RemoteError`:域码经 declaration merging 进 `RemoteErrorDetailsMap`,失败点直接 `throw new RemoteError(code, message, details)`。不要建域异常类家族,也不要写出口映射函数;与本端点无关的异常不预先归类,Gateway 会兜底折成 `gateway/internal`。只有"把任意 provider 异常归为一个域码"这一种场景才写 `catch`,并把原始异常挂在 `cause` 上。
|
||||
|
||||
码名是 `<域>/<理由>`,声明落点四条:
|
||||
|
||||
- 只有一个生产者:声明落生产者包,紧挨抛出点。
|
||||
- 多个包共同生产:落双方共同依赖的最低层域包(`session/not-found` 在 `core/session`,`workspace/not-found` 在 `dsh-workspace`)。
|
||||
- 载体码 `gateway/bad-request`、`gateway/cancelled`、`gateway/internal` 已在 protocol 声明,Gateway 基础设施码已在 gateway 声明——直接用,不要复制。
|
||||
- 不上 wire 的本地失败不进码表,用调用方自己的类型表达。
|
||||
|
||||
```ts
|
||||
import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
|
||||
|
||||
declare module '@deepseek-ai/dsh-typert-protocol' {
|
||||
interface RemoteErrorDetailsMap {
|
||||
/** No stored note carries that id. */
|
||||
'note/not-found': { readonly noteId: string }
|
||||
/** The store refused an otherwise valid write. */
|
||||
'note/rejected': { readonly noteId: string }
|
||||
}
|
||||
}
|
||||
|
||||
declare const stored: ReadonlyMap<string, string>
|
||||
declare function persist(noteId: string, title: string): Promise<void>
|
||||
|
||||
export async function rename(noteId: string, title: string): Promise<void> {
|
||||
if (!stored.has(noteId)) {
|
||||
throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
|
||||
}
|
||||
try {
|
||||
await persist(noteId, title)
|
||||
} catch (error: unknown) {
|
||||
const message = error instanceof Error ? error.message : String(error)
|
||||
throw new RemoteError('note/rejected', message, { noteId }, { cause: error })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 在包上注册
|
||||
|
||||
`@Remote` 必须落在一个 Loader entry 插件包里;owner 是抽象 seam 时把控制器放进 `packages/api/` 下的对应包。包清单要补两个生成入口与 protocol 的 peer 依赖,Client 侧则由 `@deepseek-ai/dsh-api-remotes` 的 assembly 挂载该贡献并按需转口类型词汇。两个入口分别指向哪个生成产物、生成管线如何排序,见 [API Gateway 参考](../api-gateway.zh.md)。
|
||||
|
||||
```json
|
||||
{
|
||||
"exports": {
|
||||
"./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
|
||||
"./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
|
||||
},
|
||||
"peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
|
||||
"devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
|
||||
}
|
||||
```
|
||||
|
||||
改动了签名、码表、namespace 或导出名之后重跑 `pnpm run build:lib`,Client 才拿得到新的声明与 codec;只改实现体不需要重新生成。
|
||||
|
||||
## 4. 在 Client 消费
|
||||
|
||||
调用插件在 `inject` 里同时声明 `remote` 与 `remote.<namespace>`,调用点直写 `ctx.remote.<namespace>.<method>(...)`:不要用 `Pick<ClientRemote, …>` 窄化、不要手写方法签名、不要造 wire 中转对象。结果是 `RemoteResult<T>`,就地 `if (!result.ok)` 分支,判 `code` 而不是 `instanceof`——code 分支会自动窄化 `details`。异常流的站点写 `throw result.error`(它是真 Error);接住它的上层用 `isRemoteFailure` 区分 Remote 失败与本地缺陷,本地缺陷继续往上抛。不要写防御性 catch:Remote 调用不 reject,装配错误就该炸。
|
||||
|
||||
Host 的固定事实读 `ctx.remote.$host`:`home` 与 `isLoopback` 是普通值读取,没有订阅也没有 generation 计数器,`home` 在第一帧 ready 之前是 `undefined`;重连后的刷新走 `ctx.on('connection/reset')` 或各域自己的 remote 事件。调用方 abort 掉一次一元调用时,结果落在错误分支上的 `gateway/cancelled`,而不是抛出。
|
||||
|
||||
```ts ignore-check
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
|
||||
import type {} from '@deepseek-ai/dsh-api-remotes/client'
|
||||
|
||||
export const inject = ['remote', 'remote.notes']
|
||||
|
||||
declare const ctx: Context
|
||||
|
||||
/** Store-side read: the error branch is handled where the code is meaningful. */
|
||||
export async function noteTitles(): Promise<readonly string[]> {
|
||||
const result = await ctx.remote.notes.list()
|
||||
if (!result.ok) {
|
||||
if (result.error.code === 'note/not-found') return []
|
||||
throw result.error
|
||||
}
|
||||
return result.value.map(row => row.title)
|
||||
}
|
||||
|
||||
/** Action-side: a Remote failure becomes copy; a local fault keeps crashing. */
|
||||
export async function renderTitles(): Promise<string> {
|
||||
try {
|
||||
return (await noteTitles()).join(', ')
|
||||
} catch (error: unknown) {
|
||||
if (!isRemoteFailure(error)) throw error
|
||||
return `unavailable (${error.code})`
|
||||
}
|
||||
}
|
||||
|
||||
/** Fixed Host facts as plain reads. */
|
||||
export function hostLabel(): string {
|
||||
const { home, isLoopback } = ctx.remote.$host
|
||||
return home ?? (isLoopback ? 'local host' : 'remote host')
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 测试
|
||||
|
||||
owner 侧断言抛出的码:捕获后用 `remoteErrorOf` 取出失败,再用 `toMatchObject` 比对 `code` 与需要的 `details` 字段——不要用 `toEqual` 深比对错误对象,也不要断言 `instanceof`。
|
||||
|
||||
```ts
|
||||
import { remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
|
||||
import { expect, it } from 'vitest'
|
||||
|
||||
declare function rename(noteId: string, title: string): Promise<void>
|
||||
|
||||
it('refuses an unknown note before writing', async () => {
|
||||
const failure = await rename('n-404', 'fresh title').catch((error: unknown) => error)
|
||||
|
||||
expect(remoteErrorOf(failure)).toMatchObject({
|
||||
code: 'note/not-found',
|
||||
details: { noteId: 'n-404' },
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
Client 侧的替身返回真实例:`RemoteError` 与 `TestRemote` 的值 import 一律取自 `@deepseek-ai/dsh-client-test-runtime`,因为从 `api-remotes` facade 值 import 会拉起尚未构建的装配链。`TestRemote.$host` 是普通字段,spec 直接赋值即可。
|
||||
|
||||
```ts ignore-check
|
||||
import { Context } from '@deepseek-ai/cordis'
|
||||
import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
|
||||
import { expect, it } from 'vitest'
|
||||
|
||||
it('renders the failure code the Host reported', async () => {
|
||||
const ctx = new Context()
|
||||
const remote = new TestRemote(ctx, {
|
||||
notes: {
|
||||
list: () => Promise.resolve({
|
||||
ok: false as const,
|
||||
error: new RemoteError('note/not-found', 'no note "n-404"', { noteId: 'n-404' }),
|
||||
}),
|
||||
},
|
||||
})
|
||||
remote.$host = { home: '/home/fixture', isLoopback: true }
|
||||
|
||||
await expect(ctx.remote.notes.list()).resolves.toMatchObject({ error: { code: 'note/not-found' } })
|
||||
})
|
||||
```
|
||||
|
||||
## 验证
|
||||
|
||||
1. `pnpm run build:lib`:签名、码表、namespace 或导出名变过就必须重跑,Client 声明与 codec 由它产出。
|
||||
2. `pnpm run typecheck`:Host 与 Client 两个 program 都过一遍,码表的 merge 落点错了会在这里红。
|
||||
3. 点名跑两侧 spec:`npx vitest run <owner spec> <client spec>`。
|
||||
4. 端点属于产品可见面时补一条录制会话快照,规则见[测试策略](../testing.zh.md)。
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/cookbook/adding-a-settings-card.md
|
||||
adding-a-settings-card.md: 6035cc3c586cd319c89fad95c12610d35742708c
|
||||
adding-a-settings-card.zh.md: 79a4372c24f53e3d31b165d9300af591987da1f6
|
||||
adding-a-settings-card.md: d1104299d319203789c9cd153f36b3f5e33edd10
|
||||
adding-a-settings-card.zh.md: 3ef245d76331015f4d69db52bfbd176dff3e4bcf
|
||||
@@ -8,17 +8,17 @@ The two halves live in one package — the Host half under `src/`, the browser h
|
||||
|
||||
## 1. Register the namespace (Host half)
|
||||
|
||||
The namespace is the join key, so pick it once and spell it in both halves. A consumer that already has a `cordis.yml` entry should register through `installSettingsSection`, which layers the entry under the user document and keeps working when no settings provider is mounted:
|
||||
The namespace is the join key, so pick it once and spell it in both halves. A consumer that already has a `cordis.yml` entry should register through `ctx.settings.installSection()`, which layers the entry under the user document and keeps working when no settings provider is mounted:
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
|
||||
import type {} from '@deepseek-ai/dsh-settings'
|
||||
import z from '@deepseek-ai/schemastery'
|
||||
|
||||
declare function assertReachable(endpoint: string | undefined): void
|
||||
declare function rebuildFromSettings(config: Config): void
|
||||
|
||||
export const MY_PLUGIN_NS = settingsNamespace('my-plugin')
|
||||
export const MY_PLUGIN_NS = 'my-plugin'
|
||||
|
||||
export interface Config {
|
||||
endpoint?: string
|
||||
@@ -32,11 +32,13 @@ export const Config: z<Config> = z.object({
|
||||
|
||||
export function apply(ctx: Context, config: Config) {
|
||||
let source = () => config
|
||||
installSettingsSection(ctx, MY_PLUGIN_NS, Config, config, {
|
||||
// Constraints the schema cannot express refuse the write, not the next use.
|
||||
validate: value => void assertReachable(value.endpoint),
|
||||
setSource: (current) => { source = current },
|
||||
onChange: () => { rebuildFromSettings(source()) },
|
||||
ctx.inject(['settings'], (settingsCtx) => {
|
||||
settingsCtx.settings.installSection(ctx, MY_PLUGIN_NS, Config, config, {
|
||||
// Constraints the schema cannot express refuse the write, not the next use.
|
||||
validate: value => void assertReachable(value.endpoint),
|
||||
setSource: (current) => { source = current },
|
||||
onChange: () => { rebuildFromSettings(source()) },
|
||||
})
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
@@ -8,17 +8,17 @@
|
||||
|
||||
## 1. 注册命名空间(Host 半侧)
|
||||
|
||||
命名空间就是配对用的键,所以只挑一次,并在两个半侧都写出它。已经有 `cordis.yml` entry 的消费方应通过 `installSettingsSection` 注册——它把 entry 层叠在用户文档之下,并在没有挂载 settings provider 时照常工作:
|
||||
命名空间就是配对用的键,所以只挑一次,并在两个半侧都写出它。已经有 `cordis.yml` entry 的消费方应通过 `ctx.settings.installSection()` 注册——它把 entry 层叠在用户文档之下,并在没有挂载 settings provider 时照常工作:
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
|
||||
import type {} from '@deepseek-ai/dsh-settings'
|
||||
import z from '@deepseek-ai/schemastery'
|
||||
|
||||
declare function assertReachable(endpoint: string | undefined): void
|
||||
declare function rebuildFromSettings(config: Config): void
|
||||
|
||||
export const MY_PLUGIN_NS = settingsNamespace('my-plugin')
|
||||
export const MY_PLUGIN_NS = 'my-plugin'
|
||||
|
||||
export interface Config {
|
||||
endpoint?: string
|
||||
@@ -32,11 +32,13 @@ export const Config: z<Config> = z.object({
|
||||
|
||||
export function apply(ctx: Context, config: Config) {
|
||||
let source = () => config
|
||||
installSettingsSection(ctx, MY_PLUGIN_NS, Config, config, {
|
||||
// Constraints the schema cannot express refuse the write, not the next use.
|
||||
validate: value => void assertReachable(value.endpoint),
|
||||
setSource: (current) => { source = current },
|
||||
onChange: () => { rebuildFromSettings(source()) },
|
||||
ctx.inject(['settings'], (settingsCtx) => {
|
||||
settingsCtx.settings.installSection(ctx, MY_PLUGIN_NS, Config, config, {
|
||||
// Constraints the schema cannot express refuse the write, not the next use.
|
||||
validate: value => void assertReachable(value.endpoint),
|
||||
setSource: (current) => { source = current },
|
||||
onChange: () => { rebuildFromSettings(source()) },
|
||||
})
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/cookbook/extension-cookbook.md
|
||||
extension-cookbook.md: bb3f327691d1ff6199407c241f4fa77cd4b23b87
|
||||
extension-cookbook.zh.md: db8f0850bdada35cb6d33eed874c44f20d7be9d3
|
||||
extension-cookbook.md: 0bbd1d0d531de755708da6c7a68b312675ba4b52
|
||||
extension-cookbook.zh.md: 5067c57bef08af65102e011f6d4c4394e03a3f5f
|
||||
@@ -38,8 +38,9 @@ A UI plugin renders from the `session/event` feed (the assistant token stream as
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { brandString } from '@deepseek-ai/dsh-brand'
|
||||
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
||||
import { SessionId } from '@deepseek-ai/dsh-session'
|
||||
import type { SessionId } from '@deepseek-ai/dsh-session'
|
||||
|
||||
declare function render(text: string): void
|
||||
declare function onUserInput(handler: (text: string) => void): void
|
||||
@@ -53,7 +54,7 @@ export function apply(ctx: Context) {
|
||||
render(event.data.chunk.text)
|
||||
}
|
||||
})
|
||||
onUserInput(text => ctx.agents.get(SessionId('client-session'))?.followup(createUserMessage({
|
||||
onUserInput(text => ctx.agents.get(brandString<SessionId>('client-session'))?.followup(createUserMessage({
|
||||
content: [{ type: 'text', text }],
|
||||
source: { kind: 'user' },
|
||||
})))
|
||||
|
||||
@@ -40,8 +40,9 @@ UI 插件从 `session/event` 事件流渲染(助手 token 流以 `assistant/ch
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { brandString } from '@deepseek-ai/dsh-brand'
|
||||
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
||||
import { SessionId } from '@deepseek-ai/dsh-session'
|
||||
import type { SessionId } from '@deepseek-ai/dsh-session'
|
||||
|
||||
declare function render(text: string): void
|
||||
declare function onUserInput(handler: (text: string) => void): void
|
||||
@@ -55,7 +56,7 @@ export function apply(ctx: Context) {
|
||||
render(event.data.chunk.text)
|
||||
}
|
||||
})
|
||||
onUserInput(text => ctx.agents.get(SessionId('client-session'))?.followup(createUserMessage({
|
||||
onUserInput(text => ctx.agents.get(brandString<SessionId>('client-session'))?.followup(createUserMessage({
|
||||
content: [{ type: 'text', text }],
|
||||
source: { kind: 'user' },
|
||||
})))
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/07-into-the-harness.md
|
||||
07-into-the-harness.md: 28e6c2009eec736c92987e0da282f04db249e466
|
||||
07-into-the-harness.zh.md: 603b9cac19e05c997073ad0747622b29790bc555
|
||||
07-into-the-harness.md: a1285e63edcc94f119c64ddef6827c6d8dc4d5c6
|
||||
07-into-the-harness.zh.md: 30c91c8e40d80d0c5c25a0b64ca3568f23a16591
|
||||
@@ -10,8 +10,9 @@ Create `greet-tool.ts` in `tmp/cordis-tutorial`:
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { brandString } from '@deepseek-ai/dsh-brand'
|
||||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||||
import { ToolCallId } from '@deepseek-ai/dsh-llm'
|
||||
import type { ToolCallId } from '@deepseek-ai/dsh-llm'
|
||||
|
||||
export const name = 'greet-tool'
|
||||
export const inject = ['tools']
|
||||
@@ -36,7 +37,7 @@ export function apply(ctx: Context) {
|
||||
// the model. ToolCallId brands the correlation id a provider would issue.
|
||||
void (async () => {
|
||||
const result = await ctx.tools.execute({
|
||||
callId: ToolCallId('demo-1'),
|
||||
callId: brandString<ToolCallId>('demo-1'),
|
||||
name: 'greet',
|
||||
arguments: { name: 'Cordis' },
|
||||
signal: new AbortController().signal,
|
||||
|
||||
@@ -10,8 +10,9 @@
|
||||
|
||||
```ts
|
||||
import type { Context } from '@deepseek-ai/cordis'
|
||||
import { brandString } from '@deepseek-ai/dsh-brand'
|
||||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||||
import { ToolCallId } from '@deepseek-ai/dsh-llm'
|
||||
import type { ToolCallId } from '@deepseek-ai/dsh-llm'
|
||||
|
||||
export const name = 'greet-tool'
|
||||
export const inject = ['tools']
|
||||
@@ -36,7 +37,7 @@ export function apply(ctx: Context) {
|
||||
// the model. ToolCallId brands the correlation id a provider would issue.
|
||||
void (async () => {
|
||||
const result = await ctx.tools.execute({
|
||||
callId: ToolCallId('demo-1'),
|
||||
callId: brandString<ToolCallId>('demo-1'),
|
||||
name: 'greet',
|
||||
arguments: { name: 'Cordis' },
|
||||
signal: new AbortController().signal,
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/deepseek-llm-api-wire-extensions.md
|
||||
deepseek-llm-api-wire-extensions.md: e44246d81494d3e18c7b9eca492635442f9ee82f
|
||||
deepseek-llm-api-wire-extensions.zh.md: 1033ca6608479b6333d316aae830445c962fbbac
|
||||
deepseek-llm-api-wire-extensions.md: fd42609693ac6fbf91dd82b6e73b2d1d06e65a54
|
||||
deepseek-llm-api-wire-extensions.zh.md: 61af718841c8778e8943a1a1c16621a9a6618add
|
||||
@@ -128,7 +128,7 @@ The `session` member is the exact `Session.header`, not a complete runtime Sessi
|
||||
|
||||
### Canonical event envelopes
|
||||
|
||||
Each `events` item is a complete canonical `SessionEvent`, independent of every other request field. An event always carries `type`, `seq`, `time`, and `data`; surface events may additionally carry `sourceEventSeqs` and `surfaceOp`. The sender copies every present member without projection, redaction, or reconstruction.
|
||||
Each `events` item is a complete canonical `SessionEvent`, independent of every other request field. An event always carries `type`, `seq`, `time`, and `data`; it may carry `ignorable: true`, and surface events may additionally carry `sourceEventSeqs` and `surfaceOp`. The sender copies every present member without projection, redaction, or reconstruction.
|
||||
|
||||
### Acceptance watermark and at-least-once delivery
|
||||
|
||||
@@ -156,4 +156,4 @@ Transport and non-2xx failures append no watermark. A crash after endpoint accep
|
||||
|
||||
The request headers expose the Harness application version, one anonymous Harness-home identity, and an optional Session identity. `dsh_plugin_packages` exposes active npm package names and versions. When enabled, `dsh_session_log` may expose the Session working directory, system-prompt snapshots, user and assistant content, raw assistant chunks, tool arguments and results, compaction summaries, feedback, and plugin-owned events. Adapter API keys are not Session events and therefore do not enter the field. A gateway selected through `baseURL` receives the same values as the official endpoint.
|
||||
|
||||
Receivers address extension fields by name, dispatch each field by its own `version`, preserve distinct package versions, and ignore JSON member ordering. A session-log receiver validates the contiguous sequence range before interpreting event types. Every unrecognized canonical event prevents lossless reconstruction. The base request remains usable without either the registry or a particular contribution; field absence means that contribution did not apply to that request.
|
||||
Receivers address extension fields by name, dispatch each field by its own `version`, preserve distinct package versions, and ignore JSON member ordering. A session-log receiver validates the contiguous sequence range before interpreting event types. An unrecognized canonical event without `ignorable: true` prevents lossless reconstruction. The base request remains usable without either the registry or a particular contribution; field absence means that contribution did not apply to that request.
|
||||
@@ -128,7 +128,7 @@
|
||||
|
||||
### 权威事件信封
|
||||
|
||||
每个 `events` 元素都是完整的权威 `SessionEvent`,不依赖任何其他请求字段。事件始终携带 `type`、`seq`、`time` 与 `data`;展示事件还可携带 `sourceEventSeqs` 与 `surfaceOp`。发送方会复制每个已有成员,不执行投影、脱敏或重建。
|
||||
每个 `events` 元素都是完整的权威 `SessionEvent`,不依赖任何其他请求字段。事件始终携带 `type`、`seq`、`time` 与 `data`;它可以携带 `ignorable: true`,展示事件还可携带 `sourceEventSeqs` 与 `surfaceOp`。发送方会复制每个已有成员,不执行投影、脱敏或重建。
|
||||
|
||||
### 接受水位与至少一次交付
|
||||
|
||||
@@ -156,4 +156,4 @@
|
||||
|
||||
请求标头会暴露 Harness 应用版本、一个匿名 Harness-home 身份和可选的会话身份。`dsh_plugin_packages` 会暴露存活 npm 包的名称与版本。启用后,`dsh_session_log` 可能暴露会话工作目录、系统提示词快照、用户与 assistant 内容、原始 assistant 分片、工具参数与结果、压缩摘要、反馈和插件持有的事件。适配器 API key 不是会话事件,因此不会进入该字段。通过 `baseURL` 选择的网关会收到与官方端点相同的值。
|
||||
|
||||
接收方按名称定位扩展字段,按各字段自己的 `version` 分派,保留不同的包版本,并忽略 JSON 成员顺序。会话日志接收方必须先校验连续序号范围,再解释事件类型。每个未知权威事件都会阻止无损重建。即使缺少注册表或某项贡献,基础请求仍然可用;字段缺失表示该项贡献不适用于本次请求。
|
||||
接收方按名称定位扩展字段,按各字段自己的 `version` 分派,保留不同的包版本,并忽略 JSON 成员顺序。会话日志接收方必须先校验连续序号范围,再解释事件类型。遇到不带 `ignorable: true` 的未知权威事件时,接收方无法进行无损重建。即使缺少注册表或某项贡献,基础请求仍然可用;字段缺失表示该项贡献不适用于本次请求。
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
|
||||
event-producer-consumer.md: 086ed4e1d692b69a48da8b68d777a8411a346a94
|
||||
event-producer-consumer.zh.md: 4142e7c55e5364b4bd24ec0518edae8f67b7803a
|
||||
event-producer-consumer.md: 0f6534e56d057a96e2c970856c7b6c82f3c82581
|
||||
event-producer-consumer.zh.md: 0e433d2a735d28098950b431d143cb2263f8cfa4
|
||||
@@ -7,8 +7,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
|
||||
| Event | Mode | Declared in | Dispatchers | Listeners |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:240`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
|
||||
| `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:92`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` |
|
||||
| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:241`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
|
||||
| `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:80`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` |
|
||||
| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:220`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:229`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:351`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
@@ -21,20 +21,20 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:239`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
|
||||
| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:339`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:517`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:544`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:503`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:509`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
|
||||
| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
|
||||
| `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:391`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:397`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:398`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:368`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:374`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:102`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:90`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`credentials`](../packages/credentials/credentials), `remotes` |
|
||||
| `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` |
|
||||
@@ -45,25 +45,25 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:54`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:64`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:76`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:85`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
| `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` |
|
||||
| `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
|
||||
| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:297`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
|
||||
| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:178`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
|
||||
| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:152`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:158`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:169`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
|
||||
| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:298`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
|
||||
| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:179`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
|
||||
| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:159`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:170`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
|
||||
| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`system-prompt`](../packages/core/system-prompt) |
|
||||
| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
|
||||
| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:207`](../packages/core/tools/src/index.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`), [`tools`](../packages/core/tools) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:163`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
|
||||
| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:175`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
|
||||
| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:152`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) |
|
||||
| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
|
||||
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:197`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
|
||||
| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:199`](../packages/core/tools/src/index.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`), [`tools`](../packages/core/tools) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:155`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
|
||||
| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:167`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
|
||||
| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:144`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) |
|
||||
| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
|
||||
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
|
||||
| `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:85`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` |
|
||||
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `inspector`, `modules` |
|
||||
| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
|
||||
|
||||
@@ -9,8 +9,8 @@
|
||||
|
||||
| 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:240`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
|
||||
| `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:92`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` |
|
||||
| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:241`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
|
||||
| `agent-preset/selected` | `emit` | [`packages/preset/agent-presets/src/types.ts:80`](../packages/preset/agent-presets/src/types.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`) | `remotes` |
|
||||
| `agent/created` | `emit` | [`packages/core/agent/src/runtime-types.ts:220`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-presets`](../packages/preset/agent-presets), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `agent/disposed` | `emit` | [`packages/core/agent/src/runtime-types.ts:229`](../packages/core/agent/src/runtime-types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`file-reference-local`](../packages/context/file-reference-local), [`goal-round-driver`](../packages/goal/goal-round-driver), [`subagent`](../packages/subagent/subagent), `tool-agent-team`, [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `agent/error` | `emit` | [`packages/core/agent/src/runtime-types.ts:351`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-round-driver`](../packages/goal/goal-round-driver), `session-controller`, [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
@@ -23,22 +23,22 @@
|
||||
| `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:239`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
|
||||
| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:339`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:517`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:544`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:503`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:509`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
|
||||
| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
|
||||
| `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
|
||||
| `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:379`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:385`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:391`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:397`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:367`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:373`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:102`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:90`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`credentials`](../packages/credentials/credentials), `remotes` |
|
||||
| `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/inspect-query-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:398`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:368`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `cordis/request-run-resolved` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:374`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
|
||||
| `credentials/record-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:96`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
|
||||
| `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:84`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`credentials`](../packages/credentials/credentials), `remotes` |
|
||||
| `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` |
|
||||
| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
|
||||
| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem) |
|
||||
@@ -47,25 +47,25 @@
|
||||
| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/types.ts:23`](../packages/llm/llm/src/types.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`llm`](../packages/llm/llm), `remotes` |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:67`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/test-support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:54`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:64`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:76`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:85`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:52`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compaction`](../packages/compaction/compaction), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`schedule`](../packages/schedule/schedule), `server`, [`session`](../packages/core/session), `session-controller`, [`session-log-deepseek`](../packages/session/session-log-deepseek), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:62`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-presets`](../packages/preset/agent-presets), `agent-team`, [`compaction`](../packages/compaction/compaction), [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/test-support/loader-smoke), `server`, [`session`](../packages/core/session), `session-controller`, [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`tool-workflow`](../packages/workflow/tool-workflow), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:83`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
| `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:105`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `remotes` |
|
||||
| `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:92`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
|
||||
| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:297`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
|
||||
| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:178`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
|
||||
| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:152`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:158`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:169`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
|
||||
| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:298`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
|
||||
| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:179`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
|
||||
| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:153`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:159`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:170`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
|
||||
| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`system-prompt`](../packages/core/system-prompt) |
|
||||
| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
|
||||
| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:207`](../packages/core/tools/src/index.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`), [`tools`](../packages/core/tools) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:163`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
|
||||
| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:175`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
|
||||
| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:152`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) |
|
||||
| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
|
||||
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:197`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
|
||||
| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:199`](../packages/core/tools/src/index.ts) | [`agent-presets`](../packages/preset/agent-presets) (`emit`), [`tools`](../packages/core/tools) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
|
||||
| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:155`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
|
||||
| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:167`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
|
||||
| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:144`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs) |
|
||||
| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:181`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
|
||||
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:189`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) |
|
||||
| `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:85`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` |
|
||||
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:34`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `inspector`, `modules` |
|
||||
| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/module-graph.md
|
||||
module-graph.md: 18c3ce65450f21ca5d10e43ab51265f2063d3423
|
||||
module-graph.zh.md: b0761225c9eaf0fcf0ee6d7816e063983570811d
|
||||
module-graph.md: 101595a035fcbf020265854fb834ac683ac24360
|
||||
module-graph.zh.md: 96cd42d3c6d6ec78c38fefbafd8d6a21ecab1230
|
||||
+184
-585
File diff suppressed because it is too large.
Load diff
+186
-587
File diff suppressed because it is too large.
Load diff
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/persistence-catalog.md
|
||||
persistence-catalog.md: e3b0f5eb0261f760293b5988363e2e16bc98335d
|
||||
persistence-catalog.zh.md: 357e4ac19678beced97294bacb2a3f293b0895ea
|
||||
persistence-catalog.md: 165266e3565581156bceb9a82d9e309a701cb730
|
||||
persistence-catalog.zh.md: 4107127370db86b54cf64214cc713548504f3e69
|
||||
+30
-19
@@ -7,7 +7,7 @@ Every event type that can appear in a session's durable event log: the complete
|
||||
|
||||
This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).
|
||||
|
||||
The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
|
||||
The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, the optional `ignorable` unknown-type skip marker, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.
|
||||
|
||||
## Event envelope
|
||||
|
||||
@@ -63,6 +63,17 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
/** Unix epoch milliseconds. */
|
||||
time: number
|
||||
data: SessionEventMap[K]
|
||||
/**
|
||||
* Marks an event a reader may safely skip when it does not recognize
|
||||
* `type`. Absent means required: a reader meeting an unrecognized type
|
||||
* without this marker MUST refuse to reconstruct the session instead of
|
||||
* silently dropping the event, because an unrecognized required event may
|
||||
* change how the rest of the log is interpreted. A writer sets `true` only
|
||||
* on purely informational records whose loss cannot affect reconstruction;
|
||||
* defaulting to required means a forgotten marker over-refuses (an
|
||||
* inconvenience) rather than silently resuming a gutted session.
|
||||
*/
|
||||
ignorable?: true
|
||||
} & (K extends SurfaceEventType ? {
|
||||
/**
|
||||
* Seq numbers of earlier events that this event cites as sources
|
||||
@@ -79,7 +90,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}[T]
|
||||
```
|
||||
|
||||
Sources: [`packages/core/session/src/types.ts:328`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:335`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:364`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:396`](../packages/core/session/src/types.ts)
|
||||
Sources: [`packages/core/session/src/types.ts:323`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:330`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:359`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:391`](../packages/core/session/src/types.ts)
|
||||
|
||||
## Events
|
||||
|
||||
@@ -104,7 +115,7 @@ Sources: [`packages/core/session/src/types.ts:328`](../packages/core/session/src
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/core/agent/src/types.ts:86`](../packages/core/agent/src/types.ts)
|
||||
Source: [`packages/core/agent/src/types.ts:87`](../packages/core/agent/src/types.ts)
|
||||
|
||||
### `agent-preset/*`
|
||||
|
||||
@@ -204,7 +215,7 @@ Source: [`packages/interaction/user-approval/src/index.ts:32`](../packages/inter
|
||||
|
||||
Types: [StreamChunk](subsystems/llm-streaming.md)
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="assistantmessage--surface"></a>
|
||||
|
||||
@@ -226,7 +237,7 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/
|
||||
|
||||
Types: [TokenUsage](subsystems/llm-streaming.md)
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:262`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:257`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `command/*`
|
||||
|
||||
@@ -501,7 +512,7 @@ Source: [`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src
|
||||
'model/selection': ModelSelection
|
||||
```
|
||||
|
||||
Source: [`packages/api/session-controller/src/types.ts:40`](../packages/api/session-controller/src/types.ts)
|
||||
Source: [`packages/api/session-controller/src/types.ts:41`](../packages/api/session-controller/src/types.ts)
|
||||
|
||||
### `permission/*`
|
||||
|
||||
@@ -536,7 +547,7 @@ Source: [`packages/interaction/permission-presets/src/index.ts:53`](../packages/
|
||||
'plan/mode': { active: boolean }
|
||||
```
|
||||
|
||||
Source: [`packages/plan/plan-mode/src/index.ts:47`](../packages/plan/plan-mode/src/index.ts)
|
||||
Source: [`packages/plan/plan-mode/src/index.ts:46`](../packages/plan/plan-mode/src/index.ts)
|
||||
|
||||
### `request/*`
|
||||
|
||||
@@ -552,7 +563,7 @@ Source: [`packages/plan/plan-mode/src/index.ts:47`](../packages/plan/plan-mode/s
|
||||
'request/context': RequestContext
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:301`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="requestheader--log-only"></a>
|
||||
|
||||
@@ -571,7 +582,7 @@ Source: [`packages/core/session/src/types.ts:301`](../packages/core/session/src/
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:291`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:286`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `sandbox/*`
|
||||
|
||||
@@ -646,7 +657,7 @@ Source: [`packages/schedule/schedule/src/types.ts:219`](../packages/schedule/sch
|
||||
'session/end-seed': Record<string, never>
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:324`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:319`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="sessiontitle--log-only"></a>
|
||||
|
||||
@@ -662,7 +673,7 @@ Source: [`packages/core/session/src/types.ts:324`](../packages/core/session/src/
|
||||
|
||||
Types: [SessionTitleEventData](subsystems/session-title.md)
|
||||
|
||||
Source: [`packages/session/session-title/src/index.ts:75`](../packages/session/session-title/src/index.ts)
|
||||
Source: [`packages/session/session-title/src/index.ts:76`](../packages/session/session-title/src/index.ts)
|
||||
|
||||
<a id="sessiontitle-llm-request--log-only"></a>
|
||||
|
||||
@@ -675,7 +686,7 @@ Source: [`packages/session/session-title/src/index.ts:75`](../packages/session/s
|
||||
|
||||
Types: [SessionTitleLlmRequestEventData](subsystems/session-title.md)
|
||||
|
||||
Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
|
||||
Source: [`packages/session/session-title-llm/src/index.ts:44`](../packages/session/session-title-llm/src/index.ts)
|
||||
|
||||
### `session-log-deepseek/*`
|
||||
|
||||
@@ -706,7 +717,7 @@ Source: [`packages/session/session-log-deepseek/src/types.ts:26`](../packages/se
|
||||
'step/end': { turn: number; step: number }
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:241`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="stepstart--log-only"></a>
|
||||
|
||||
@@ -717,7 +728,7 @@ Source: [`packages/core/session/src/types.ts:241`](../packages/core/session/src/
|
||||
'step/start': { turn: number; step: number }
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:239`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `subagent/*`
|
||||
|
||||
@@ -848,7 +859,7 @@ Source: [`packages/todo/tool-todo/src/types.ts:31`](../packages/todo/tool-todo/s
|
||||
|
||||
Types: [ToolCallId](subsystems/core.md)
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:268`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="toolcode-dispatch--log-only"></a>
|
||||
|
||||
@@ -923,7 +934,7 @@ Source: [`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types
|
||||
}
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:280`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `tool-workflow/*`
|
||||
|
||||
@@ -1003,7 +1014,7 @@ Source: [`packages/workflow/tool-workflow/src/types.ts:47`](../packages/workflow
|
||||
|
||||
Types: [TurnEndReason](subsystems/session.md)
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:237`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:232`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="turnstart--log-only"></a>
|
||||
|
||||
@@ -1019,7 +1030,7 @@ Source: [`packages/core/session/src/types.ts:237`](../packages/core/session/src/
|
||||
'turn/start': { turn: number }
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:228`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:223`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `user/*`
|
||||
|
||||
@@ -1038,7 +1049,7 @@ Source: [`packages/core/session/src/types.ts:228`](../packages/core/session/src/
|
||||
'user/message': UserMessage
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:249`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:244`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `web/*`
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
|
||||
英文源文件根据源码生成(`scripts/gen-persistence-catalog.ts`),并由 `pnpm run verify-persistence-catalog`(`doc-sync`(文档同步门禁)的一部分)验证新鲜度;本中文文件作为经评审对侧通过双语配对维护。声明块保留源码声明和嵌套属性的 JSDoc,只移除其所在接口/模块带来的缩进,并使用 `ts persistence-catalog` 围栏(doc-typecheck 会跳过这些围栏,因为声明引用了其所属模块中的类型)。payload 中的类型名称会链接到记录该类型的页面。参见 [persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md)。
|
||||
|
||||
以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`,以及条件字段 `surfaceOp`/`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员:它会生成一条 LLM(大语言模型)消息,并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件:这类记录可持久化、可回放,但不参与派生历史。每个 payload 均可进行 JSON 序列化(在 `Session.append` 处强制执行),整个格式固定为 `SESSION_FORMAT_VERSION = 0`:这是预发布格式,不暗示任何兼容性(参见[版本立场](subsystems/persistence.zh.md))。范围仅限本仓库中的包;下游插件可以继续合并其他事件类型,而这些类型按设计不属于本目录。
|
||||
以下信封声明组合了每个事件的 `type`、单调递增的 `seq`、以 epoch 毫秒表示的 `time`、`data`、可选的未知类型跳过标记 `ignorable`,以及条件字段 `surfaceOp`/`sourceEventSeqs`。**surface** 表示 `SurfaceEventType` 成员:它会生成一条 LLM(大语言模型)消息,并声明该事件如何加入 surface 列表。**log-only** 表示其他所有事件:这类记录可持久化、可回放,但不参与派生历史。每个 payload 均可进行 JSON 序列化(在 `Session.append` 处强制执行),整个格式固定为 `SESSION_FORMAT_VERSION = 0`:这是预发布格式,不暗示任何兼容性(参见[版本立场](subsystems/persistence.zh.md))。范围仅限本仓库中的包;下游插件可以继续合并其他事件类型,而这些类型按设计不属于本目录。
|
||||
|
||||
## 事件信封
|
||||
|
||||
@@ -65,6 +65,17 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
/** Unix epoch milliseconds. */
|
||||
time: number
|
||||
data: SessionEventMap[K]
|
||||
/**
|
||||
* Marks an event a reader may safely skip when it does not recognize
|
||||
* `type`. Absent means required: a reader meeting an unrecognized type
|
||||
* without this marker MUST refuse to reconstruct the session instead of
|
||||
* silently dropping the event, because an unrecognized required event may
|
||||
* change how the rest of the log is interpreted. A writer sets `true` only
|
||||
* on purely informational records whose loss cannot affect reconstruction;
|
||||
* defaulting to required means a forgotten marker over-refuses (an
|
||||
* inconvenience) rather than silently resuming a gutted session.
|
||||
*/
|
||||
ignorable?: true
|
||||
} & (K extends SurfaceEventType ? {
|
||||
/**
|
||||
* Seq numbers of earlier events that this event cites as sources
|
||||
@@ -81,7 +92,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}[T]
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:321`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:328`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:357`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:389`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:323`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:330`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:359`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:391`](../packages/core/session/src/types.ts)
|
||||
|
||||
## 事件
|
||||
|
||||
@@ -106,7 +117,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/core/agent/src/types.ts:86`](../packages/core/agent/src/types.ts)
|
||||
来源:[`packages/core/agent/src/types.ts:87`](../packages/core/agent/src/types.ts)
|
||||
|
||||
### `agent-preset/*`
|
||||
|
||||
@@ -206,7 +217,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
类型:[StreamChunk](subsystems/llm-streaming.zh.md)
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:249`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="assistantmessage--surface"></a>
|
||||
|
||||
@@ -228,7 +239,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
类型:[TokenUsage](subsystems/llm-streaming.zh.md)
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:260`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:257`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `command/*`
|
||||
|
||||
@@ -503,7 +514,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'model/selection': ModelSelection
|
||||
```
|
||||
|
||||
来源:[`packages/api/session-controller/src/types.ts:39`](../packages/api/session-controller/src/types.ts)
|
||||
来源:[`packages/api/session-controller/src/types.ts:41`](../packages/api/session-controller/src/types.ts)
|
||||
|
||||
### `permission/*`
|
||||
|
||||
@@ -538,7 +549,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'plan/mode': { active: boolean }
|
||||
```
|
||||
|
||||
来源:[`packages/plan/plan-mode/src/index.ts:47`](../packages/plan/plan-mode/src/index.ts)
|
||||
来源:[`packages/plan/plan-mode/src/index.ts:46`](../packages/plan/plan-mode/src/index.ts)
|
||||
|
||||
### `request/*`
|
||||
|
||||
@@ -554,7 +565,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'request/context': RequestContext
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:294`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="requestheader--log-only"></a>
|
||||
|
||||
@@ -573,7 +584,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:289`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:286`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `sandbox/*`
|
||||
|
||||
@@ -648,7 +659,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'session/end-seed': Record<string, never>
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:317`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:319`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="sessiontitle--log-only"></a>
|
||||
|
||||
@@ -664,7 +675,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
类型:[SessionTitleEventData](subsystems/session-title.zh.md)
|
||||
|
||||
来源:[`packages/session/session-title/src/index.ts:75`](../packages/session/session-title/src/index.ts)
|
||||
来源:[`packages/session/session-title/src/index.ts:76`](../packages/session/session-title/src/index.ts)
|
||||
|
||||
<a id="sessiontitle-llm-request--log-only"></a>
|
||||
|
||||
@@ -677,7 +688,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
类型:[SessionTitleLlmRequestEventData](subsystems/session-title.zh.md)
|
||||
|
||||
来源:[`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts)
|
||||
来源:[`packages/session/session-title-llm/src/index.ts:44`](../packages/session/session-title-llm/src/index.ts)
|
||||
|
||||
### `session-log-deepseek/*`
|
||||
|
||||
@@ -708,7 +719,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'step/end': { turn: number; step: number }
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:239`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:236`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="stepstart--log-only"></a>
|
||||
|
||||
@@ -719,7 +730,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'step/start': { turn: number; step: number }
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:237`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `subagent/*`
|
||||
|
||||
@@ -850,7 +861,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
类型:[ToolCallId](subsystems/core.zh.md)
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:263`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="toolcode-dispatch--log-only"></a>
|
||||
|
||||
@@ -925,7 +936,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:278`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `tool-workflow/*`
|
||||
|
||||
@@ -1005,7 +1016,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
类型:[TurnEndReason](subsystems/session.zh.md)
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:235`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:232`](../packages/core/session/src/types.ts)
|
||||
|
||||
<a id="turnstart--log-only"></a>
|
||||
|
||||
@@ -1021,7 +1032,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'turn/start': { turn: number }
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:223`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `user/*`
|
||||
|
||||
@@ -1040,7 +1051,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
'user/message': UserMessage
|
||||
```
|
||||
|
||||
来源:[`packages/core/session/src/types.ts:247`](../packages/core/session/src/types.ts)
|
||||
来源:[`packages/core/session/src/types.ts:244`](../packages/core/session/src/types.ts)
|
||||
|
||||
### `web/*`
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/core.md
|
||||
core.md: 5f66abccad5ad691f855c49923a49a276c983f7d
|
||||
core.zh.md: 36521157b6ac121cf0e9a4eee67706bec3a37735
|
||||
core.md: 5fef3af1c8c5edb938f08dbbb1cb5cd772e05858
|
||||
core.zh.md: 728dbef3a52faa20c9df8849175ee88276a906e3
|
||||
+29
-10
@@ -358,9 +358,9 @@ Two large discriminated unions are the ones consumers `switch` over most: **`Str
|
||||
|
||||
### Branded IDs
|
||||
|
||||
IDs passed between packages are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `ToolCallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
|
||||
IDs passed between packages are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `ToolCallId` is expected). Construction uses the shared `brandString<T>()` helper or an owner-defined validating factory; comparison, logging, and JSON behave as ordinary strings.
|
||||
|
||||
The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
|
||||
The `Branded<B>` primitive and stateless constructor live in [dsh-brand](../../packages/util/brand), which has no harness capability dependency. `brandString<T>()` applies a compile-time-only string brand.
|
||||
|
||||
Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
|
||||
|
||||
@@ -467,6 +467,25 @@ async list(): Promise<AgentPreset[]>
|
||||
*/
|
||||
@Remote('list') async remoteExportList(): Promise<AgentPresetRoster>
|
||||
|
||||
/**
|
||||
* Every preset's composition as flattened plugin rows, for plugin-listing
|
||||
* surfaces beside the roster's own picker.
|
||||
*
|
||||
* A preset with a live standing mount answers from its newest generation's
|
||||
* Loader entries — the composition new sessions join — even when the file
|
||||
* behind it has since been edited into an unreadable state: the mount is
|
||||
* what sessions actually run, so the broken verdict only applies to a
|
||||
* preset nothing composed. One never composed since boot answers from its
|
||||
* file, with `!!js` disabled gates evaluated against the Loader context so
|
||||
* both answers reflect the same host. Reading never mounts: an unmounted
|
||||
* preset is parsed, not composed, so listing a preset's plugins cannot
|
||||
* activate them early. A composition that stopped reading between
|
||||
* discovery's health verdict and this read is reported broken with the
|
||||
* raced reason rather than dropped.
|
||||
* @returns one composition per roster preset, in roster order.
|
||||
*/
|
||||
async compositionInventory(): Promise<AgentPresetComposition[]>
|
||||
|
||||
/**
|
||||
* Resolve one preset by id.
|
||||
*
|
||||
@@ -545,8 +564,8 @@ async read(id: string): Promise<string>
|
||||
* One preset's composition text with the roster row it belongs to.
|
||||
* @param agentPreset - the preset id.
|
||||
* @returns the composition beside its trust and published metadata.
|
||||
* @throws {TypertRemoteFailure} `bad-request` for an empty id, or
|
||||
* `agent-preset-not-found` when no configured root supplies it.
|
||||
* @throws {RemoteError} `gateway/bad-request` for an empty id, or
|
||||
* `agent-preset/not-found` when no configured root supplies it.
|
||||
*/
|
||||
@Remote('read') async readDocument(agentPreset: string): Promise<AgentPresetDocument>
|
||||
|
||||
@@ -573,8 +592,8 @@ async copy(from: string, id: string, name?: string): Promise<void>
|
||||
* @param id - the new preset id.
|
||||
* @param name - the copy's optional display name.
|
||||
* @returns once the copy is stored.
|
||||
* @throws {TypertRemoteFailure} with the corresponding stable preset code
|
||||
* and details when the copy is refused.
|
||||
* @throws {RemoteError} with the corresponding stable preset code and
|
||||
* details when the copy is refused.
|
||||
*/
|
||||
@Remote('copy') async remoteExportCopy(from: string, id: string, name?: string): Promise<void>
|
||||
|
||||
@@ -590,8 +609,8 @@ async remove(id: string): Promise<void>
|
||||
* Delete one preset through the Remote API.
|
||||
* @param id - the preset id.
|
||||
* @returns once the preset is deleted.
|
||||
* @throws {TypertRemoteFailure} with the corresponding stable preset code
|
||||
* and details when deletion is refused.
|
||||
* @throws {RemoteError} with the corresponding stable preset code and
|
||||
* details when deletion is refused.
|
||||
*/
|
||||
@Remote('deletePreset') async remoteExportDelete(id: string): Promise<void>
|
||||
|
||||
@@ -642,8 +661,8 @@ async recompose(agentCtx: Context, id: string): Promise<AgentPreset>
|
||||
* @param agent - the session's live agent, resolved from the wire identity.
|
||||
* @param agentPreset - the preset to compose the agent from instead.
|
||||
* @returns the preset id that was recorded.
|
||||
* @throws {TypertRemoteFailure} with `bad-request`, `agent-preset-locked`,
|
||||
* `agent-preset-not-found`, or `agent-preset-invalid` when refused.
|
||||
* @throws {RemoteError} with `gateway/bad-request`, `agent-preset/locked`,
|
||||
* `agent-preset/not-found`, or `agent-preset/invalid` when refused.
|
||||
*/
|
||||
@Remote('select') async select(agent: Agent, agentPreset: string): Promise<string>
|
||||
|
||||
|
||||
+29
-10
@@ -368,9 +368,9 @@ declare module '@deepseek-ai/dsh-llm' {
|
||||
|
||||
### 品牌化 ID
|
||||
|
||||
在包之间传递的 ID 都经过**品牌化**——结构上是字符串,但在类型层面不可互换(不能把 `SessionId` 传给需要 `ToolCallId` 的位置)。每种类型通过各自的工厂构造;比较、日志记录和 JSON 行为与普通字符串相同。
|
||||
在包之间传递的 ID 都经过**品牌化**——结构上是字符串,但在类型层面不可互换(不能把 `SessionId` 传给需要 `ToolCallId` 的位置)。构造使用共享 `brandString<T>()` helper 或所属方自定义的校验工厂;比较、日志记录和 JSON 行为与普通字符串相同。
|
||||
|
||||
`Branded<B>` 原语位于独立的纯类型包 [dsh-brand](../../packages/util/brand) 中(没有运行时代码,也不依赖 harness 包),因此任何包都能品牌化其拥有的 id,而无需依赖无关的能力包。
|
||||
`Branded<B>` 原语与无状态构造函数位于 [dsh-brand](../../packages/util/brand),该包不依赖 harness 能力。`brandString<T>()` 应用仅编译期存在的字符串品牌。
|
||||
|
||||
源码:[`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
|
||||
|
||||
@@ -477,6 +477,25 @@ async list(): Promise<AgentPreset[]>
|
||||
*/
|
||||
@Remote('list') async remoteExportList(): Promise<AgentPresetRoster>
|
||||
|
||||
/**
|
||||
* Every preset's composition as flattened plugin rows, for plugin-listing
|
||||
* surfaces beside the roster's own picker.
|
||||
*
|
||||
* A preset with a live standing mount answers from its newest generation's
|
||||
* Loader entries — the composition new sessions join — even when the file
|
||||
* behind it has since been edited into an unreadable state: the mount is
|
||||
* what sessions actually run, so the broken verdict only applies to a
|
||||
* preset nothing composed. One never composed since boot answers from its
|
||||
* file, with `!!js` disabled gates evaluated against the Loader context so
|
||||
* both answers reflect the same host. Reading never mounts: an unmounted
|
||||
* preset is parsed, not composed, so listing a preset's plugins cannot
|
||||
* activate them early. A composition that stopped reading between
|
||||
* discovery's health verdict and this read is reported broken with the
|
||||
* raced reason rather than dropped.
|
||||
* @returns one composition per roster preset, in roster order.
|
||||
*/
|
||||
async compositionInventory(): Promise<AgentPresetComposition[]>
|
||||
|
||||
/**
|
||||
* Resolve one preset by id.
|
||||
*
|
||||
@@ -555,8 +574,8 @@ async read(id: string): Promise<string>
|
||||
* One preset's composition text with the roster row it belongs to.
|
||||
* @param agentPreset - the preset id.
|
||||
* @returns the composition beside its trust and published metadata.
|
||||
* @throws {TypertRemoteFailure} `bad-request` for an empty id, or
|
||||
* `agent-preset-not-found` when no configured root supplies it.
|
||||
* @throws {RemoteError} `gateway/bad-request` for an empty id, or
|
||||
* `agent-preset/not-found` when no configured root supplies it.
|
||||
*/
|
||||
@Remote('read') async readDocument(agentPreset: string): Promise<AgentPresetDocument>
|
||||
|
||||
@@ -583,8 +602,8 @@ async copy(from: string, id: string, name?: string): Promise<void>
|
||||
* @param id - the new preset id.
|
||||
* @param name - the copy's optional display name.
|
||||
* @returns once the copy is stored.
|
||||
* @throws {TypertRemoteFailure} with the corresponding stable preset code
|
||||
* and details when the copy is refused.
|
||||
* @throws {RemoteError} with the corresponding stable preset code and
|
||||
* details when the copy is refused.
|
||||
*/
|
||||
@Remote('copy') async remoteExportCopy(from: string, id: string, name?: string): Promise<void>
|
||||
|
||||
@@ -600,8 +619,8 @@ async remove(id: string): Promise<void>
|
||||
* Delete one preset through the Remote API.
|
||||
* @param id - the preset id.
|
||||
* @returns once the preset is deleted.
|
||||
* @throws {TypertRemoteFailure} with the corresponding stable preset code
|
||||
* and details when deletion is refused.
|
||||
* @throws {RemoteError} with the corresponding stable preset code and
|
||||
* details when deletion is refused.
|
||||
*/
|
||||
@Remote('deletePreset') async remoteExportDelete(id: string): Promise<void>
|
||||
|
||||
@@ -652,8 +671,8 @@ async recompose(agentCtx: Context, id: string): Promise<AgentPreset>
|
||||
* @param agent - the session's live agent, resolved from the wire identity.
|
||||
* @param agentPreset - the preset to compose the agent from instead.
|
||||
* @returns the preset id that was recorded.
|
||||
* @throws {TypertRemoteFailure} with `bad-request`, `agent-preset-locked`,
|
||||
* `agent-preset-not-found`, or `agent-preset-invalid` when refused.
|
||||
* @throws {RemoteError} with `gateway/bad-request`, `agent-preset/locked`,
|
||||
* `agent-preset/not-found`, or `agent-preset/invalid` when refused.
|
||||
*/
|
||||
@Remote('select') async select(agent: Agent, agentPreset: string): Promise<string>
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/credentials.md
|
||||
credentials.md: 60cd388fc18fe239b9ee5207d77d3b5561b7a3b3
|
||||
credentials.zh.md: 5ca47fac6c36c14eb1ee0aa8a6cb6a8b5e3eb9c4
|
||||
credentials.md: 5ae53a19140f423e1c52334c40f25fca7d3ed754
|
||||
credentials.zh.md: b6d5d8eb3960edd68a96a32a41c591e61f2c8b5e
|
||||
@@ -227,9 +227,10 @@ Host service backing the generated `ctx.remote.credentials` namespace. It carrie
|
||||
* Describe several references for one configuration surface. Batched because
|
||||
* a settings page describes every reference its rows name at once, and one
|
||||
* round trip keeps those rows from settling separately.
|
||||
* @param refs - reference names, at most {@link MAX_DESCRIBE_REFS}; a name outside the grammar rejects the whole call as `bad-request`.
|
||||
* @param refs - reference names, at most {@link MAX_DESCRIBE_REFS}; a name outside the grammar
|
||||
* rejects the whole call as `gateway/bad-request`.
|
||||
* @returns one view per requested name, keyed by that name.
|
||||
* @throws TypertRemoteFailure when the request is invalid or no credential provider is mounted.
|
||||
* @throws RemoteError when the request is invalid or no credential provider is mounted.
|
||||
*/
|
||||
@Remote async describe(refs: string[]): Promise<Record<string, CredentialInfo>>
|
||||
|
||||
@@ -238,14 +239,14 @@ Host service backing the generated `ctx.remote.credentials` namespace. It carrie
|
||||
* this direction only: no read path returns it.
|
||||
* @param ref - reference name to store under.
|
||||
* @param value - the non-empty secret value.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote async set(ref: string, value: string): Promise<void>
|
||||
|
||||
/**
|
||||
* Remove one reference from a configuration surface.
|
||||
* @param ref - reference name to remove.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote async unset(ref: string): Promise<void>
|
||||
```
|
||||
|
||||
@@ -227,9 +227,10 @@ Host service backing the generated `ctx.remote.credentials` namespace. It carrie
|
||||
* Describe several references for one configuration surface. Batched because
|
||||
* a settings page describes every reference its rows name at once, and one
|
||||
* round trip keeps those rows from settling separately.
|
||||
* @param refs - reference names, at most {@link MAX_DESCRIBE_REFS}; a name outside the grammar rejects the whole call as `bad-request`.
|
||||
* @param refs - reference names, at most {@link MAX_DESCRIBE_REFS}; a name outside the grammar
|
||||
* rejects the whole call as `gateway/bad-request`.
|
||||
* @returns one view per requested name, keyed by that name.
|
||||
* @throws TypertRemoteFailure when the request is invalid or no credential provider is mounted.
|
||||
* @throws RemoteError when the request is invalid or no credential provider is mounted.
|
||||
*/
|
||||
@Remote async describe(refs: string[]): Promise<Record<string, CredentialInfo>>
|
||||
|
||||
@@ -238,14 +239,14 @@ Host service backing the generated `ctx.remote.credentials` namespace. It carrie
|
||||
* this direction only: no read path returns it.
|
||||
* @param ref - reference name to store under.
|
||||
* @param value - the non-empty secret value.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote async set(ref: string, value: string): Promise<void>
|
||||
|
||||
/**
|
||||
* Remove one reference from a configuration surface.
|
||||
* @param ref - reference name to remove.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote async unset(ref: string): Promise<void>
|
||||
```
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
|
||||
llm-streaming.md: e37356d91e75334987b6fc707744f2376df1b2fc
|
||||
llm-streaming.zh.md: 05f24bed6beff9508db88e60af7b259eda33f474
|
||||
llm-streaming.md: 6867ae292d77474bcedc1466ae0ce6b1fc1c92d3
|
||||
llm-streaming.zh.md: b75e24f2e9010b4fb08c035f14bc4e91dc3971ef
|
||||
@@ -929,7 +929,7 @@ async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, sig
|
||||
* @param request - endpoint, protocol, and one-shot credential to use.
|
||||
* @param signal - caller cancellation supplied by the Remote carrier.
|
||||
* @returns advertised models in endpoint order.
|
||||
* @throws TypertRemoteFailure with `model-discovery-failed` when discovery refuses or fails.
|
||||
* @throws RemoteError with `llm/model-discovery-rejected` when discovery refuses or fails.
|
||||
*/
|
||||
@Remote('discoverModels') async remoteDiscoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, signal: AbortSignal, ): Promise<LlmDiscoveredModel[]>
|
||||
|
||||
|
||||
@@ -935,7 +935,7 @@ async discoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, sig
|
||||
* @param request - endpoint, protocol, and one-shot credential to use.
|
||||
* @param signal - caller cancellation supplied by the Remote carrier.
|
||||
* @returns advertised models in endpoint order.
|
||||
* @throws TypertRemoteFailure with `model-discovery-failed` when discovery refuses or fails.
|
||||
* @throws RemoteError with `llm/model-discovery-rejected` when discovery refuses or fails.
|
||||
*/
|
||||
@Remote('discoverModels') async remoteDiscoverModels( settingsNs: string, request: LlmModelDiscoveryRequest, signal: AbortSignal, ): Promise<LlmDiscoveredModel[]>
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/persistence.md
|
||||
persistence.md: f73b9ab01c232c4d4fec5aa51e5250c60b9337da
|
||||
persistence.zh.md: 061c29f6b54c41137e3c764e9a7804f411f63f17
|
||||
persistence.md: 697cbf38ddbdea88947da86d10fc05b0cbc9ddb0
|
||||
persistence.zh.md: 6e12ed26fda7d11a8dfe6fd6575395d2f1b5500a
|
||||
@@ -91,7 +91,7 @@ interface SessionHeader {
|
||||
|
||||
## Format refusal — logs a build cannot faithfully read
|
||||
|
||||
A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. After legacy-shape normalization, an event type outside this build's generated set (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) also refuses reconstruction because silently skipping it could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating this format version's header fields or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt"; SQLite gates whole-file structure through its own `SCHEMA_VERSION` pragma first. Design rationale and the deferred upgrader chain live in the [fail-closed event-vocabulary note](../../.agents/notes/implemented/simplification/2026-08-25-fail-closed-session-event-vocabulary.md).
|
||||
A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. After legacy-shape normalization, an event type outside this build's generated vocabulary (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) refuses the same way unless the event's envelope carries `ignorable: true` — silently skipping an unrecognized required event could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating this format version's header shape or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt"; SQLite gates whole-file structure through its own `SCHEMA_VERSION` pragma first. Design rationale and the deferred upgrader chain live in the [session-log-version-mechanism note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md).
|
||||
|
||||
## `CreateSessionOptions` — seeding and metadata
|
||||
|
||||
@@ -233,7 +233,7 @@ interface SessionPersistenceSnapshot {
|
||||
All implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass the shared `runPersistenceContract` suite:
|
||||
|
||||
- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
|
||||
- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — an opt-in `node:sqlite` backend using schema 19 to store exact same-block delta runs in bounded physical `text-chunks`, `reasoning-chunks`, and `tool-call-chunks` rows. It reconstructs the complete logical event stream before returning it, packs only newly durable batches, and rejects older schemas rather than migrating them.
|
||||
- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)** — an opt-in `node:sqlite` backend using schema 20 to store exact same-block delta runs in bounded physical `text-chunks`, `reasoning-chunks`, and `tool-call-chunks` rows. It reconstructs the complete logical event stream before returning it, packs only newly durable batches, and rejects older schemas rather than migrating them.
|
||||
|
||||
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
||||
|
||||
|
||||
@@ -91,7 +91,7 @@ interface SessionHeader {
|
||||
|
||||
## 格式拒绝:本构建无法可靠读取的日志
|
||||
|
||||
后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志,它与 `SessionPersistenceCorruptionError` 区分,因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时,消息说明方向("由更新的 harness 写入,请升级 harness 后打开");比它旧时说明本构建没有升级路径。经过 legacy 形状归一化后,本构建生成集合(`KNOWN_SESSION_EVENT_TYPES`,由 `gen-persistence-catalog` 生成)之外的事件类型也会拒绝重建,因为静默跳过该事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时,消息附上原始日志路径,被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本,先于校验本格式版本的 header 字段和解码任何事件行,因此结构完全不同的未来格式仍会报告升级方向,绝不会报"损坏";SQLite 则先由自己的 `SCHEMA_VERSION` pragma 把关整个文件的结构。设计理由与推迟建设的升级器链见[事件词汇表显式拒绝 Agent Note](../../.agents/notes/implemented/simplification/2026-08-25-fail-closed-session-event-vocabulary.zh.md)。
|
||||
后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志,它与 `SessionPersistenceCorruptionError` 区分,因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时,消息说明方向("由更新的 harness 写入,请升级 harness 后打开");比它旧时说明本构建没有升级路径。经过 legacy 形状归一化后,本构建生成词汇表(`KNOWN_SESSION_EVENT_TYPES`,由 `gen-persistence-catalog` 生成)之外的事件类型同样被拒绝,除非该事件的信封带 `ignorable: true`:静默跳过一个不认识的必需事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时,消息附上原始日志路径,被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本,先于本格式版本的 header 形状校验和任何事件行解码,因此结构完全不同的未来格式仍会报告升级方向,绝不会报"损坏";SQLite 则先由自己的 `SCHEMA_VERSION` pragma 把关整个文件的结构。设计理由与推迟建设的升级器链见 [session-log 版本机制 Agent Note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.zh.md)。
|
||||
|
||||
## `CreateSessionOptions`:seed 与元数据
|
||||
|
||||
@@ -233,7 +233,7 @@ interface SessionPersistenceSnapshot {
|
||||
两者都实现同一个抽象 `SessionPersistence`(在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots,观察方法可选支持取消),并通过共享的 `runPersistenceContract` 套件:
|
||||
|
||||
- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——逐会话仅追加的逻辑 JSONL 日志,默认存储为带 checksum 的连续 Zstandard frame,也可配置为原始行;支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。
|
||||
- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**:一个可选启用的 `node:sqlite` 后端,使用 schema 19 把同一分片块中字段完全匹配的 delta 连续段存为有界物理 `text-chunks`、`reasoning-chunks` 与 `tool-call-chunks` 行。它在返回前重建完整逻辑事件流,只打包新增的持久批次,并拒绝旧 schema,而不是执行迁移。
|
||||
- **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**:一个可选启用的 `node:sqlite` 后端,使用 schema 20 把同一分片块中字段完全匹配的 delta 连续段存为有界物理 `text-chunks`、`reasoning-chunks` 与 `tool-call-chunks` 行。它在返回前重建完整逻辑事件流,只打包新增的持久批次,并拒绝旧 schema,而不是执行迁移。
|
||||
|
||||
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/session.md
|
||||
session.md: f3c246f7a77386a088f0559d233031bdb8d997f8
|
||||
session.zh.md: bc706a11e9b504f6806cbf7c1beb67b972fb4f75
|
||||
session.md: d35395fb80a6558e15b82cdb76559f59e492f425
|
||||
session.zh.md: d3bc750b5c198e38efa94c88f95dcb9406c9059b
|
||||
@@ -201,6 +201,17 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
/** Unix epoch milliseconds. */
|
||||
time: number
|
||||
data: SessionEventMap[K]
|
||||
/**
|
||||
* Marks an event a reader may safely skip when it does not recognize
|
||||
* `type`. Absent means required: a reader meeting an unrecognized type
|
||||
* without this marker MUST refuse to reconstruct the session instead of
|
||||
* silently dropping the event, because an unrecognized required event may
|
||||
* change how the rest of the log is interpreted. A writer sets `true` only
|
||||
* on purely informational records whose loss cannot affect reconstruction;
|
||||
* defaulting to required means a forgotten marker over-refuses (an
|
||||
* inconvenience) rather than silently resuming a gutted session.
|
||||
*/
|
||||
ignorable?: true
|
||||
} & (K extends SurfaceEventType ? {
|
||||
/**
|
||||
* Seq numbers of earlier events that this event cites as sources
|
||||
@@ -434,7 +445,7 @@ declare class Session {
|
||||
* Map/Set/Date/class instance), or when the candidate violates the
|
||||
* canonical surface contract (marker shape and eligibility, unique
|
||||
* earlier source-event references, positional replacement validity, and complete
|
||||
* shadowed-node coverage). One recursive pass reads, validates, and
|
||||
* shadowed-node coverage). One iterative pass reads, validates, and
|
||||
* copies each nested value once, so a stateful getter cannot supply one value
|
||||
* to validation and another to storage. The event log is the durable source
|
||||
* of truth, so a bad event fails at the append site rather than later during
|
||||
@@ -660,7 +671,7 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH
|
||||
* @param request - path after best-effort Session workspace resolution.
|
||||
* @param signal - caller lifetime; abort terminates the native command.
|
||||
* @returns confirmation after the native opener accepts the path.
|
||||
* @throws TypertRemoteFailure when the request is invalid, cancelled, or the opener fails.
|
||||
* @throws RemoteError when the request is invalid, cancelled, or the opener fails.
|
||||
*/
|
||||
@Remote('openWorkspacePath') async openWorkspacePath( request: SessionOpenWorkspacePathRequest, signal: AbortSignal, ): Promise<SessionOpenWorkspacePathValue>
|
||||
|
||||
|
||||
@@ -201,6 +201,17 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
/** Unix epoch milliseconds. */
|
||||
time: number
|
||||
data: SessionEventMap[K]
|
||||
/**
|
||||
* Marks an event a reader may safely skip when it does not recognize
|
||||
* `type`. Absent means required: a reader meeting an unrecognized type
|
||||
* without this marker MUST refuse to reconstruct the session instead of
|
||||
* silently dropping the event, because an unrecognized required event may
|
||||
* change how the rest of the log is interpreted. A writer sets `true` only
|
||||
* on purely informational records whose loss cannot affect reconstruction;
|
||||
* defaulting to required means a forgotten marker over-refuses (an
|
||||
* inconvenience) rather than silently resuming a gutted session.
|
||||
*/
|
||||
ignorable?: true
|
||||
} & (K extends SurfaceEventType ? {
|
||||
/**
|
||||
* Seq numbers of earlier events that this event cites as sources
|
||||
@@ -436,7 +447,7 @@ declare class Session {
|
||||
* Map/Set/Date/class instance), or when the candidate violates the
|
||||
* canonical surface contract (marker shape and eligibility, unique
|
||||
* earlier source-event references, positional replacement validity, and complete
|
||||
* shadowed-node coverage). One recursive pass reads, validates, and
|
||||
* shadowed-node coverage). One iterative pass reads, validates, and
|
||||
* copies each nested value once, so a stateful getter cannot supply one value
|
||||
* to validation and another to storage. The event log is the durable source
|
||||
* of truth, so a bad event fails at the append site rather than later during
|
||||
@@ -664,7 +675,7 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH
|
||||
* @param request - path after best-effort Session workspace resolution.
|
||||
* @param signal - caller lifetime; abort terminates the native command.
|
||||
* @returns confirmation after the native opener accepts the path.
|
||||
* @throws TypertRemoteFailure when the request is invalid, cancelled, or the opener fails.
|
||||
* @throws RemoteError when the request is invalid, cancelled, or the opener fails.
|
||||
*/
|
||||
@Remote('openWorkspacePath') async openWorkspacePath( request: SessionOpenWorkspacePathRequest, signal: AbortSignal, ): Promise<SessionOpenWorkspacePathValue>
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/settings.md
|
||||
settings.md: 3215de191b4ef8fecb373d280c8bc8e4a89bbc7e
|
||||
settings.zh.md: 0c28ef381ee6ea8e59da64717575fbf80c8a2e5f
|
||||
settings.md: d8e3cbc46eb697315d4938b696e921a0c2e11828
|
||||
settings.zh.md: 772fd7832ff80cab9444c16c9a1dc7ae1875d51e
|
||||
+30
-12
@@ -197,8 +197,22 @@ prepareDocument(): Promise<string | undefined>
|
||||
* @param schema - schemastery schema resolving this namespace's value.
|
||||
* @param options - composition `base` layer and effect timing.
|
||||
* @returns the owner scope for reads, observation, and updates.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
|
||||
register<const Namespace extends string, T>( ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, options?: SettingsRegisterOptions<T>, ): SettingsScope<T>
|
||||
|
||||
/**
|
||||
* Attach one optional-settings consumer to this provider. The consumer
|
||||
* registers its composition entry as the base layer while this provider is
|
||||
* present, then falls back to that entry if the provider detaches.
|
||||
* @param owner - consumer context whose unload suppresses fallback work.
|
||||
* @param ns - consumer-owned settings namespace.
|
||||
* @param schema - schema resolving the namespace.
|
||||
* @param entry - composition entry used as the base and fallback value.
|
||||
* @param hooks - source sink, change notification, and optional validation.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
installSection<const Namespace extends string, T>( owner: Context, ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>, ): void
|
||||
|
||||
/**
|
||||
* Describe every registered namespace for configuration surfaces, including
|
||||
@@ -213,8 +227,9 @@ describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
|
||||
* Read one registered namespace's resolved value.
|
||||
* @param ns - the namespace to read.
|
||||
* @returns the resolved value, or `undefined` while unregistered.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
get(ns: SettingsNamespace): unknown
|
||||
get<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>): unknown
|
||||
|
||||
/**
|
||||
* Merge a patch into one registered namespace's user layer, validate the
|
||||
@@ -226,8 +241,9 @@ get(ns: SettingsNamespace): unknown
|
||||
* @param patch - plain-object patch over the user section.
|
||||
* @param expectedRevision - the descriptor `revision` the caller read; a
|
||||
* namespace that moved past it rejects with {@link SettingsConflictError}.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
|
||||
async update<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, patch: object, expectedRevision?: number, ): Promise<void>
|
||||
|
||||
/**
|
||||
* Replace one registered namespace's user section wholesale, validate,
|
||||
@@ -238,8 +254,9 @@ async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): P
|
||||
* @param section - the complete next user section.
|
||||
* @param expectedRevision - the descriptor `revision` the caller read; a
|
||||
* namespace that moved past it rejects with {@link SettingsConflictError}.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
|
||||
async replace<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, section: object, expectedRevision?: number, ): Promise<void>
|
||||
|
||||
/**
|
||||
* Apply path-addressed edits to one registered namespace's user section,
|
||||
@@ -252,8 +269,9 @@ async replace(ns: SettingsNamespace, section: object, expectedRevision?: number)
|
||||
* @param ops - ordered path edits; later ops observe earlier ones.
|
||||
* @param expectedRevision - the descriptor `revision` the caller read; a
|
||||
* namespace that moved past it rejects with {@link SettingsConflictError}.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
|
||||
async mutate<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, ops: readonly SettingsPathOp[], expectedRevision?: number, ): Promise<void>
|
||||
```
|
||||
|
||||
Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
|
||||
@@ -262,14 +280,14 @@ Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/sett
|
||||
|
||||
### `ctx.settingsController` — `SettingsController`
|
||||
|
||||
Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings-conflict` or `settings-rejected` with the service's message.
|
||||
Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings/conflict` or `settings/rejected` with the service's message.
|
||||
|
||||
```ts cordis-catalog
|
||||
/**
|
||||
* Describe every registered namespace for a configuration page: redacted
|
||||
* layered values plus the serialized schema the page renders its form from.
|
||||
* @returns provider writability, local-document presence, and one view per namespace.
|
||||
* @throws TypertRemoteFailure when no settings provider is mounted.
|
||||
* @throws RemoteError when no settings provider is mounted.
|
||||
*/
|
||||
@Remote describe(): SettingsDescribeValue
|
||||
|
||||
@@ -285,7 +303,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param patch - fields to merge into the user section.
|
||||
* @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
|
||||
* @returns the namespace's redacted view after the write.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote update( ns: string, patch: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
|
||||
|
||||
@@ -295,7 +313,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param section - complete replacement user section.
|
||||
* @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
|
||||
* @returns the namespace's redacted view after the write.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote replace( ns: string, section: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
|
||||
|
||||
@@ -307,7 +325,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param ops - the edits to apply, in order.
|
||||
* @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
|
||||
* @returns the namespace's redacted view after the write.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote async mutate( ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
|
||||
|
||||
@@ -315,7 +333,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* Materialize the provider-owned settings document and open it in a native text editor.
|
||||
* @param signal - caller lifetime; abort terminates preparation or the native command.
|
||||
* @returns confirmation after the native opener accepts the document.
|
||||
* @throws TypertRemoteFailure when no document exists, preparation fails, or opening fails.
|
||||
* @throws RemoteError when no document exists, preparation fails, or opening fails.
|
||||
*/
|
||||
@Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
|
||||
|
||||
@@ -324,7 +342,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param agentPreset - preset id resolved against Host-owned roots.
|
||||
* @param signal - caller lifetime; abort terminates the native command.
|
||||
* @returns an opened confirmation or the resolved directory for text display.
|
||||
* @throws TypertRemoteFailure when the preset is missing, read-only, invalid, or cannot be opened.
|
||||
* @throws RemoteError when the preset is missing, read-only, invalid, or cannot be opened.
|
||||
*/
|
||||
@Remote async openAgentPresetDirectory( agentPreset: string, signal: AbortSignal, ): Promise<AgentPresetDirectoryOpenValue>
|
||||
```
|
||||
|
||||
@@ -197,8 +197,22 @@ prepareDocument(): Promise<string | undefined>
|
||||
* @param schema - schemastery schema resolving this namespace's value.
|
||||
* @param options - composition `base` layer and effect timing.
|
||||
* @returns the owner scope for reads, observation, and updates.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>
|
||||
register<const Namespace extends string, T>( ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, options?: SettingsRegisterOptions<T>, ): SettingsScope<T>
|
||||
|
||||
/**
|
||||
* Attach one optional-settings consumer to this provider. The consumer
|
||||
* registers its composition entry as the base layer while this provider is
|
||||
* present, then falls back to that entry if the provider detaches.
|
||||
* @param owner - consumer context whose unload suppresses fallback work.
|
||||
* @param ns - consumer-owned settings namespace.
|
||||
* @param schema - schema resolving the namespace.
|
||||
* @param entry - composition entry used as the base and fallback value.
|
||||
* @param hooks - source sink, change notification, and optional validation.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
installSection<const Namespace extends string, T>( owner: Context, ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>, ): void
|
||||
|
||||
/**
|
||||
* Describe every registered namespace for configuration surfaces, including
|
||||
@@ -213,8 +227,9 @@ describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
|
||||
* Read one registered namespace's resolved value.
|
||||
* @param ns - the namespace to read.
|
||||
* @returns the resolved value, or `undefined` while unregistered.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
get(ns: SettingsNamespace): unknown
|
||||
get<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>): unknown
|
||||
|
||||
/**
|
||||
* Merge a patch into one registered namespace's user layer, validate the
|
||||
@@ -226,8 +241,9 @@ get(ns: SettingsNamespace): unknown
|
||||
* @param patch - plain-object patch over the user section.
|
||||
* @param expectedRevision - the descriptor `revision` the caller read; a
|
||||
* namespace that moved past it rejects with {@link SettingsConflictError}.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>
|
||||
async update<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, patch: object, expectedRevision?: number, ): Promise<void>
|
||||
|
||||
/**
|
||||
* Replace one registered namespace's user section wholesale, validate,
|
||||
@@ -238,8 +254,9 @@ async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): P
|
||||
* @param section - the complete next user section.
|
||||
* @param expectedRevision - the descriptor `revision` the caller read; a
|
||||
* namespace that moved past it rejects with {@link SettingsConflictError}.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>
|
||||
async replace<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, section: object, expectedRevision?: number, ): Promise<void>
|
||||
|
||||
/**
|
||||
* Apply path-addressed edits to one registered namespace's user section,
|
||||
@@ -252,8 +269,9 @@ async replace(ns: SettingsNamespace, section: object, expectedRevision?: number)
|
||||
* @param ops - ordered path edits; later ops observe earlier ones.
|
||||
* @param expectedRevision - the descriptor `revision` the caller read; a
|
||||
* namespace that moved past it rejects with {@link SettingsConflictError}.
|
||||
* @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
|
||||
*/
|
||||
async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
|
||||
async mutate<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, ops: readonly SettingsPathOp[], expectedRevision?: number, ): Promise<void>
|
||||
```
|
||||
|
||||
Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
|
||||
@@ -262,14 +280,14 @@ Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/sett
|
||||
|
||||
### `ctx.settingsController` — `SettingsController`
|
||||
|
||||
Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings-conflict` or `settings-rejected` with the service's message.
|
||||
Host service backing the generated `ctx.remote.settings` namespace. Every remote read uses `redactSecrets: true`, so a `role('secret')` field cannot ride a response. Writes expose the settings service's merge, replacement, and path-addressed operations, and classify every provider refusal as `settings/conflict` or `settings/rejected` with the service's message.
|
||||
|
||||
```ts cordis-catalog
|
||||
/**
|
||||
* Describe every registered namespace for a configuration page: redacted
|
||||
* layered values plus the serialized schema the page renders its form from.
|
||||
* @returns provider writability, local-document presence, and one view per namespace.
|
||||
* @throws TypertRemoteFailure when no settings provider is mounted.
|
||||
* @throws RemoteError when no settings provider is mounted.
|
||||
*/
|
||||
@Remote describe(): SettingsDescribeValue
|
||||
|
||||
@@ -285,7 +303,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param patch - fields to merge into the user section.
|
||||
* @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
|
||||
* @returns the namespace's redacted view after the write.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote update( ns: string, patch: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
|
||||
|
||||
@@ -295,7 +313,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param section - complete replacement user section.
|
||||
* @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
|
||||
* @returns the namespace's redacted view after the write.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote replace( ns: string, section: Record<string, JsonValue>, expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
|
||||
|
||||
@@ -307,7 +325,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param ops - the edits to apply, in order.
|
||||
* @param expectedRevision - revision the caller read; `undefined` writes unconditionally.
|
||||
* @returns the namespace's redacted view after the write.
|
||||
* @throws TypertRemoteFailure when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
* @throws RemoteError when the request is invalid, no provider is mounted, or the provider refuses the write.
|
||||
*/
|
||||
@Remote async mutate( ns: string, ops: SettingsPathOpView[], expectedRevision: number | undefined, ): Promise<SettingsNamespaceView>
|
||||
|
||||
@@ -315,7 +333,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* Materialize the provider-owned settings document and open it in a native text editor.
|
||||
* @param signal - caller lifetime; abort terminates preparation or the native command.
|
||||
* @returns confirmation after the native opener accepts the document.
|
||||
* @throws TypertRemoteFailure when no document exists, preparation fails, or opening fails.
|
||||
* @throws RemoteError when no document exists, preparation fails, or opening fails.
|
||||
*/
|
||||
@Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
|
||||
|
||||
@@ -324,7 +342,7 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
|
||||
* @param agentPreset - preset id resolved against Host-owned roots.
|
||||
* @param signal - caller lifetime; abort terminates the native command.
|
||||
* @returns an opened confirmation or the resolved directory for text display.
|
||||
* @throws TypertRemoteFailure when the preset is missing, read-only, invalid, or cannot be opened.
|
||||
* @throws RemoteError when the preset is missing, read-only, invalid, or cannot be opened.
|
||||
*/
|
||||
@Remote async openAgentPresetDirectory( agentPreset: string, signal: AbortSignal, ): Promise<AgentPresetDirectoryOpenValue>
|
||||
```
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/skills.md
|
||||
skills.md: 18eb4d3289cec5c7807feab4229096b5799d4168
|
||||
skills.zh.md: aa167373cb9736cf24d7bf20dc965e68568826be
|
||||
skills.md: 8224b91290c110d52d739cd85b3fc7d641f9a7ea
|
||||
skills.zh.md: 018bd85d74ba40717c741d6600f991f3c6d36d4c
|
||||
@@ -258,7 +258,7 @@ Host service backing `ctx.remote.skills` without activating a cold Agent.
|
||||
* @param request - Session identity whose cwd and preset select the catalog view.
|
||||
* @param signal - caller lifetime carried by the Remote transport; admitted catalog reads retain their existing completion semantics.
|
||||
* @returns user-invocable skill metadata without loading skill bodies.
|
||||
* @throws TypertRemoteFailure when the Session cannot be inspected or no registry can serve it.
|
||||
* @throws RemoteError when the Session cannot be inspected or no registry can serve it.
|
||||
*/
|
||||
@Remote async list(request: SkillListRequest, signal: AbortSignal): Promise<SkillListValue>
|
||||
```
|
||||
|
||||
@@ -258,7 +258,7 @@ Host service backing `ctx.remote.skills` without activating a cold Agent.
|
||||
* @param request - Session identity whose cwd and preset select the catalog view.
|
||||
* @param signal - caller lifetime carried by the Remote transport; admitted catalog reads retain their existing completion semantics.
|
||||
* @returns user-invocable skill metadata without loading skill bodies.
|
||||
* @throws TypertRemoteFailure when the Session cannot be inspected or no registry can serve it.
|
||||
* @throws RemoteError when the Session cannot be inspected or no registry can serve it.
|
||||
*/
|
||||
@Remote async list(request: SkillListRequest, signal: AbortSignal): Promise<SkillListValue>
|
||||
```
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/subagent.md
|
||||
subagent.md: dfadbbdee28607c929e629a20c18af6b55f4f51e
|
||||
subagent.zh.md: d4ffe30d69aff404733a6e8acbc2d1a19e2276d3
|
||||
subagent.md: 095d73f43e75add0fab68aee97a6e6c0d27dbed2
|
||||
subagent.zh.md: e3df4c982cec86cf1701bb807715a20e18978677
|
||||
+12
-10
@@ -657,9 +657,9 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<Subagen
|
||||
* @param parentSessionId - parent session whose direct children are listed.
|
||||
* @param signal - carrier cancellation forwarded to Session queries.
|
||||
* @returns the catalog view for that parent.
|
||||
* @throws {TypertRemoteFailure} `bad-request` for an empty parent id,
|
||||
* `cancelled` for an aborted read, `subagent-projections-unavailable` when
|
||||
* the deployment has no projection registry, otherwise `internal`.
|
||||
* @throws {RemoteError} `gateway/bad-request` for an empty parent id,
|
||||
* `gateway/cancelled` for an aborted read, `subagent/projections-unavailable` when
|
||||
* the deployment has no projection registry, otherwise `gateway/internal`.
|
||||
*/
|
||||
@Remote('list') async remoteExportList(parentSessionId: SessionId, signal: AbortSignal): Promise<SubagentCatalog>
|
||||
|
||||
@@ -669,13 +669,15 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<Subagen
|
||||
* validated browser zone on the accepted message. Success identifies the
|
||||
* message the child's FIFO inbox accepted; later execution is independent of
|
||||
* this call.
|
||||
* Image parts are admitted and persisted through the attachment store
|
||||
* before delivery, and the child's model must accept image input.
|
||||
* @param request - durable address, minted identity, content, and optional browser zone.
|
||||
* @param signal - carrier cancellation, owning the call until inbox acceptance.
|
||||
* @returns the accepted message's inbox identity.
|
||||
* @throws {TypertRemoteFailure} `bad-request`, `invalid-time-zone`,
|
||||
* `subagent-parent-unavailable`, `subagent-not-resumable`,
|
||||
* `subagent-unauthorized`, `subagent-delivery-unavailable`, `cancelled`, or
|
||||
* `internal`.
|
||||
* @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
|
||||
* `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
|
||||
* `subagent/not-resumable`, `subagent/unauthorized`,
|
||||
* `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
|
||||
*/
|
||||
@Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>
|
||||
|
||||
@@ -689,9 +691,9 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<Subagen
|
||||
* @param parentSessionId - durable direct parent whose authority is claimed.
|
||||
* @param mode - required continuable-address discriminator.
|
||||
* @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
|
||||
* @throws {TypertRemoteFailure} `bad-request` for an empty id,
|
||||
* `subagent-unauthorized` when the address does not own the live target,
|
||||
* otherwise `internal`.
|
||||
* @throws {RemoteError} `gateway/bad-request` for an empty id,
|
||||
* `subagent/unauthorized` when the address does not own the live target,
|
||||
* otherwise `gateway/internal`.
|
||||
*/
|
||||
@Remote('interruptByParent') interruptByParent( childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable', ): SubagentInterruptReceipt
|
||||
|
||||
|
||||
@@ -661,9 +661,9 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<Subagen
|
||||
* @param parentSessionId - parent session whose direct children are listed.
|
||||
* @param signal - carrier cancellation forwarded to Session queries.
|
||||
* @returns the catalog view for that parent.
|
||||
* @throws {TypertRemoteFailure} `bad-request` for an empty parent id,
|
||||
* `cancelled` for an aborted read, `subagent-projections-unavailable` when
|
||||
* the deployment has no projection registry, otherwise `internal`.
|
||||
* @throws {RemoteError} `gateway/bad-request` for an empty parent id,
|
||||
* `gateway/cancelled` for an aborted read, `subagent/projections-unavailable` when
|
||||
* the deployment has no projection registry, otherwise `gateway/internal`.
|
||||
*/
|
||||
@Remote('list') async remoteExportList(parentSessionId: SessionId, signal: AbortSignal): Promise<SubagentCatalog>
|
||||
|
||||
@@ -673,13 +673,15 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<Subagen
|
||||
* validated browser zone on the accepted message. Success identifies the
|
||||
* message the child's FIFO inbox accepted; later execution is independent of
|
||||
* this call.
|
||||
* Image parts are admitted and persisted through the attachment store
|
||||
* before delivery, and the child's model must accept image input.
|
||||
* @param request - durable address, minted identity, content, and optional browser zone.
|
||||
* @param signal - carrier cancellation, owning the call until inbox acceptance.
|
||||
* @returns the accepted message's inbox identity.
|
||||
* @throws {TypertRemoteFailure} `bad-request`, `invalid-time-zone`,
|
||||
* `subagent-parent-unavailable`, `subagent-not-resumable`,
|
||||
* `subagent-unauthorized`, `subagent-delivery-unavailable`, `cancelled`, or
|
||||
* `internal`.
|
||||
* @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
|
||||
* `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
|
||||
* `subagent/not-resumable`, `subagent/unauthorized`,
|
||||
* `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
|
||||
*/
|
||||
@Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>
|
||||
|
||||
@@ -693,9 +695,9 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<Subagen
|
||||
* @param parentSessionId - durable direct parent whose authority is claimed.
|
||||
* @param mode - required continuable-address discriminator.
|
||||
* @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
|
||||
* @throws {TypertRemoteFailure} `bad-request` for an empty id,
|
||||
* `subagent-unauthorized` when the address does not own the live target,
|
||||
* otherwise `internal`.
|
||||
* @throws {RemoteError} `gateway/bad-request` for an empty id,
|
||||
* `subagent/unauthorized` when the address does not own the live target,
|
||||
* otherwise `gateway/internal`.
|
||||
*/
|
||||
@Remote('interruptByParent') interruptByParent( childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable', ): SubagentInterruptReceipt
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
|
||||
system-prompt.md: 68eab4f5c93f14675d548c0fa635c5f3f3ce70a7
|
||||
system-prompt.zh.md: 086555593e507da03aea3e83a55017e0aa839fcb
|
||||
system-prompt.md: 502daab50a908bfbf5dcae480771c0baa0827849
|
||||
system-prompt.zh.md: 95e33eb6bbea7d271c4f70948388fe2deef420a9
|
||||
@@ -39,7 +39,7 @@ interface ToolProviderResult {
|
||||
|
||||
## Prompt sections
|
||||
|
||||
`PromptSection` is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context. Sections sort by ascending order and then code-unit name; `FIRST_PARTY_SECTION_ORDER` publishes the sparse named allocation for repository-owned contributions. One effective `complete` section becomes the sole prompt section after cooperative assembly.
|
||||
`PromptSection` is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context. Sections sort by ascending order and then code-unit name; repository contributors resolve the service-owned named allocation through `getSectionOrder()`. Runtime-context contributors resolve their independent allocation through `getContextOrder()`. One effective `complete` section becomes the sole prompt section after cooperative assembly.
|
||||
|
||||
```ts type-equiv
|
||||
/** One contributed section of the system prompt (registry input). */
|
||||
@@ -48,8 +48,7 @@ interface PromptSection {
|
||||
readonly name: string
|
||||
/**
|
||||
* Sections are concatenated in ascending order. Equal orders use code-unit
|
||||
* name order. Repository-owned placements use
|
||||
* {@link FIRST_PARTY_SECTION_ORDER}.
|
||||
* name order.
|
||||
*/
|
||||
readonly order: number
|
||||
/**
|
||||
@@ -109,6 +108,20 @@ Registry service for the prompt inputs assembled before each model step.
|
||||
*/
|
||||
section(section: PromptSection): () => void
|
||||
|
||||
/**
|
||||
* Resolve the centrally owned placement of a repository prompt section.
|
||||
* @param name - stable section placement name.
|
||||
* @returns the section's numeric sort order.
|
||||
*/
|
||||
getSectionOrder(name: PromptSectionOrderName): number
|
||||
|
||||
/**
|
||||
* Resolve the centrally owned placement of a repository runtime context.
|
||||
* @param name - stable context placement name.
|
||||
* @returns the context's numeric sort order.
|
||||
*/
|
||||
getContextOrder(name: PromptContextOrderName): number
|
||||
|
||||
/**
|
||||
* Register ordered dynamic context in the calling context's scope. Scoped
|
||||
* entries shadow global entries with the same name.
|
||||
|
||||
@@ -39,7 +39,7 @@ interface ToolProviderResult {
|
||||
|
||||
## 提示词段落
|
||||
|
||||
`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的,也可以从当前组装上下文动态解析。各段先按 order 升序排列,再按名称的代码单元顺序排列;`FIRST_PARTY_SECTION_ORDER` 公开仓库自带贡献的稀疏具名分配表。协作式组装完成后,一个有效的 `complete` 段会成为唯一的提示词段落。
|
||||
`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的,也可以从当前组装上下文动态解析。各段先按 order 升序排列,再按名称的代码单元顺序排列;仓库贡献方通过 `getSectionOrder()` 解析服务持有的具名分配。Runtime-context 贡献方通过 `getContextOrder()` 解析独立分配。协作式组装完成后,一个有效的 `complete` 段会成为唯一的提示词段落。
|
||||
|
||||
```ts type-equiv
|
||||
/** One contributed section of the system prompt (registry input). */
|
||||
@@ -48,8 +48,7 @@ interface PromptSection {
|
||||
readonly name: string
|
||||
/**
|
||||
* Sections are concatenated in ascending order. Equal orders use code-unit
|
||||
* name order. Repository-owned placements use
|
||||
* {@link FIRST_PARTY_SECTION_ORDER}.
|
||||
* name order.
|
||||
*/
|
||||
readonly order: number
|
||||
/**
|
||||
@@ -109,6 +108,20 @@ Registry service for the prompt inputs assembled before each model step.
|
||||
*/
|
||||
section(section: PromptSection): () => void
|
||||
|
||||
/**
|
||||
* Resolve the centrally owned placement of a repository prompt section.
|
||||
* @param name - stable section placement name.
|
||||
* @returns the section's numeric sort order.
|
||||
*/
|
||||
getSectionOrder(name: PromptSectionOrderName): number
|
||||
|
||||
/**
|
||||
* Resolve the centrally owned placement of a repository runtime context.
|
||||
* @param name - stable context placement name.
|
||||
* @returns the context's numeric sort order.
|
||||
*/
|
||||
getContextOrder(name: PromptContextOrderName): number
|
||||
|
||||
/**
|
||||
* Register ordered dynamic context in the calling context's scope. Scoped
|
||||
* entries shadow global entries with the same name.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/typert.md
|
||||
typert.md: 20734175cc6b853ae7eeb18e6d5fc91a97cdbe0d
|
||||
typert.zh.md: e900011f24a5a232ab8764501594b563f320e090
|
||||
typert.md: 0f3d2b1afdc1b7713402abc5885dc9551e16ac14
|
||||
typert.zh.md: a3c06489707e18433ed9018363c57ec76732e606
|
||||
+18
-18
@@ -139,7 +139,7 @@ interface TypertRemoteNamespaceMap {}
|
||||
|
||||
## Host Gateway
|
||||
|
||||
Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures use the Gateway's in-process error taxonomy, ordinary exceptions are folded by the RPC adapter into the transport's `internal` error code, and existing RPC errors carried by lookup policy through `TypertLookupFailure` are returned unchanged.
|
||||
Connection decodes its carrier envelope before calling `ctx.typertGateway`. The request carries exact named wire fields and the carrier's cancellation signal separately; infrastructure and boundary failures ride `TypertGatewayError`, whose `gateway/*` codes are ordinary `RemoteError` codes, so the RPC adapter passes every structurally identified `RemoteError` through with its code and details intact and folds only unrecognized exceptions into `gateway/internal`.
|
||||
|
||||
```ts type-equiv
|
||||
/** One Remote method request after a carrier has decoded its envelope. */
|
||||
@@ -158,23 +158,23 @@ interface InvokeRemoteRequest {
|
||||
```ts type-equiv
|
||||
/** Stable infrastructure and boundary failures emitted before or after business execution. */
|
||||
type TypertGatewayErrorCode =
|
||||
| 'ambiguous-endpoint'
|
||||
| 'arguments-invalid'
|
||||
| 'binding-invalid'
|
||||
| 'context-failed'
|
||||
| 'context-not-found'
|
||||
| 'context-unavailable'
|
||||
| 'definition-unavailable'
|
||||
| 'input-invalid'
|
||||
| 'invocation-unavailable'
|
||||
| 'lookup-failed'
|
||||
| 'lookup-not-found'
|
||||
| 'lookup-unavailable'
|
||||
| 'method-unavailable'
|
||||
| 'provider-mismatch'
|
||||
| 'result-invalid'
|
||||
| 'service-unavailable'
|
||||
| 'signature-invalid'
|
||||
| 'gateway/ambiguous-endpoint'
|
||||
| 'gateway/arguments-invalid'
|
||||
| 'gateway/binding-invalid'
|
||||
| 'gateway/context-failed'
|
||||
| 'gateway/context-not-found'
|
||||
| 'gateway/context-unavailable'
|
||||
| 'gateway/definition-unavailable'
|
||||
| 'gateway/input-invalid'
|
||||
| 'gateway/invocation-unavailable'
|
||||
| 'gateway/lookup-failed'
|
||||
| 'gateway/lookup-not-found'
|
||||
| 'gateway/lookup-unavailable'
|
||||
| 'gateway/method-unavailable'
|
||||
| 'gateway/provider-mismatch'
|
||||
| 'gateway/result-invalid'
|
||||
| 'gateway/service-unavailable'
|
||||
| 'gateway/signature-invalid'
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
|
||||
@@ -139,7 +139,7 @@ interface TypertRemoteNamespaceMap {}
|
||||
|
||||
## Host Gateway
|
||||
|
||||
Connection 会先解码 carrier envelope,再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带;基础设施与边界失败使用 Gateway 的进程内错误分类体系,普通异常由 RPC 适配器归并为传输层的 `internal` 错误码,lookup 策略通过 `TypertLookupFailure` 携带的既有 RPC error 则原样返回。
|
||||
Connection 会先解码 carrier envelope,再调用 `ctx.typertGateway`。请求将精确的具名 wire 字段与 carrier 的取消 signal 分开携带;基础设施与边界失败由 `TypertGatewayError` 承载,其 `gateway/*` 码就是普通的 `RemoteError` 码,因此 RPC 适配器会把每个经结构识别的 `RemoteError` 连同其 code 与 details 原样放行,只把无法识别的异常归并为 `gateway/internal`。
|
||||
|
||||
```ts type-equiv
|
||||
/** One Remote method request after a carrier has decoded its envelope. */
|
||||
@@ -158,23 +158,23 @@ interface InvokeRemoteRequest {
|
||||
```ts type-equiv
|
||||
/** Stable infrastructure and boundary failures emitted before or after business execution. */
|
||||
type TypertGatewayErrorCode =
|
||||
| 'ambiguous-endpoint'
|
||||
| 'arguments-invalid'
|
||||
| 'binding-invalid'
|
||||
| 'context-failed'
|
||||
| 'context-not-found'
|
||||
| 'context-unavailable'
|
||||
| 'definition-unavailable'
|
||||
| 'input-invalid'
|
||||
| 'invocation-unavailable'
|
||||
| 'lookup-failed'
|
||||
| 'lookup-not-found'
|
||||
| 'lookup-unavailable'
|
||||
| 'method-unavailable'
|
||||
| 'provider-mismatch'
|
||||
| 'result-invalid'
|
||||
| 'service-unavailable'
|
||||
| 'signature-invalid'
|
||||
| 'gateway/ambiguous-endpoint'
|
||||
| 'gateway/arguments-invalid'
|
||||
| 'gateway/binding-invalid'
|
||||
| 'gateway/context-failed'
|
||||
| 'gateway/context-not-found'
|
||||
| 'gateway/context-unavailable'
|
||||
| 'gateway/definition-unavailable'
|
||||
| 'gateway/input-invalid'
|
||||
| 'gateway/invocation-unavailable'
|
||||
| 'gateway/lookup-failed'
|
||||
| 'gateway/lookup-not-found'
|
||||
| 'gateway/lookup-unavailable'
|
||||
| 'gateway/method-unavailable'
|
||||
| 'gateway/provider-mismatch'
|
||||
| 'gateway/result-invalid'
|
||||
| 'gateway/service-unavailable'
|
||||
| 'gateway/signature-invalid'
|
||||
```
|
||||
|
||||
```ts type-equiv
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/testing.md
|
||||
testing.md: c21c67bba85387e35e80d16217c2673653281672
|
||||
testing.zh.md: 008bee58918510c8afb695a7e0b880828d698227
|
||||
testing.md: 25514702e7aa8649c10ec213f5a6bf5c6e9e9a09
|
||||
testing.zh.md: 5338e4bc392e1e1ff16c32f708970be917e6efa7
|
||||
@@ -15,6 +15,10 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
|
||||
|
||||
Session fixtures keep headers and payloads but omit body sequence/time envelopes. Replay synthesizes them. Fixtures use canonical packed rows; [the migrator](../scripts/migrate-packed-session-fixtures.ts) rewrites old layouts.
|
||||
|
||||
## How specs execute
|
||||
|
||||
Forked workers run several spec files at once, the coverage gate splits into concurrent partitions beside the other gates in its job, and the self-hosted runners share one host and one volume. Only the process is isolated: ports, predictable paths, external namespaces, and inherited children are not. Own each acquired resource through its teardown, and read a spec that passes only when it runs alone as a defect in the spec rather than an unstable runner. [dsh-ci-test-reliability](../.agents/skills/dsh-ci-test-reliability/SKILL.md) owns the allocation, restoration, synchronization, timeout-budget, platform, and teardown rules; its [flake diagnosis workflow](../.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md) classifies an existing probabilistic failure.
|
||||
|
||||
## The with-key policy: inference is cheap here
|
||||
|
||||
We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Cover file-writing prompts, multi-turn conversations, tool use, and mid-stream cancellation. Highest-value are **smoke tests** that boot a shipped `dsh` profile, send one prompt, and check the world — they catch the "green unit tests, broken product" class that mocks cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). Self-skip keeps secretless CI and keyless contributors unblocked; it is not a cost signal. Profile-level integration tests live under `apps/cli/tests/profiles/`; package-specific compositions stay with their package tests.
|
||||
|
||||
@@ -15,6 +15,10 @@
|
||||
|
||||
会话 fixture 保留 header 与 payload,但省略正文序号/时间 envelope。回放会合成这些字段;运行时持久化不变。fixture 使用规范打包行;[迁移器](../scripts/migrate-packed-session-fixtures.ts)会改写旧布局。
|
||||
|
||||
## spec 如何被执行
|
||||
|
||||
fork 出的 worker 会同时运行多个 spec 文件,coverage gate 会拆成并发的 partition,与同一个 job 中的其它 gate 并排运行,而自托管 runner 共用同一台宿主机和同一个卷。被隔离的只有进程:端口、可预测路径、外部命名空间和继承而来的子进程都不隔离。为每个占用的资源负责到它的 teardown,并把「只有单独运行时才通过」的 spec 读作该 spec 的缺陷,而不是 runner 不稳定。[dsh-ci-test-reliability](../.agents/skills/dsh-ci-test-reliability/SKILL.md) 负责资源分配、状态恢复、同步、超时预算、平台差异与 teardown 规则;它的 [flake 诊断流程](../.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md)用于归类已经存在的概率性失败。
|
||||
|
||||
## 带密钥策略:推理(inference)在这里很便宜
|
||||
|
||||
我们是 DeepSeek,不要吝惜真实 API 测试。无密钥测试只能证明底层通路;只有带密钥运行才能证明 agent(智能体)能对接真实模型正常工作。覆盖文件写入提示词、包含多个轮次的对话、工具使用和流中取消。价值最高的是**冒烟测试**:启动已交付的 `dsh` profile、发送一条提示词,并检查外部世界;它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题([事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.zh.md))。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞;它不是成本信号。Profile 级集成测试位于 `apps/cli/tests/profiles/`;包专属组合留在对应包的测试目录中。
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/user/develop/practice/llm-adapter.md
|
||||
llm-adapter.md: ff5fc5657e2be0a5fe0d4e10f148865e62f92b18
|
||||
llm-adapter.zh.md: b05bfad6cbc4038f54f816b212068d85e54c2100
|
||||
llm-adapter.md: 7e30847cdf265bca8f55aac40f73686101ec185d
|
||||
llm-adapter.zh.md: 22a3c54f45088a41362c1a8e903d2441ed4fc93b
|
||||
@@ -54,7 +54,8 @@ export function apply(ctx: Context, config: Config) {
|
||||
`stream()` yields chunks using this protocol:
|
||||
|
||||
```ts
|
||||
import { ToolCallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
|
||||
import { brandString } from '@deepseek-ai/dsh-brand'
|
||||
import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
|
||||
|
||||
async function* exampleChunks(): AsyncIterable<StreamChunk> {
|
||||
// 1. Start each content block with block-start.
|
||||
@@ -76,7 +77,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
|
||||
yield {
|
||||
type: 'tool-call-delta',
|
||||
index: 1,
|
||||
id: ToolCallId('call-123'),
|
||||
id: brandString<ToolCallId>('call-123'),
|
||||
name: 'bash',
|
||||
argumentsDelta: '{"command":"ls"}',
|
||||
}
|
||||
@@ -85,7 +86,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
|
||||
index: 1,
|
||||
block: {
|
||||
type: 'tool-call',
|
||||
id: ToolCallId('call-123'),
|
||||
id: brandString<ToolCallId>('call-123'),
|
||||
name: 'bash',
|
||||
arguments: '{"command":"ls"}',
|
||||
},
|
||||
|
||||
@@ -54,7 +54,8 @@ export function apply(ctx: Context, config: Config) {
|
||||
`stream()` 必须按以下协议生成分片:
|
||||
|
||||
```ts
|
||||
import { ToolCallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
|
||||
import { brandString } from '@deepseek-ai/dsh-brand'
|
||||
import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
|
||||
|
||||
async function* exampleChunks(): AsyncIterable<StreamChunk> {
|
||||
// 1. Start each content block with block-start.
|
||||
@@ -76,7 +77,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
|
||||
yield {
|
||||
type: 'tool-call-delta',
|
||||
index: 1,
|
||||
id: ToolCallId('call-123'),
|
||||
id: brandString<ToolCallId>('call-123'),
|
||||
name: 'bash',
|
||||
argumentsDelta: '{"command":"ls"}',
|
||||
}
|
||||
@@ -85,7 +86,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
|
||||
index: 1,
|
||||
block: {
|
||||
type: 'tool-call',
|
||||
id: ToolCallId('call-123'),
|
||||
id: brandString<ToolCallId>('call-123'),
|
||||
name: 'bash',
|
||||
arguments: '{"command":"ls"}',
|
||||
},
|
||||
|
||||
Reference in new issue
Block a user