@deepseek-ai/dsh-tool-goal 0.1.1-rc.2 → 0.1.2-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.i18n.yaml +2 -2
  2. package/README.md +98 -15
  3. package/README.zh.md +103 -20
  4. package/lib/index.js +23 -17
  5. package/lib/types/authority.d.ts +3 -7
  6. package/package.json +22 -19
package/README.i18n.yaml CHANGED
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/goal/tool-goal/README.md
5
- README.md: f8accfaaee2b68b090bc5dfd66a260c4af170530
6
- README.zh.md: c5875e26531465b0c8f0373d3e587ea626156ec2
5
+ README.md: a7016374d8de11d96db963a341e21f635b09ca3b
6
+ README.zh.md: 8353f8905f007f58d30d26b487e283896175a106
package/README.md CHANGED
@@ -1,30 +1,45 @@
1
+ ---
2
+ description: "The model-facing goal tools for users and maintainers choosing, composing, or debugging get_goal, create_goal, and update_goal."
3
+ kind: "package-reference"
4
+ ---
5
+
1
6
  # @deepseek-ai/dsh-tool-goal
2
7
 
3
8
  English | [中文](README.zh.md)
4
9
 
5
- The model-facing control tools for [`ctx.goals`](../goal/README.md): `get_goal`, `create_goal`, and `update_goal`. The [goal-tool Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) owns the authority split and Codex-shaped UX.
10
+ ## Summary
11
+
12
+ `dsh-tool-goal` gives the model three tools over the persisted goal service: `get_goal` reads the current goal, `create_goal` starts a new one, and `update_goal` edits, pauses, resumes, completes, or blocks it. The model may infer a long-running objective from a direct human request and create a goal; updates must carry the exact id and revision read beforehand. Authority is enforced at execution: create, edit, pause, and resume require a direct human turn on a top-level agent, while complete and blocked also accept the current goal round during automatic continuation. A configured threshold (default 3) bounds how soon an autonomous round may self-report `blocked`. Mount it with `dsh-goal` whenever the model should manage goals itself.
6
13
 
7
- ## Tools
14
+ ## Table of Contents
8
15
 
9
- - `get_goal()` returns the current goal or `null`, including the compare-and-set id/revision, durable phase, admitted/capped goal rounds, any blocker reason, and current process-local activation.
10
- - `create_goal(objective, max_goal_rounds?)` creates one goal from a direct top-level human turn. The model may infer long-running goal intent without an exact command phrase; non-human turns and subagents are rejected at execution.
11
- - `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` supports `edit`, `pause`, `resume`, `complete`, and `blocked`. Replacements belong only to `edit`; `blocked_reason` is required only for `blocked` and is persisted with the stable code `model-reported`. Strict-schema empty-string and zero fillers count as omitted, while meaningful values remain limited to their action.
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
12
22
 
13
- All calls are exclusive, so a model-ordered batch observes earlier mutations and their new revisions. UI clients receive pure generic cards: read for `get_goal`, other for mutations. Mutation cards select the first meaningful action value and otherwise show the goal id, so accepted fillers never produce blank input.
23
+ -----
14
24
 
15
- All three canonical values match the compact JSON already rendered to Native callers: `{ goal: null }` or `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`. Programmatic consumers therefore receive the same domain structure without parsing the rendered JSON.
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
16
27
 
17
- An autonomous goal round that successfully reports `complete` or `blocked` marks that tool execution with `concludeTurn()` so the physical turn stops after the step. Direct-human mutations never contribute this stop: the assistant may acknowledge the change and concurrent human steering remains available to the loop.
28
+ Mount `dsh-tool-goal` beside the goal service when the model should create and update persisted goals itself. The tools are the model-facing half of the goal surface; the `/goal` command is the human-facing half, and the continuation driver uses the same tools to complete or block goals at the end of autonomous rounds.
18
29
 
19
- ## Authority
30
+ ### Tools
20
31
 
21
- Execution requires the exact live `exec.agent`, its inherited `AgentRegistry` initiator, running status, and an open turn. Create, edit, pause, and resume additionally require an accepted `{ kind: 'user' }` message or steering event in a runtime-root agent's current turn. Durable fork lineage does not demote a resumed root; live subagent ownership does.
32
+ All three tools return the same compact JSON — `{ goal: null }` when no goal is current, otherwise the goal's id, revision, objective, phase, rounds started, round cap, optional blocker reason, and whether continuation is armed — matching what Native callers already render.
22
33
 
