mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
docs: mark owned-run boundary decision implemented
This commit is contained in:
_Kerman
@@ -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 .agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
|
||||
2026-07-30-followup-enqueue-and-owned-runs.md: 12da1d770c9346e79394c194f33e7faae2254cdf
|
||||
2026-07-30-followup-enqueue-and-owned-runs.zh.md: c7b839d1207151002a0cff1a470245198561b2d8
|
||||
@@ -0,0 +1,42 @@
|
||||
# Agent Note: Follow-up enqueue and owned run boundaries
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
`Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input.
|
||||
|
||||
The [one-send-one-turn decision](../simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers that pair one prompt request with a turn result manufacture that missing relationship downstream. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome.
|
||||
|
||||
## Decision
|
||||
|
||||
Keep `Agent.followup(message): void` as an enqueue-only operation. `Agent.whenIdle()` and `agent/status` remain whole-agent lifecycle observations; neither settles an individual message. Inbox durability records the identified message and its admission or cancellation, without assigning later output to it.
|
||||
|
||||
The low-level SDK protocol answers `session/prompt` as soon as enqueue succeeds with `{ messageId }`. It streams durable facts through `session.event`, publishes whole-agent transitions through `session.status`, and has no `session.finished`. A low-level client may observe that receipt and later idleness, but receives no prompt result.
|
||||
|
||||
High-level automation APIs return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their `finalResponse` is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may report a result because its caller owns the complete child lifecycle and any steering belongs to that run.
|
||||
|
||||
ACP must return a protocol `stopReason`. Its bridge serializes one in-flight prompt per ACP session, waits for whole-agent idle, reports `cancelled` only for explicit ACP cancellation or disposal, and otherwise reports the generic `end_turn`. It does not infer token-limit or error attribution for the prompt.
|
||||
|
||||
Goal continuation retains `MessageId` only to recognize its durable queued and admitted goal message. It advances from durable goal state at whole-agent idle, without mapping the message to a turn result.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Map `MessageId` to the turn that admits it.** A turn may consume steering and injected context and may continue through multiple model/tool steps. The mapping identifies admission, not causal ownership of the resulting output or stop reason.
|
||||
|
||||
**Return a per-follow-up completion handle.** A handle would imply a result boundary that the shared agent lifecycle does not have. It would either omit work that influenced the activity or silently absorb unrelated later input.
|
||||
|
||||
**Use the last `turn/end` observed before idle.** This is a useful run-level observation for an explicitly owned interval, but naming it as the submitted message's outcome recreates the false causal claim.
|
||||
|
||||
## Verification
|
||||
|
||||
- Agent and inbox tests pin enqueue-only follow-up, durable admission or cancellation, and whole-agent idle observation.
|
||||
- SDK protocol, TypeScript SDK, and Python SDK tests pin the `{ messageId }` receipt, `session.status`, the absence of `session.finished`, and receipt-to-idle `RunResult` collection without prompt-level `status` or `reason`.
|
||||
- ACP, one-shot CLI, goal continuation, and subagent tests pin the distinct activity ownership each integration possesses.
|
||||
- Consumer tests pin that no production integration derives a follow-up result by correlating `MessageId` with `turn/end`.
|
||||
|
||||
## Consequences
|
||||
|
||||
An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications disappear from SDK and ACP results; callers that need those facts must inspect the durable event stream without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Agent Note: follow-up 入队与自有运行边界
|
||||
|
||||
Status: proposed
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-30-followup-enqueue-and-owned-runs.md) | 中文
|
||||
|
||||
@@ -8,19 +8,19 @@ Status: proposed
|
||||
|
||||
`Agent.followup()` 会标识一条用户消息并将其排入队列，但单次 follow-up 并不拥有随后发生的活动。在 agent（智能体）下一次进入 idle 前，steering（中途引导）、注入的上下文、工具续行、恢复和后续排队消息都可能参与活动。因此，`MessageId` 可以证明 inbox 已准入，但不能标识哪一条 assistant 消息或哪一个 `turn/end` 是该输入的结果。
|
||||
|
||||
[one-send-one-turn 决策](../../implemented/simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。协议层和 SDK 层仍会在下游配对一项提示词请求与一个轮次结果，人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。
|
||||
[one-send-one-turn 决策](../simplification/2026-07-17-one-send-one-turn.md) 已经在核心 seam 中排除了按 send 返回完成句柄的设计。凡是把一项提示词请求与一个轮次结果配对的协议层和 SDK 层，都会在下游人为构造这一缺失的关系。一旦活动准入更多输入，该配对就会产生歧义，还会把轮次机制暴露为提示词级结果。
|
||||
|
||||
## 提案
|
||||
## 决策
|
||||
|
||||
保留 `Agent.followup(message): void`，使其仅执行入队。`Agent.whenIdle()` 和 `agent/status` 仍用于观察整个 agent 的生命周期；二者都不结算单条消息。Inbox 持久性会记录已标识消息及其准入或取消，但不会把后续输出归属于该消息。
|
||||
|
||||
底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，并删除 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
|
||||
底层 SDK 协议在入队成功后立即以 `{ messageId }` 响应 `session/prompt`。它通过 `session.event` 传输持久事实，通过 `session.status` 发布整个 agent 的状态转换，且不包含 `session.finished`。底层客户端可以观察该回执和之后的 idle，但不会收到提示词结果。
|
||||
|
||||
只有明确拥有一个活动区间时，高层自动化 API 才可以返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法会从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行仍可报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
|
||||
只有明确拥有一个活动区间时，高层自动化 API 才返回 `RunResult`。TypeScript 和 Python SDK 的 `run()` 方法从已提交消息的持久 inbox 回执开始收集，直至整个 agent 下一次进入 `idle`；其 `finalResponse` 是该区间内最后一条已提交的 assistant 消息，而不是按因果关系归属于已提交提示词的响应。单次 CLI（命令行界面）拥有相应的 idle 到 idle 区间。隔离的子 agent 运行可以报告结果，因为调用方拥有完整的子级生命周期，任何 steering 都属于该运行。
|
||||
|
||||
ACP（Agent Client Protocol）仍必须返回协议规定的 `stopReason`。其桥接层会串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，仅在显式 ACP 取消或资源释放时报告 `cancelled`，其他情况均报告通用的 `end_turn`。它不会推断 token 上限或错误是否归属于该提示词。
|
||||
ACP（Agent Client Protocol）必须返回协议规定的 `stopReason`。其桥接层串行处理每个 ACP 会话中唯一一个正在处理的提示词，等待整个 agent 进入 idle，仅在显式 ACP 取消或资源释放时报告 `cancelled`，其他情况均报告通用的 `end_turn`。它不推断 token 上限或错误是否归属于该提示词。
|
||||
|
||||
Goal 续行只会保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它会在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。
|
||||
Goal 续行只保留 `MessageId`，用于识别持久排队和已准入的 goal 消息。它在整个 agent 进入 idle 时根据持久 goal 状态推进，不把消息映射到轮次结果。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
@@ -30,14 +30,13 @@ Goal 续行只会保留 `MessageId`，用于识别持久排队和已准入的 go
|
||||
|
||||
**使用进入 idle 前观察到的最后一个 `turn/end`。** 对于明确拥有的区间，这是一项有用的运行级观测；但如果将其命名为已提交消息的结果，就会再次作出错误的因果声明。
|
||||
|
||||
## 验收标准
|
||||
## 验证
|
||||
|
||||
- `Agent.followup()` 仍仅执行入队，其文档不承诺单条消息的完成状态或结果。
|
||||
- SDK 协议格式（wire format）由 `session/prompt` 返回 `MessageId`、发布 `session.status`，且不包含 `session.finished`。
|
||||
- TypeScript 和 Python 高层 SDK 公开不带提示词级 `status` 或 `reason` 的 `RunResult`，并定义从回执到 idle 的收集窗口。
|
||||
- ACP、单次 CLI、goal 续行和 subagent 提供方分别记录自己实际拥有的活动边界。
|
||||
- 生产消费方都不会通过关联 `MessageId` 与 `turn/end` 来推导 follow-up 结果。
|
||||
- Agent 与 inbox 测试固定 follow-up 仅入队、持久准入或取消以及整个 agent 的 idle 观测。
|
||||
- SDK 协议、TypeScript SDK 和 Python SDK 测试固定 `{ messageId }` 回执、`session.status`、不存在 `session.finished`，以及不含提示词级 `status` 或 `reason` 的回执到 idle `RunResult` 收集。
|
||||
- ACP、单次 CLI、goal 续行和 subagent 测试固定各集成实际拥有的不同活动边界。
|
||||
- 消费方测试固定生产集成都不会通过关联 `MessageId` 与 `turn/end` 来推导 follow-up 结果。
|
||||
|
||||
## 风险
|
||||
## 后果
|
||||
|
||||
自有活动区间可以包含进入 idle 前提交的 steering、注入上下文或其他工作，因此其最终响应和事件有意比初始消息涵盖更广。SDK 和 ACP 结果不再包含提示词级模型错误和 token 上限分类；需要这些事实的调用方必须检查持久事件流，但不能声称这些事实具有因果归属。在同一会话上并发执行自动化操作时，必须采用显式串行或所有权策略，不能依赖隐式的按提示词结果。
|
||||
@@ -1,6 +0,0 @@
|
||||
# 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 .agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md
|
||||
2026-07-30-followup-enqueue-and-owned-runs.md: 73dfb501cb5c18a7a9219861eba37e73499af5e0
|
||||
2026-07-30-followup-enqueue-and-owned-runs.zh.md: 03a321c761eda385acb665d26a33ef618c70dee5
|
||||
@@ -1,43 +0,0 @@
|
||||
# Agent Note: Follow-up enqueue and owned run boundaries
|
||||
|
||||
Status: proposed
|
||||
|
||||
English | [中文](2026-07-30-followup-enqueue-and-owned-runs.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
`Agent.followup()` identifies and queues a user message, but one follow-up does not own the activity that follows it. Steering, injected context, tool continuations, recovery, and later queued messages can all contribute before the agent next becomes idle. A `MessageId` can therefore prove inbox admission, but it cannot identify which assistant message or `turn/end` is the result of that input.
|
||||
|
||||
The [one-send-one-turn decision](../../implemented/simplification/2026-07-17-one-send-one-turn.md) already rejects a per-send completion handle at the core seam. Protocol and SDK layers currently manufacture that missing relationship downstream by pairing one prompt request with a turn result. The pairing becomes ambiguous as soon as activity admits more input, and it exposes turn mechanics as if they were a prompt-level outcome.
|
||||
|
||||
## Proposal
|
||||
|
||||
Keep `Agent.followup(message): void` as an enqueue-only operation. `Agent.whenIdle()` and `agent/status` remain whole-agent lifecycle observations; neither settles an individual message. Inbox durability records the identified message and its admission or cancellation, without assigning later output to it.
|
||||
|
||||
The low-level SDK protocol will answer `session/prompt` as soon as enqueue succeeds with `{ messageId }`. It will stream durable facts through `session.event`, publish whole-agent transitions through `session.status`, and remove `session.finished`. A low-level client may observe that receipt and later idleness, but receives no prompt result.
|
||||
|
||||
High-level automation APIs may return a `RunResult` only when they explicitly own an activity interval. The TypeScript and Python SDK `run()` methods will collect from the submitted message's durable inbox receipt through the next whole-agent `idle`; their `finalResponse` is the last committed assistant message in that interval, not a response causally attributed to the submitted prompt. The one-shot CLI owns the analogous idle-to-idle interval. An isolated child-agent run may still report a result because its caller owns the complete child lifecycle and any steering belongs to that run.
|
||||
|
||||
ACP must still return a protocol `stopReason`. Its bridge will serialize one in-flight prompt per ACP session, wait for whole-agent idle, report `cancelled` only for explicit ACP cancellation or disposal, and otherwise report the generic `end_turn`. It will not infer token-limit or error attribution for the prompt.
|
||||
|
||||
Goal continuation will retain `MessageId` only to recognize its durable queued and admitted goal message. It will advance from durable goal state at whole-agent idle, without mapping the message to a turn result.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Map `MessageId` to the turn that admits it.** A turn may consume steering and injected context and may continue through multiple model/tool steps. The mapping identifies admission, not causal ownership of the resulting output or stop reason.
|
||||
|
||||
**Return a per-follow-up completion handle.** A handle would imply a result boundary that the shared agent lifecycle does not have. It would either omit work that influenced the activity or silently absorb unrelated later input.
|
||||
|
||||
**Use the last `turn/end` observed before idle.** This is a useful run-level observation for an explicitly owned interval, but naming it as the submitted message's outcome recreates the false causal claim.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- `Agent.followup()` remains enqueue-only, and its documentation promises no per-message completion or result.
|
||||
- The SDK wire protocol returns `MessageId` from `session/prompt`, publishes `session.status`, and has no `session.finished`.
|
||||
- TypeScript and Python high-level SDKs expose `RunResult` without prompt-level `status` or `reason`, and define the receipt-to-idle collection window.
|
||||
- ACP, the one-shot CLI, goal continuation, and subagent providers document the distinct activity ownership they actually possess.
|
||||
- No production consumer derives a follow-up result by correlating `MessageId` with `turn/end`.
|
||||
|
||||
## Risks
|
||||
|
||||
An owned activity interval can include steering, injected context, or other work submitted before idleness, so its final response and events are deliberately broader than the initiating message. Prompt-level model error and token-limit classifications disappear from SDK and ACP results; callers that need those facts must inspect the durable event stream without claiming causal attribution. Concurrent automation on one session requires an explicit serialization or ownership policy rather than an implicit per-prompt result.
|
||||
@@ -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/architecture.md
|
||||
architecture.md: d8e5f8a2e8d36acb7d27ed0571645f6166eff3af
|
||||
architecture.zh.md: 96948aa5283e0114b1883335b91148ce3b720e06
|
||||
architecture.md: 7a160bd6eb26e96688699110ed15696b941825d0
|
||||
architecture.zh.md: 26b71962d312375aa8d69c8dce7abac32d541f2f
|
||||
|
||||
@@ -131,7 +131,7 @@ Turn and step events are turn-enclosed; idle injected `user/message` events may
|
||||
|
||||
### Agent Handles
|
||||
|
||||
`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. `followup()` only queues an identified message: its `MessageId` follows durable inbox admission, not a prompt-specific output or turn ending. `agent/status` and `whenIdle()` describe whole-agent activity; only a caller that explicitly owns an activity interval may summarize that interval as a run result ([proposal](../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
|
||||
`ctx.agents` returns `AgentHandle { agent, dispose() }`. Plugins drive agents with `followup()`, `steer()`, and `inject()`; `cancel()` stops work, while the awaited disposer owns teardown. `followup()` only queues an identified message: its `MessageId` follows durable inbox admission, not a prompt-specific output or turn ending. `agent/status` and `whenIdle()` describe whole-agent activity; only a caller that explicitly owns an activity interval may summarize that interval as a run result ([decision](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
|
||||
|
||||
### Agent Scope
|
||||
|
||||
|
||||
@@ -131,7 +131,7 @@ idle inject:
|
||||
|
||||
### Agent 句柄
|
||||
|
||||
`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。`followup()` 只会将一条带标识的消息排队：其 `MessageId` 跟踪持久 inbox 准入，而不标识某个提示词特有的输出或轮次结束。`agent/status` 与 `whenIdle()` 描述整个 agent 的活动；只有显式拥有某个活动区间的调用方才能将该区间概括为一次运行的结果（[提案](../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
|
||||
`ctx.agents` 返回 `AgentHandle { agent, dispose() }`。插件用 `followup()`、`steer()` 和 `inject()` 驱动 agent；`cancel()` 停止工作，而拆卸由需等待完成的 disposer 负责。`followup()` 只会将一条带标识的消息排队：其 `MessageId` 跟踪持久 inbox 准入，而不标识某个提示词特有的输出或轮次结束。`agent/status` 与 `whenIdle()` 描述整个 agent 的活动；只有显式拥有某个活动区间的调用方才能将该区间概括为一次运行的结果（[决策](../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
|
||||
|
||||
### Agent 作用域
|
||||
|
||||
|
||||
@@ -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/core-data-structures/core.md
|
||||
core.md: b7e1c11b488dc751f4d50f4616a6bf20186d06d5
|
||||
core.zh.md: 0e204ef9ce51db66dac491ffcb2a32682b8f4826
|
||||
core.md: 3bbfe3c4c763a24edb6ec1362344cef6ce50f650
|
||||
core.zh.md: d54159c25659a89baded31b8e3aa5207715e0c12
|
||||
|
||||
@@ -503,7 +503,7 @@ interface Agent {
|
||||
}
|
||||
```
|
||||
|
||||
`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox and admission facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([proposal](../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission leaves the provider default in control. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
|
||||
`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `followup()` returns no handle: its `MessageId` identifies durable inbox and admission facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)). `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission leaves the provider default in control. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
|
||||
|
||||
The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
|
||||
|
||||
|
||||
@@ -511,7 +511,7 @@ interface Agent {
|
||||
}
|
||||
```
|
||||
|
||||
`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 与准入事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[提案](../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时由提供方默认值控制。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
|
||||
`AgentStatus` 为 `'idle' | 'running'`，`SessionId` 是品牌类型。dispose（资源释放）会把 agent 从注册表移除并发出 `agent/disposed`；它不是一个终态 status 值。`running` 描述整个驱动器的排空区间，可能跨越连续的排队轮次；它不能证明某个轮次仍然打开。`followup()` 不返回 handle：其 `MessageId` 标识持久 inbox 与准入事实，而不标识之后的助手输出或轮次结束。`whenIdle()` 观察整个 agent，因此只有显式拥有从回执到 idle 这一完整区间的调用方才能将其称为一次运行（[决策](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。`AgentOptions` 可合并扩展：core 声明 `provider?`、`model?` 与 `maxTokens?`（在 `agent/request` 后，分发要求 provider 与 model 都存在）。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时由提供方默认值控制。Persona 归 `dsh-system-prompt` 所有：agent 作用域的 `deployment:persona` 可以遮蔽全局默认值。
|
||||
|
||||
cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 保留粗粒度 `{ kind: 'aborted' }` 结果；若需记录请求 provenance，应使用单独的持久事件，而不是让终态结果承担额外含义。
|
||||
|
||||
|
||||
@@ -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 packages/core/agent/README.md
|
||||
README.md: 987386c363705ded9ab074ed012dd0219e6c8308
|
||||
README.zh.md: 593a079bcf93e4c7a0785fb58c6abcb5be53693c
|
||||
README.md: cf9b0569a8c689222b46a551139178f2e353f680
|
||||
README.zh.md: 259eeb97555795d4d3a57fcd8deffadf00291b29
|
||||
|
||||
@@ -68,7 +68,7 @@ The handle every plugin programs against:
|
||||
- `agent.whenIdle()` — observe whole-agent quiescence, including replacement work scheduled before the current driver retires. It does not settle any particular message.
|
||||
- `agent.session`, `agent.status`, `agent.options`, `agent.id`, `agent.ctx`
|
||||
|
||||
`running` describes a driver-wide drain interval, not proof that a turn is still open; it can cover turn close, the durability checkpoint, and consecutive queued turns. Only a caller that owns a complete interval may summarize it as a run result ([proposal](../../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
|
||||
`running` describes a driver-wide drain interval, not proof that a turn is still open; it can cover turn close, the durability checkpoint, and consecutive queued turns. Only a caller that owns a complete interval may summarize it as a run result ([decision](../../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
|
||||
|
||||
### Extension points
|
||||
|
||||
|
||||
@@ -68,7 +68,7 @@ Agent *创建* 由实现 `AgentFactory` 的插件（`dsh-agent-loop`）提供，
|
||||
- `agent.whenIdle()`：观察整个 agent 达到完全停稳，包括当前驱动器退役前调度的替代工作。它不结算任何特定消息。
|
||||
- `agent.session`、`agent.status`、`agent.options`、`agent.id`、`agent.ctx`
|
||||
|
||||
`running` 描述驱动器范围的 drain 区间，而不是轮次仍打开的证明；它可以覆盖轮次关闭、持久性检查点和连续的排队轮次。只有拥有完整区间的调用方才能将其概括为一次运行的结果（[提案](../../../.agents/notes/proposed/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
|
||||
`running` 描述驱动器范围的 drain 区间，而不是轮次仍打开的证明；它可以覆盖轮次关闭、持久性检查点和连续的排队轮次。只有拥有完整区间的调用方才能将其概括为一次运行的结果（[决策](../../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)）。
|
||||
|
||||
### 扩展点
|
||||
|
||||
|
||||
Reference in New Issue
Block a user