@hy-sde-org/dsh-graph-control 0.1.2-rc.1 → 0.1.5-rc.1
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.
- package/README.i18n.yaml +2 -2
- package/README.md +6 -12
- package/README.zh.md +6 -12
- package/package.json +8 -8
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/graph/graph-control/README.md
|
|
5
|
-
README.md:
|
|
6
|
-
README.zh.md:
|
|
5
|
+
README.md: 82dd862268ec6f13ab0ce23b4adb60d0116c23f8
|
|
6
|
+
README.zh.md: 130008fcb7d935ce7383587845c504b88c6a4e54
|
package/README.md
CHANGED
|
@@ -1,21 +1,16 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: "Durable control plane for the Agent Graph: schedule updates, exactly-once intent claims, operator provisions, and supervisor wakes."
|
|
3
|
-
kind: "package-reference"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
1
|
# @hy-sde-org/dsh-graph-control
|
|
7
2
|
|
|
8
3
|
English | [中文](README.zh.md)
|
|
9
4
|
|
|
10
5
|
## Summary
|
|
11
6
|
|
|
12
|
-
`dsh-graph-control` is the durable decision store for the Agent Graph
|
|
7
|
+
`dsh-graph-control` is the durable decision store for the Agent Graph. It owns exactly the stateful rows a graph needs — the schedule-update log, exactly-once intent claims, operator provisions, and supervisor wakes — and nothing else: records, routes, readiness intents, work status, and client snapshots stay derived (the stream and projection packages fold them).
|
|
13
8
|
|
|
14
9
|
The store is designed around Maka's one hard rule: **the durable claim (with preallocated turn/run identity) is written before the runtime is ever asked to run**, and every claim/provision transition is conditional on the schedule revision it observed. A retry therefore reuses the same activation identity instead of invoking the provider twice. All ids are deterministic sha256 (`graph_update_…`, `graph_claim_…`, `graph_operator_…`, `graph_wake_…`), so replays are idempotent by construction.
|
|
15
10
|
|
|
16
11
|
Persistence: one `KvUnit` (`name: agent_graph`) with five authoritative tables; derived uniqueness indexes are rebuilt from those rows at open, so a torn write heals instead of corrupting. The storage contract forbids concurrent writers on one unit, so the store serializes mutations on one write chain and each per-record write is durable.
|
|
17
12
|
|
|
18
|
-
This package contributes no tool, prompt, or plugin row — the coordinator
|
|
13
|
+
This package contributes no tool, prompt, or plugin row — the stream-layer coordinator, the executor adapter, and the supervisor tools consume it.
|
|
19
14
|
|
|
20
15
|
## Table of Contents
|
|
21
16
|
|
|
@@ -46,19 +41,18 @@ Open the unit exactly once per process: the storage layer rejects double-open, a
|
|
|
46
41
|
- **Schedule log** (`schedule`): append-only decisions, revision = max+1, idempotent by `updateId` and by source triple `(session, run, toolCall)`; `finish` cannot combine with `add_work`; the graph is closed once a finish is committed.
|
|
47
42
|
- **Intent claims** (`claims`): keyed `graphId:intentId`, with activation-identity uniqueness (`(targetSessionId, targetTurnId)` and `(targetSessionId, targetRunId)`) enforced against derived indexes; transitions `claimed → executing → cancelled` are revision-conditional; fresh claims are rejected after closure while existing claims stay dispatchable.
|
|
48
43
|
- **Operator provisions** (`provisions`): deterministic `provisionId`/`operatorId` make retries adopt the same operator; revision-conditional and closure-blocked like claims.
|
|
49
|
-
- **Supervisor wakes** (`wakes` + `wake_attempts`): claim once, begin attempts (refused once delivered/superseded), complete with `waiting_permission | delivered | superseded | retryable_failed`; supersede by root session (+ optional graph filter); `recoverSupervisorWakes()` is deliberately a no-op — whether an interrupted attempt really completed is a Runtime fact, so the coordinator
|
|
44
|
+
- **Supervisor wakes** (`wakes` + `wake_attempts`): claim once, begin attempts (refused once delivered/superseded), complete with `waiting_permission | delivered | superseded | retryable_failed`; supersede by root session (+ optional graph filter); `recoverSupervisorWakes()` is deliberately a no-op — whether an interrupted attempt really completed is a Runtime fact, so the coordinator inspects run facts and completes accordingly. The store never guesses.
|
|
50
45
|
|
|
51
46
|
## Further Exploration
|
|
52
47
|
|
|
53
|
-
- [`
|
|
54
|
-
- Maka reference: `docs/architecture/agent-graph-stream-scheduling-draft.md` (Chapter 7) in the Maka checkout.
|
|
48
|
+
- Maka reference: [`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md) (Chapter 7).
|
|
55
49
|
|
|
56
50
|
## Model Experience
|
|
57
51
|
|
|
58
|
-
No model-facing surface. This package is host-side machinery; the supervisor tools of
|
|
52
|
+
No model-facing surface. This package is host-side machinery; the supervisor tools of `dsh-tool-graph` are what the model sees.
|
|
59
53
|
|
|
60
54
|
## Known Limitations and Deferred Work
|
|
61
55
|
|
|
62
56
|
- No epoch table: one DSH session owns one graph per the design decision (multi-graph-per-root is deferred).
|
|
63
57
|
- Multi-row CAS is process-atomic (one write chain), not transaction-atomic; a crash mid-sequence heals on open because indexes are derived. Claims with a torn write are recovered by the coordinator inspecting run facts, as in Maka.
|
|
64
|
-
- Derived work status (`requested/stopped/superseded`), records, routes, readiness, and client snapshots belong to
|
|
58
|
+
- Derived work status (`requested/stopped/superseded`), records, routes, readiness, and client snapshots belong to the stream and projection packages and are not stored here.
|
package/README.zh.md
CHANGED
|
@@ -1,21 +1,16 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: "Agent Graph 的持久化决策存储:调度更新、恰好一次的意图声明、操作员预置与主管唤醒。"
|
|
3
|
-
kind: "package-reference"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
1
|
# @hy-sde-org/dsh-graph-control
|
|
7
2
|
|
|
8
3
|
[English](README.md) | 中文
|
|
9
4
|
|
|
10
5
|
## 摘要
|
|
11
6
|
|
|
12
|
-
`dsh-graph-control` 是 Agent Graph
|
|
7
|
+
`dsh-graph-control` 是 Agent Graph 的持久化决策存储。它只持有图真正需要的有状态行——调度更新日志、恰好一次的意图声明、操作员预置和主管唤醒——其余一律不存:记录、路由、就绪意图、工作状态和客户端快照留给流层与投影包派生(session-projection 折叠)。
|
|
13
8
|
|
|
14
9
|
本包围绕 Maka 的一条硬规则设计:**持久化声明(含预分配的 turn/run 身份)必须在运行时被要求执行之前写入**,且每个声明/预置转换都以其观察到的调度修订号为前置条件。因此重试只会复用同一个激活身份,而不会第二次调用提供方。所有 ID 均为确定性 sha256(`graph_update_…`、`graph_claim_…`、`graph_operator_…`、`graph_wake_…`),重放天然幂等。
|
|
15
10
|
|
|
16
11
|
持久化:一个 `KvUnit`(`name: agent_graph`)承载五张权威表;派生唯一性索引在打开时从权威行重建,撕裂写入可自愈而非损坏。存储契约禁止同一单元的并发写入者,因此本存储将全部变更串在一条写链上,每条记录写入均持久化。
|
|
17
12
|
|
|
18
|
-
|
|
13
|
+
本包不提供任何工具、提示词或插件行——由流层协调器、执行器适配器和主管工具消费。
|
|
19
14
|
|
|
20
15
|
## 目录
|
|
21
16
|
|
|
@@ -48,22 +43,21 @@ const { claim } = await store.claimIntentAtScheduleRevision(claimRequest, update
|
|
|
48
43
|
- **调度日志**(`schedule`):只追加决策,修订号 = max+1,按 `updateId` 与源三元组 `(session, run, toolCall)` 幂等;`finish` 不能与 `add_work` 合并;一旦提交 finish,图即关闭。
|
|
49
44
|
- **意图声明**(`claims`):键为 `graphId:intentId`,激活身份唯一性(`(targetSessionId, targetTurnId)` 与 `(targetSessionId, targetRunId)`)由派生索引约束;`claimed → executing → cancelled` 转换以修订号为条件;关闭后拒绝新声明,但既有声明仍可派发。
|
|
50
45
|
- **操作员预置**(`provisions`):确定性 `provisionId`/`operatorId` 使重试采用同一操作员;与声明一样受修订号约束并在关闭后拦截。
|
|
51
|
-
- **主管唤醒**(`wakes` + `wake_attempts`):声明一次后开始尝试(已投递/已替代则拒绝);以 `waiting_permission | delivered | superseded | retryable_failed` 完成;按根会话(可选图过滤)替代;`recoverSupervisorWakes()`
|
|
46
|
+
- **主管唤醒**(`wakes` + `wake_attempts`):声明一次后开始尝试(已投递/已替代则拒绝);以 `waiting_permission | delivered | superseded | retryable_failed` 完成;按根会话(可选图过滤)替代;`recoverSupervisorWakes()` 刻意为空操作——中断的尝试是否真正完成属于运行时事实,协调器检查运行事实后完成之。本存储从不猜测。
|
|
52
47
|
|
|
53
48
|
<a id="further-exploration"></a>
|
|
54
49
|
## 进一步探索
|
|
55
50
|
|
|
56
|
-
- [`
|
|
57
|
-
- Maka 参考:Maka 检出中的 `docs/architecture/agent-graph-stream-scheduling-draft.md`(第 7 章)。
|
|
51
|
+
- Maka 参考:[`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md)(第 7 章)。
|
|
58
52
|
|
|
59
53
|
<a id="model-experience"></a>
|
|
60
54
|
## 模型体验
|
|
61
55
|
|
|
62
|
-
无模型可见面。本包是主机侧机制;模型看到的是
|
|
56
|
+
无模型可见面。本包是主机侧机制;模型看到的是 `dsh-tool-graph` 的主管工具。
|
|
63
57
|
|
|
64
58
|
<a id="known-limitations-and-deferred-work"></a>
|
|
65
59
|
## 已知限制与后续工作
|
|
66
60
|
|
|
67
61
|
- 无 epoch 表:按设计决策,一个 DSH 会话拥有一个图(每根多图推迟)。
|
|
68
62
|
- 多行 CAS 为进程原子(单写链)而非事务原子;崩溃后序列中撕裂的写入在打开时自愈,因为索引是派生的。撕裂写入的声明由协调器检查运行事实恢复,与 Maka 一致。
|
|
69
|
-
- 派生工作状态(`requested/stopped/superseded
|
|
63
|
+
- 派生工作状态(`requested/stopped/superseded`)、记录、路由、就绪与客户端快照属于流层与投影包,不在此存储。
|
package/package.json
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hy-sde-org/dsh-graph-control",
|
|
3
|
-
"description": "Durable control plane for the Agent Graph: schedule updates, exactly-once intent claims, operator provisions, and supervisor wakes
|
|
4
|
-
"version": "0.1.
|
|
3
|
+
"description": "Durable control plane for the Agent Graph: schedule updates, exactly-once intent claims, operator provisions, and supervisor wakes.",
|
|
4
|
+
"version": "0.1.5-rc.1",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
7
7
|
},
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/
|
|
11
|
-
"directory": "packages/graph
|
|
10
|
+
"url": "git+https://github.com/hy-sde/dsh-plugins.git",
|
|
11
|
+
"directory": "dsh-graph/packages/graph-control"
|
|
12
12
|
},
|
|
13
13
|
"type": "module",
|
|
14
|
-
"main": "
|
|
15
|
-
"types": "
|
|
14
|
+
"main": "./dist/index.js",
|
|
15
|
+
"types": "./dist/index.d.ts",
|
|
16
16
|
"exports": {
|
|
17
17
|
".": {
|
|
18
18
|
"types": "./dist/index.d.ts",
|
|
@@ -27,10 +27,10 @@
|
|
|
27
27
|
],
|
|
28
28
|
"license": "MIT",
|
|
29
29
|
"peerDependencies": {
|
|
30
|
-
"@deepseek-ai/dsh-storage": "^0.1.
|
|
30
|
+
"@deepseek-ai/dsh-storage": "^0.1.5-rc.1"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
|
-
"@deepseek-ai/dsh-storage": "^0.1.
|
|
33
|
+
"@deepseek-ai/dsh-storage": "^0.1.5-rc.1",
|
|
34
34
|
"@deepseek-ai/dsh-storage-sqlite": "^0.0.1-rc.1",
|
|
35
35
|
"@types/node": "^24.0.0",
|
|
36
36
|
"typescript": "^5.9.3",
|