23
- `{ kind: 'user' }` is a host attestation. `Agent.followup()` and `steer()` assign it when their caller omits a source, so plugins, schedulers, and other non-human producers must pass their own source rather than inheriting human authority.
34
+ | Tool | What it does |
35
+ |---|---|
36
+ | `get_goal()` | Reads the current goal, or `null` when none is current |
37
+ | `create_goal(objective, max_goal_rounds?)` | Creates one goal from a direct top-level human turn |
38
+ | `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` | `edit`, `pause`, `resume`, `complete`, or `blocked` on the exact goal revision |
24
39
 
25
- Complete and blocked also accept the exact current goal round: a goal-sourced `user/message` whose id, revision, and round equal the folded current goal. A goal-round blocked call is mechanically rejected until `blockedAfterConsecutiveRounds`; the model judges whether the same condition actually persisted and must describe it in `blocked_reason`. Direct human authority may stop a goal immediately.
40
+ Call `get_goal` before `update_goal` and copy the exact `goal_id` and `revision`; all calls are exclusive, so a model-ordered batch observes earlier mutations and their new revisions. Replacements belong only to `edit`; `blocked_reason` is required only for `blocked` and is persisted with the stable code `model-reported`. Strict-schema empty-string and zero fillers count as omitted, while meaningful values remain limited to their action.
26
41
 
27
- ## Config
42
+ ### Configure it
28
43
 
29
44
  ```yaml
30
45
  - id: tool-goal
@@ -33,8 +48,61 @@ Complete and blocked also accept the exact current goal round: a goal-sourced `u
33
48
  blockedAfterConsecutiveRounds: 3
34
49
  ```
35
50
 
36
- The value must be a positive safe integer. It supplies both the hard lower bound on model self-blocking and the number named in model guidance.
51
+ The value must be a positive safe integer. It supplies both the hard lower bound on model self-blocking and the number named in model guidance. The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-goal) is the exhaustive source for every accepted field.
52
+
53
+ ### Authority rules
54
+
55
+ The tools execute only for the exact live calling agent inside its active driver with an open turn. `create`, `edit`, `pause`, and `resume` additionally require a direct human message in a runtime-root agent's current turn — a subagent or a non-human producer cannot create or edit goals. `complete` and `blocked` also accept the exact current goal round: a goal-sourced round may complete the goal immediately, but a blocked call is mechanically rejected until the configured number of consecutive rounds has passed — the model judges whether the same condition actually persisted and must describe it in `blocked_reason`. A direct human request may stop a goal immediately.
56
+
57
+ An autonomous round that successfully reports `complete` or `blocked` also ends the physical turn after that step, and the model receives a closing instruction to write the final message to the user. Direct-human mutations never trigger that stop: the assistant may acknowledge the change and the loop keeps concurrent human steering available.
58
+
59
+ -----
60
+
61
+ <a id="understand-the-implementation"></a>
62
+ ## Understand the implementation
63
+
64
+ <details>
65
+ <summary>Implementation internals — click to expand</summary>
66
+
67
+ This section explains how the tools enforce authority and render output; the observable contract is covered in [Use this package](#use-this-package).
68
+
69
+ ### Design
70
+
71
+ - **Authority at execution.** Every call resolves the exact live agent, its inherited `AgentRegistry` initiator, running status, and an open turn; `create`, `edit`, `pause`, and `resume` additionally require an accepted `{ kind: 'user' }` message or steering event in a runtime-root agent's current turn. Durable fork lineage does not demote a resumed root; live subagent ownership does.
72
+ - **Host attestation of human input.** `{ kind: 'user' }` is assigned by `Agent.followup()` and `steer()` when their caller omits a source, so plugins, schedulers, and other non-human producers must pass their own source rather than inheriting human authority.
73
+ - **System-prompt guidance with the configured threshold.** The package registers one `tool:goal` system-prompt section whose fixed text interpolates `blockedAfterConsecutiveRounds`; the same value is the hard lower bound enforced at execution.
74
+ - **Wrap-up context for terminal rounds.** A successful autonomous `complete` or `blocked` defers a closing `<goal_complete>` or `<goal_blocked>` instruction so the model addresses the user once before the turn ends; direct-human mutations never defer this context.
75
+
76
+ ### Source map
77
+
78
+ | File | Role |
79
+ |---|---|
80
+ | [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, config, system-prompt section, result rendering |
81
+ | [`src/authority.ts`](src/authority.ts) | Execution-time authority checks and goal-round acceptance |
82
+ | [`src/wrapup.ts`](src/wrapup.ts) | Closing-message instruction for terminal autonomous updates |
83
+ | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: empty (no runtime invariant — the goal domain owns accepted mutations) |
84
+
85
+ ### Tool output
37
86
 
87
+ All three tools share one canonical output: the compact JSON `{ goal: null }` or `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`. `activation` in a result is a live observation and never becomes replay authority. UI clients receive pure generic cards — read for `get_goal`, other for mutations.
88
+
89
+ </details>
90
+
91
+ -----
92
+
93
+ <a id="further-exploration"></a>
94
+ ## Further Exploration
95
+
96
+ The tools are the model-facing half of the goal surface; read these pages for the state they mutate and the policy they defer to.
97
+
98
+ - [Goal service](../goal/README.md) — the goal state and lifecycle the tools mutate.
99
+ - [Goal group map](../README.md) — the goal packages and how they compose.
100
+ - [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-goal) — the exact schemas the model receives.
101
+ - [Goal-tool Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.md) — the authority split and UX decisions.
102
+
103
+ -----
104
+
105
+ <a id="model-experience"></a>
38
106
  ## Model Experience
39
107
 
40
108
  ### System prompt
@@ -73,8 +141,23 @@ Schemas are prefix-stable while their definitions and visibility are unchanged.
73
141
 
74
142
  ## Known Limitations and Deferred Work
75
143
 
144
+ <a id="known-limitations-and-deferred-work"></a>
145
+
146
+
147
+ These limits define when the goal tools are a poor fit or need special care. They are current package constraints, not a task backlog.
148
+
76
149
  - **Semantic intent remains model judgment** — execution can prove that the current turn contains a direct human message, not whether the request is substantial enough to merit a goal.
77
150
  - **Same-condition blocking remains model judgment** — the runtime enforces distinct admitted-round count, not semantic equivalence of obstacles; an independent evaluator is deferred.
78
- - **No scheduling or direct human rendering** — these tools mutate state only; the same-session driver and [`dsh-command-goal`](../command-goal/README.md) are independent consumers of the same domain.
151
+ - **No scheduling or direct human rendering** — these tools mutate state only; the same-session driver and `dsh-command-goal` are independent consumers of the same domain.
79
152
  - **Goal-round authority requires a driver** — the autonomous `complete`/`blocked` path is dormant unless a continuation driver admits goal-sourced user turns; mounting this tool package alone does not create them.
80
153
  - **Prompt registration is independent of filtering** — a scope may hide the tools while retaining their guidance unless the deployment scopes both registrations together.
154
+
155
+ <a id="dev-note"></a>
156
+ ### Dev Note
157
+
158
+ <details>
159
+ <summary>Working context for maintainers — click to expand</summary>
160
+
161
+ This Dev Note is working context for maintainers; it is explicitly non-authoritative. Open question: whether the goal-policy section should be independently scoped from the tool registrations, so a scope cannot hide the tools while keeping the guidance.
162
+
163
+ </details>
package/README.zh.md CHANGED
@@ -1,30 +1,45 @@
1
+ ---
2
+ description: "面向选择、组合或排查 get_goal、create_goal 与 update_goal 的用户与维护者的模型侧 goal 工具说明。"
3
+ kind: "package-reference"
4
+ ---
5
+
1
6
  # @deepseek-ai/dsh-tool-goal
2
7
 
3
8
  [English](README.md) | 中文
4
9
 
5
- [`ctx.goals`](../goal/README.zh.md) 的面向模型控制 API：`get_goal`、`create_goal` 和 `update_goal`。[goal 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md) 负责权限拆分与 Codex 风格用户体验。
10
+ ## 概述
11
+
12
+ `dsh-tool-goal` 为模型提供基于持久 goal 服务的三个工具：`get_goal` 读取当前 goal，`create_goal` 创建新 goal，`update_goal` 编辑、暂停、恢复、完成或阻塞它。模型可以从人类直接请求中推断长期目标并创建 goal；更新必须携带先前读取到的精确 id 与 revision。权限在执行时强制：create、edit、pause 和 resume 要求顶层 agent 的当前轮次中存在人类直接消息；complete 和 blocked 在自动续行期间还接受当前 Goal Round。可配置的阈值（默认 3）约束自主 Round 多快可以自行报告 `blocked`。当模型需要自行管理 goal 时，与 `dsh-goal` 一起挂载它。
6
13
 
7
- ## 工具
14
+ ## 目录
8
15
 
9
- - `get_goal()` 返回当前 goal 或 `null`，包括比较并设置 id／revision、持久 phase、Goal Round 的已准入数／上限、任何 blocker reason，以及当前进程本地续行启用状态。
10
- - `create_goal(objective, max_goal_rounds?)` 根据人类直接发起的顶层轮次创建一个 goal。模型可以推断长期运行的 goal 意图，而无需精确命令短语；非人类轮次和 subagent 会在执行时被拒绝。
11
- - `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`。替换值只属于 `edit`；`blocked_reason` 只有在 action 为 `blocked` 时才必填，并以稳定代码 `model-reported` 持久化。严格 schema 下的空字符串和零填充值视为省略，而有意义的值仍限定到各自 action。
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
12
22
 
13
- 所有调用都互斥，因此模型排序的批次能观察到更早变更及其新 revision。UI 客户端会收到纯通用卡片：`get_goal` 使用 read，变更使用 other。变更卡片选择第一个有意义的 action 值，否则显示 goal id，因此已接受的填充值绝不会产生空输入。
23
+ -----
14
24
 
15
- 3 个规范值都与已经渲染给 Native 调用方的紧凑 JSON 一致：`{ goal: null }` 或 `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`。因此，编程消费方无需解析渲染后的 JSON，即可收到相同领域结构。
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
16
27
 
17
- 自主 Goal Round 成功报告 `complete` 或 `blocked` 时，会用 `concludeTurn()` 标记该次工具执行，使物理轮次在该步骤后停止。人类直接变更绝不会导致这种停止：assistant 可以确认变更，循环仍可接收并发的人类 steering（中途引导）。
28
+ 当模型需要自行创建和更新持久 goal 时，把 `dsh-tool-goal` 挂在 goal 服务旁边。这些工具是 goal 表面面向模型的一半；`/goal` 命令是面向人类的一半，续行驱动器在自主 Round 结束时使用同一套工具完成或阻塞 goal。
18
29
 
19
- ## 权限
30
+ ### 工具
20
31
 
21
- 执行要求完全相同的活跃 `exec.agent`、其继承的 `AgentRegistry` initiator、running 状态与开放轮次。create、edit、pause 和 resume 还要求运行时根 agent（智能体）的当前轮次中存在已接受的 `{ kind: 'user' }` 消息或 steering 事件。持久 fork 谱系不会降低已恢复根 agent 的等级；活跃 subagent 所有权会降低。
32
+ 三个工具都返回相同的紧凑 JSON——没有当前 goal 时为 `{ goal: null }`，否则返回 goal 的 id、revision、目标、phase、已开始 Round、Round 上限、可选的 blocker reason 与续行是否已启用——与 Native 调用方已经渲染的内容一致。
22
33
 
23
- `{ kind: 'user' }` 是宿主证明。`Agent.followup()` 与 `steer()` 会在调用方省略 source 时分配该值，因此插件、调度器与其他非人类生产方必须传入自己的 source，不能继承用户权限。
34
+ | 工具 | 作用 |
35
+ |---|---|
36
+ | `get_goal()` | 读取当前 goal；没有当前 goal 时返回 `null` |
37
+ | `create_goal(objective, max_goal_rounds?)` | 根据人类直接发起的顶层轮次创建一个 goal |
38
+ | `update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` | 对精确 goal revision 执行 `edit`、`pause`、`resume`、`complete` 或 `blocked` |
24
39
 
25
- complete 与 blocked 还接受完全一致的当前 Goal Round：来源为 goal 的 `user/message`，其 id、revision 和 Round 编号与折叠后的当前 goal 相等。在达到 `blockedAfterConsecutiveRounds` 前，Goal Round 的 blocked 调用会被机械拒绝；模型判断同一条件是否确实持续，并必须在 `blocked_reason` 中说明。人类直接授权可以立即停止 goal。
40
+ 在 `update_goal` 之前调用 `get_goal`，并复制精确的 `goal_id` 与 `revision`；所有调用都互斥，因此模型排序的批次能观察到更早变更及其新 revision。替换值只属于 `edit`；`blocked_reason` 只有在 `blocked` 时才必填，并以稳定代码 `model-reported` 持久化。严格 schema 下的空字符串和零填充值视为省略，而有意义的值仍限定到各自 action。
26
41
 
27
- ## 配置
42
+ ### 配置
28
43
 
29
44
  ```yaml
30
45
  - id: tool-goal
@@ -33,8 +48,61 @@ complete 与 blocked 还接受完全一致的当前 Goal Round：来源为 goal
33
48
  blockedAfterConsecutiveRounds: 3
34
49
  ```
35
50
 
36
- 该值必须是正的安全整数。它既提供模型自行报告阻塞的硬下限，也决定模型指引中指明的数值。
51
+ 该值必须是正的安全整数。它既提供模型自行报告阻塞的硬下限，也决定模型指引中指明的数值。生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-goal)是每个受支持字段的穷尽式真源。
52
+
53
+ ### 权限规则
54
+
55
+ 工具只为活跃驱动器内、处于开放轮次中的精确活跃调用 agent 执行。`create`、`edit`、`pause` 和 `resume` 还要求运行时根 agent（智能体）的当前轮次中存在人类直接消息——subagent 或非人类生产方不能创建或编辑 goal。`complete` 和 `blocked` 还接受完全一致的当前 Goal Round：来源为 goal 的 Round 可以立即完成 goal，但 blocked 调用在达到配置的连续 Round 数量之前会被机械拒绝——模型判断同一条件是否确实持续，并必须在 `blocked_reason` 中说明。人类直接请求可以立即停止 goal。
56
+
57
+ 成功报告 `complete` 或 `blocked` 的自主 Round 还会在该步骤后结束物理轮次，模型会收到一条结束指令，要求向用户写出最终消息。人类直接变更绝不会触发这种停止：assistant 可以确认变更，循环仍可接收并发的人类 steering（中途引导）。
58
+
59
+ -----
60
+
61
+ <a id="understand-the-implementation"></a>
62
+ ## 理解实现
63
+
64
+ <details>
65
+ <summary>实现细节——点击展开</summary>
66
+
67
+ 本节解释工具如何强制执行权限并渲染输出；可观察约定已在[使用本包](#use-this-package)中说明。
68
+
69
+ ### 设计
70
+
71
+ - **执行时权限。** 每次调用都解析精确活跃 agent、其继承的 `AgentRegistry` initiator、running 状态与开放轮次；`create`、`edit`、`pause` 和 `resume` 还要求运行时根 agent 的当前轮次中存在已接受的 `{ kind: 'user' }` 消息或 steering 事件。持久 fork 谱系不会降低已恢复根 agent 的等级；活跃 subagent 所有权会降低。
72
+ - **人类输入的宿主证明。** `Agent.followup()` 与 `steer()` 会在调用方省略 source 时分配 `{ kind: 'user' }`，因此插件、调度器与其他非人类生产方必须传入自己的 source，不能继承人类权限。
73
+ - **带配置阈值的系统提示词指引。** 本包注册一个 `tool:goal` 系统提示词章节，其固定文本插入 `blockedAfterConsecutiveRounds`；同一数值就是执行时强制执行的硬下限。
74
+ - **终局 Round 的结束上下文。** 成功的自主 `complete` 或 `blocked` 会延后一条 `<goal_complete>` 或 `<goal_blocked>` 结束指令，让模型在轮次结束前向用户做一次交代；人类直接变更绝不会延后该上下文。
75
+
76
+ ### 源码地图
77
+
78
+ | 文件 | 职责 |
79
+ |---|---|
80
+ | [`src/index.ts`](src/index.ts) | 插件入口：工具注册、配置、系统提示词章节、结果渲染 |
81
+ | [`src/authority.ts`](src/authority.ts) | 执行时权限检查与 Goal Round 接受 |
82
+ | [`src/wrapup.ts`](src/wrapup.ts) | 终局自主更新的结束消息指令 |
83
+ | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生：空（无运行时不变式——已接受的变更由 goal 领域负责） |
84
+
85
+ ### 工具输出
37
86
 
87
+ 三个工具共用一种规范输出：紧凑 JSON `{ goal: null }`，或 `{ goal: { id, revision, objective, phase, roundsStarted, maxGoalRounds, blockedReason? }, activation }`。结果中的 `activation` 是实时观察值，绝不会成为回放权限依据。UI 客户端收到纯通用卡片——`get_goal` 为 read，变更使用 other。
88
+
89
+ </details>
90
+
91
+ -----
92
+
93
+ <a id="further-exploration"></a>
94
+ ## 进一步探索
95
+
96
+ 这些工具是 goal 表面面向模型的一半；需要了解它们变更的状态与它们交由的策略时阅读以下页面。
97
+
98
+ - [goal 服务](../goal/README.zh.md)——工具变更的 goal 状态与生命周期。
99
+ - [goal 组地图](../README.zh.md)——goal 各包及其组合方式。
100
+ - [生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-goal)——模型接收的精确 schema。
101
+ - [goal 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.zh.md)——权限拆分与 UX 决策。
102
+
103
+ -----
104
+
105
+ <a id="model-experience"></a>
38
106
  ## 模型体验
39
107
 
40
108
  ### 系统提示词
@@ -71,10 +139,25 @@ Use goal tools for one long-running completion objective in the current session.
71
139
 
72
140
  schema 的定义与可见性不变时，前缀保持稳定。调用和结果会追加到可复用请求前缀之后，不会使更早条目失效。
73
141
 
74
- ## 已知限制与暂缓事项
142
+ ## 已知限制与延期工作
143
+
144
+ <a id="known-limitations-and-deferred-work"></a>
145
+
146
+
147
+ 这些限制说明 goal 工具何时不合适或需要特别注意。它们是当前包约束，不是任务积压。
148
+
149
+ - **语义意图仍由模型判断**——执行只能证明当前轮次包含一条人类直接发送的消息，无法证明请求是否足够重大而值得创建 goal。
150
+ - **阻塞条件是否相同仍由模型判断**——运行时强制统计互不重复的已准入 Goal Round，而不判断障碍在语义上是否等价；独立评估器的实现暂缓。
151
+ - **不负责调度或直接面向人类呈现**——这些工具只变更状态；同会话驱动器与 `dsh-command-goal` 是同一领域的独立消费方。
152
+ - **Goal Round 权限需要驱动器**——除非续行驱动器准入 goal 来源的用户轮次，否则自主 `complete`／`blocked` 路径不会启用；只挂载这个包不会创建这些轮次。
153
+ - **提示词注册与过滤相互独立**——某个范围可能隐藏工具，却保留指引，除非部署将两项注册限定在同一范围。
154
+
155
+ <a id="dev-note"></a>
156
+ ### 开发备注
157
+
158
+ <details>
159
+ <summary>维护者的工作上下文——点击展开</summary>
160
+
161
+ 本开发备注是维护者的工作上下文，明确不具权威性。开放问题：goal 策略章节是否应与工具注册独立限定范围，避免某个范围隐藏工具却保留指引。
75
162
 
76
- - **语义意图仍由模型判断**：执行只能证明当前轮次包含一条人类直接发送的消息，无法证明请求是否足够重大而值得创建 goal。
77
- - **阻塞条件是否相同仍由模型判断**：运行时强制统计互不重复的已准入 Goal Round，而不判断障碍在语义上是否等价；独立评估器的实现暂缓。
78
- - **不负责调度或直接面向人类呈现**：这些工具只变更状态；同会话驱动器与 [`dsh-command-goal`](../command-goal/README.zh.md) 是同一领域的独立消费方。
79
- - **Goal Round 权限需要驱动器**：除非续行驱动器准入 goal 来源的用户轮次，否则自主 `complete`／`blocked` 路径不会启用；只挂载这个包不会创建这些轮次。
80
- - **提示词注册与过滤相互独立**：某个范围可能隐藏工具，却保留指引，除非部署将两项注册限定在同一范围。
163
+ </details>
package/lib/index.js CHANGED
@@ -8,24 +8,21 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
8
8
  function reject(message, code = "GOAL_TOOL_AUTHORITY_REQUIRED") {
9
9
  throw new HarnessError(message, code);
10
10
  }
11
- /** Locate the open turn enclosing a model tool call. */
12
- function openTurn(agent) {
11
+ /** Resolve the immutable event cut and open-turn boundary without copying the turn suffix. */
12
+ function openTurnEvents(ctx, agent) {
13
13
  const events = agent.session.events;
14
- for (let index = events.length - 1; index >= 0; index -= 1) {
15
- const boundary = events[index];
16
- if (boundary?.type === "turn/end") reject("goal tools require an open model turn", "GOAL_TOOL_DRIVER_REQUIRED");
17
- if (boundary?.type === "turn/start") return {
18
- start: boundary,
19
- events: events.slice(index + 1)
20
- };
21
- }
22
- return reject("goal tools require an open model turn", "GOAL_TOOL_DRIVER_REQUIRED");
14
+ const boundary = ctx.sessionProjections.stateOf(agent.session, "turnBoundary");
15
+ if (boundary === void 0 || boundary.openTurnStartSeq === null) reject("goal tools require an open model turn", "GOAL_TOOL_DRIVER_REQUIRED");
16
+ return {
17
+ events,
18
+ openTurnStartSeq: boundary.openTurnStartSeq
19
+ };
23
20
  }
24
21
  /**
25
22
  * Resolve and authenticate the calling agent and its driver boundary.
26
23
  * @param ctx - Context carrying the live agent registry.
27
24
  * @param exec - Tool execution metadata supplied by the registry.
28
- * @returns The authenticated agent and its current turn window.
25
+ * @returns The authenticated agent, immutable event cut, and open-turn boundary.
29
26
  */
30
27
  function goalToolExecution(ctx, exec) {
31
28
  const agent = exec.agent;
@@ -33,9 +30,17 @@ function goalToolExecution(ctx, exec) {
33
30
  if (ctx.agents.get(agent.id) !== agent || agent.status !== "running" || ctx.agents.currentInitiator() !== agent) return reject("goal tools require the exact live calling agent inside its active driver", "GOAL_TOOL_DRIVER_REQUIRED");
34
31
  return {
35
32
  agent,
36
- ...openTurn(agent)
33
+ ...openTurnEvents(ctx, agent)
37
34
  };
38
35
  }
36
+ /** Whether the captured open turn contains an event accepted by `predicate`. */
37
+ function someOpenTurnEvent(execution, predicate) {
38
+ for (let seq = execution.openTurnStartSeq + 1; seq < execution.events.length; seq += 1) {
39
+ const event = execution.events[seq];
40
+ if (event !== void 0 && predicate(event)) return true;
41
+ }
42
+ return false;
43
+ }
39
44
  /**
40
45
  * Whether host-attested human input appears in the current root-agent turn.
41
46
  * An omitted `Agent.followup()` / `steer()` source resolves to `user`, so non-human
@@ -43,11 +48,11 @@ function goalToolExecution(ctx, exec) {
43
48
  */
44
49
  function hasDirectHumanInput(ctx, execution) {
45
50
  if (!ctx.agents.roots().includes(execution.agent)) return false;
46
- return execution.events.some((event) => event.type === "user/message" && event.data.source.kind === "user");
51
+ return someOpenTurnEvent(execution, (event) => event.type === "user/message" && event.data.source.kind === "user");
47
52
  }
48
53
  /** Whether this turn is the current goal's exact admitted round. */
49
54
  function isMatchingGoalRound(execution, goal) {
50
- return execution.events.some((event) => event.type === "user/message" && event.data.source.kind === "goal" && event.data.source.goalId === goal.id && event.data.source.revision === goal.revision && event.data.source.round === goal.roundsStarted);
55
+ return someOpenTurnEvent(execution, (event) => event.type === "user/message" && event.data.source.kind === "goal" && event.data.source.goalId === goal.id && event.data.source.revision === goal.revision && event.data.source.round === goal.roundsStarted);
51
56
  }
52
57
  /**
53
58
  * Require authority originating in a human message accepted by a runtime root.
@@ -103,7 +108,8 @@ const inject = [
103
108
  "agents",
104
109
  "goals",
105
110
  "tools",
106
- "systemPrompt"
111
+ "systemPrompt",
112
+ "sessionProjections"
107
113
  ];
108
114
  /** Schemastery config for the goal-tool policy. */
109
115
  const Config = z.object({ blockedAfterConsecutiveRounds: z.number().step(1).min(1).default(3) });
@@ -252,7 +258,7 @@ function apply(ctx, config) {
252
258
  const resolved = resolveConfig(config);
253
259
  ctx.systemPrompt.section({
254
260
  name: "tool:goal",
255
- order: 114,
261
+ order: ctx.systemPrompt.getSectionOrder("TOOL_GOAL"),
256
262
  text: guidance(resolved.blockedAfterConsecutiveRounds)
257
263
  });
258
264
  ctx.tools.register(defineTool({
package/lib/types/authority.d.ts CHANGED
@@ -4,14 +4,11 @@ import type { Agent } from '@deepseek-ai/dsh-agent';
4
4
  import type { GoalView } from '@deepseek-ai/dsh-goal';
5
5
  import type { SessionEvent } from '@deepseek-ai/dsh-session';
6
6
  import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
7
- type TurnStartEvent = Extract<SessionEvent, {
8
- type: 'turn/start';
9
- }>;
10
- /** Current open turn plus the events accepted after its start boundary. */
7
+ /** The calling agent plus the immutable event cut and open-turn start seq used for authority checks. */
11
8
  export interface GoalToolExecution {
12
9
  readonly agent: Agent;
13
- readonly start: TurnStartEvent;
14
10
  readonly events: readonly SessionEvent[];
11
+ readonly openTurnStartSeq: number;
15
12
  }
16
13
  /** Hard authority granted to one state-changing call. */
17
14
  export type GoalToolAuthority = {
@@ -24,7 +21,7 @@ export type GoalToolAuthority = {
24
21
  * Resolve and authenticate the calling agent and its driver boundary.
25
22
  * @param ctx - Context carrying the live agent registry.
26
23
  * @param exec - Tool execution metadata supplied by the registry.
27
- * @returns The authenticated agent and its current turn window.
24
+ * @returns The authenticated agent, immutable event cut, and open-turn boundary.
28
25
  */
29
26
  export declare function goalToolExecution(ctx: Context, exec: ToolRunContext): GoalToolExecution;
30
27
  /**
@@ -40,5 +37,4 @@ export declare function requireDirectHuman(ctx: Context, execution: GoalToolExec
40
37
  * @returns The direct-human or exact-goal-round authority grant.
41
38
  */
42
39
  export declare function completionAuthority(ctx: Context, execution: GoalToolExecution): GoalToolAuthority;
43
- export {};
44
40
  //# sourceMappingURL=authority.d.ts.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-tool-goal",
3
3
  "description": "Model-facing same-session goal tools with execution-time authority checks",
4
- "version": "0.1.1-rc.2",
4
+ "version": "0.1.2-alpha.2",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -32,27 +32,30 @@
32
32
  ],
33
33
  "license": "MIT",
34
34
  "peerDependencies": {
35
- "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
36
- "@deepseek-ai/dsh-goal": "^0.1.1-rc.2",
37
- "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
38
- "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
39
- "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
40
- "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
41
- "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
42
- "@deepseek-ai/cordis": "^4.0.1"
35
+ "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
36
+ "@deepseek-ai/dsh-goal": "^0.1.2-alpha.2",
37
+ "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
38
+ "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
39
+ "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
40
+ "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
41
+ "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
42
+ "@deepseek-ai/cordis": "^4.0.2",
43
+ "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2"
43
44
  },
44
45
  "dependencies": {
45
- "@deepseek-ai/schemastery": "^3.18.1"
46
+ "@deepseek-ai/schemastery": "^3.18.2"
46
47
  },
47
48
  "devDependencies": {
48
- "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
49
- "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
50
- "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
51
- "@deepseek-ai/dsh-goal": "^0.1.1-rc.2",
52
- "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
53
- "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
54
- "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
55
- "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
56
- "@deepseek-ai/cordis": "^4.0.1"
49
+ "@deepseek-ai/dsh-agent-loop": "^0.1.2-alpha.2",
50
+ "@deepseek-ai/dsh-goal": "^0.1.2-alpha.2",
51
+ "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
52
+ "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
53
+ "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
54
+ "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
55
+ "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
56
+ "@deepseek-ai/cordis": "^4.0.2",
57
+ "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
58
+ "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
59
+ "@deepseek-ai/dsh-session": "^0.1.2-alpha.2"
57
60
  }
58
61
  }