@robiteame/dsh-tool-session-tree 0.1.0

package/README.i18n.yaml

@@ -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 packages/extensions/tool-session-tree/README.md
+README.md: 4f13ffd46a8a842a91bcc98a514deff06ac8b60b
+README.zh.md: e00633ad46600dcb9755f7b23b407b20464af7b2

package/README.md

@@ -0,0 +1,98 @@
+# tool-session-tree
+
+English | [中文](README.zh.md)
+
+Model-facing companion of the session-tree service: the `session_tree` tool,
+the `/tree` command family, and a system-prompt section over the shared
+append-only session-tree store. All state lives in
+`sessionTreeStore` (`@robiteame/dsh-pi-agent-session-tree`), so the model,
+the command line, and the browser panel observe the same trees.
+
+## Surfaces
+
+| Surface | Name | Notes |
+|---|---|---|
+| Tool | `session_tree` | one tree per agent session; operations below |
+| Command | `/tree` | Opens/refreshes the right sidebar; low-level subcommands remain available for automation |
+| Commands | `/fork`, `/clone`, `/session` | Fork or clone the selected sidebar node with no IDs; inspect tree status |
+
+## Tool operations
+
+`create`, `append`, `list`, `branches`, `tree`, `jump`, `fork`, `clone`,
+`context`, `session`, `branch`, `branch.summary`, `snapshot.save`,
+`snapshot.load`, `sessions`.
+
+- `context` returns `{cursor, messages}` — the standard LLM messages array for
+  the root→cursor path.
+- `branch` parks the cursor at an existing node and names the next append's
+  branch; `branch.summary` additionally appends a summary node. Historical
+  nodes are never modified or deleted.
+- `snapshot.save` returns the versioned snapshot; `snapshot.load` restores it
+  under the same sessionId (`version: 1`).
+
+Every operation answers `{ok: true, value}` or
+`{ok: false, error: {code, message}}`, so tool results are always lossless
+JSON with a stable failure vocabulary. Human `/fork` and `/clone` commands
+require a sidebar selection and otherwise return `请先在右侧会话树选中目标节点`.
+
+## Tool examples
+
+```json
+{"operation":"create","sessionId":"demo"}
+{"operation":"append","sessionId":"demo","message":{"role":"user","content":"Explore option A"}}
+{"operation":"append","sessionId":"demo","message":{"role":"assistant","content":"Baseline answer"}}
+{"operation":"branch","sessionId":"demo","nodeId":"<root-nodeId>","branch":"option-b"}
+{"operation":"append","sessionId":"demo","message":{"role":"user","content":"Explore option B"},"branch":"option-b"}
+{"operation":"context","sessionId":"demo"}
+{"operation":"snapshot.save","sessionId":"demo"}
+{"operation":"snapshot.load","sessionId":"demo","snapshot":{"version":1,"sessionId":"demo","cursor":null,"activeBranch":"main","nodes":[]}}
+```
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+A fixed section tells the model that the tree projects the durable Harness Session log: native turns synchronize automatically, `context` reads the active branch after navigation, `append` is only for explicit custom entries, and branching never edits history. The `surface` field reported by `context` and `session` states the active surface mode (`native`, `stock`, or `projection`).
+##### SessionTree guidance
+
+```markdown
+SessionTree is the append-only projection of this agent's durable Harness Session log. Native user, assistant, tool, and model-context events are synchronized automatically: never duplicate ordinary turns with operation 'append'. Before answering after navigation, call session_tree with operation 'context' and treat its root-to-cursor messages as the active branch context. Use 'append' only for an explicit custom tree entry not already recorded by Harness. To explore an alternative, call 'fork' or 'branch' with a historical nodeId and branch name (or 'branch.summary' to record a summary); old nodes are never modified or deleted. Use 'branches' and 'tree' to inspect topology, and 'snapshot.save'/'snapshot.load' for explicit export or full-tree restore. All operations report failures as {ok:false,error:{code,message}}. Depending on the Harness build, jump/fork switch the model-visible history either through the native selected-surface API or through an official replace-surface emulation; when neither is available the tree is projection-only. The surface field reported by 'context' and 'session' states the active mode: native, stock, or projection.
+```
+
+#### Token effect
+
+Small fixed input cost on every request where this plugin's prompt registration is in scope, plus the returned JSON for each `context` call.
+
+#### KV Cache effect
+
+Prefix-stable while the plugin scope and guidance text are unchanged. The `context` result is dynamic output and never joins the reusable prefix.
+
+### Tool schemas and results
+
+#### What the model sees
+
+The generated [`session_tree` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-session-tree) (one `operation` discriminant plus JSON payload fields). Successful results are compact JSON envelopes; a failed operation returns `{ok: false, error: {code, message}}` instead of throwing.
+
+#### Token effect
+
+Fixed schema cost plus one compact result per call.
+
+#### KV Cache effect
+
+Schemas are prefix-stable while their definitions and visibility are unchanged. Calls and results append after the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- **Native events are durable** — the tree is rebuilt from the Harness Session
+  event log on live sync; explicit snapshots provide full-tree export and
+  restore, while the native model surface follows the active leaf.
+- **Patched versus official Harness** — a patched checkout persists
+  `session-tree/*` markers and uses the selected-surface API. An official
+  Bundle appends an official `replace` surface event when the cursor moves and
+  persists branch metadata in the sidecar at
+  `$DSH_HOME/storages/session-tree/<sessionId>.json`.
+- **The store is process-wide** — a restarted process reconstructs trees from
+  persisted Session events, and on an official Bundle additionally restores
+  the sidecar before the owning agent's next pre-step.

package/README.zh.md

@@ -0,0 +1,77 @@
+# tool-session-tree
+
+[English](README.md) | 中文
+
+会话树服务的模型面配套：`session_tree` 工具、`/tree` 命令族，以及共享只追加会话树存储之上的 system-prompt 片段。所有状态都在 `sessionTreeStore`（`@robiteame/dsh-pi-agent-session-tree`）中，因此模型、命令行与浏览器面板观察到同一批树。
+
+## 表面
+
+| 表面 | 名称 | 说明 |
+|---|---|---|
+| 工具 | `session_tree` | 每个 agent 会话一棵树；操作见下 |
+| 命令 | `/tree` | 打开或刷新右侧会话树；低级子命令继续供自动化使用 |
+| 命令 | `/fork`、`/clone`、`/session` | 无需 ID，直接 fork/clone 右侧选中节点；查看树状态 |
+
+## 工具操作
+
+`create`、`append`、`list`、`branches`、`tree`、`jump`、`fork`、`clone`、`context`、`session`、`branch`、`branch.summary`、`snapshot.save`、`snapshot.load`、`sessions`。
+
+- `context` 返回 `{cursor, messages}`——根→光标路径的标准 LLM messages 数组。
+- `branch` 把光标停在已有节点并命名下一次 append 的分支；`branch.summary` 额外追加摘要节点。历史节点永不被修改或删除。
+- `snapshot.save` 返回版本化快照；`snapshot.load` 在同一 sessionId 下恢复（`version: 1`）。
+
+每次操作都返回 `{ok: true, value}` 或 `{ok: false, error: {code, message}}`，因此工具结果始终是无损 JSON，并带有稳定失败词表。用户执行 `/fork`、`/clone` 前必须先点击右侧节点，否则返回“请先在右侧会话树选中目标节点”。
+
+## 工具示例
+
+```json
+{"operation":"create","sessionId":"demo"}
+{"operation":"append","sessionId":"demo","message":{"role":"user","content":"Explore option A"}}
+{"operation":"append","sessionId":"demo","message":{"role":"assistant","content":"Baseline answer"}}
+{"operation":"branch","sessionId":"demo","nodeId":"<root-nodeId>","branch":"option-b"}
+{"operation":"append","sessionId":"demo","message":{"role":"user","content":"Explore option B"},"branch":"option-b"}
+{"operation":"context","sessionId":"demo"}
+{"operation":"snapshot.save","sessionId":"demo"}
+{"operation":"snapshot.load","sessionId":"demo","snapshot":{"version":1,"sessionId":"demo","cursor":null,"activeBranch":"main","nodes":[]}}
+```
+
+## 模型体验
+
+### 系统提示
+
+#### 模型看到什么
+
+一段固定文本告诉模型：树是 Harness 持久化 Session 日志的只追加投影——原生 user/assistant/tool/model 事件会自动同步；导航后先读 `context`，不要重复 append 普通轮次；仅用 `append` 记录明确的自定义 entry，从历史节点分叉且不修改旧节点。`context` 与 `session` 返回的 `surface` 字段报告当前表面模式（`native`、`stock` 或 `projection`）。
+##### SessionTree 指引
+
+```markdown
+SessionTree is the append-only projection of this agent's durable Harness Session log. Native user, assistant, tool, and model-context events are synchronized automatically: never duplicate ordinary turns with operation 'append'. Before answering after navigation, call session_tree with operation 'context' and treat its root-to-cursor messages as the active branch context. Use 'append' only for an explicit custom tree entry not already recorded by Harness. To explore an alternative, call 'fork' or 'branch' with a historical nodeId and branch name (or 'branch.summary' to record a summary); old nodes are never modified or deleted. Use 'branches' and 'tree' to inspect topology, and 'snapshot.save'/'snapshot.load' for explicit export or full-tree restore. All operations report failures as {ok:false,error:{code,message}}. Depending on the Harness build, jump/fork switch the model-visible history either through the native selected-surface API or through an official replace-surface emulation; when neither is available the tree is projection-only. The surface field reported by 'context' and 'session' states the active mode: native, stock, or projection.
+```
+
+#### Token 影响
+
+本插件提示注册在作用域内时，每次请求的固定小成本输入，外加每次 `context` 调用返回的 JSON。
+
+#### KV 缓存影响
+
+在插件作用域与指引文本不变时前缀稳定。`context` 结果是动态输出，不进入可复用前缀。
+
+### 工具 schema 与结果
+
+#### 模型看到什么
+
+生成的 [`session_tree` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-session-tree)（一个 `operation` 判别字段加 JSON 载荷字段）。成功结果是紧凑 JSON 信封；失败操作返回 `{ok: false, error: {code, message}}` 而不是抛错。
+
+#### Token 影响
+
+固定 schema 成本加每次调用一个紧凑结果。
+
+#### KV 缓存影响
+
+定义与可见性不变时 schema 前缀稳定。调用与结果追加在可复用请求前缀之后。
+
+## 已知限制与待办
+
+- **原生事件持久化**——每次实时同步都会从 Harness Session 事件日志重建树；显式快照用于整树导出与恢复，原生模型 surface 跟随活动叶子。
+- **补丁集成与官方 Harness**——补丁集成持久化 `session-tree/*` 标记并使用 selected-surface API。官方 Bundle 在光标移动时追加官方 `replace` surface 事件，并把分支元数据保存到 `$DSH_HOME/storages/session-tree/<sessionId>.json`。
+- **存储是进程级**——进程重启后，会在所属 Agent 恢复为实时状态时从持久 Session 事件重建树；官方 Bundle 还会在所属 Agent 下一次 pre-step 前恢复 sidecar。

package/lib/index.js

@@ -0,0 +1,491 @@
+// packages/extensions/tool-session-tree/src/index.ts
+import { SessionId as toSessionId } from "@deepseek-ai/dsh-session";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { appendSessionTreeEvent, applyTreeCursorToSession, isSessionTreeRestoreEvent, persistSessionTree, SessionTree, sessionTreeStore, sessionTreeSurfaceMode, supportsDurableSessionTreeEvents, syncSessionTree } from "@robiteame/dsh-pi-agent-session-tree";
+var name = "tool-session-tree";
+var inject = ["tools", "systemPrompt", "commands", "agents"];
+var SESSION_TREE_PROMPT = "SessionTree is the append-only projection of this agent's durable Harness Session log. Native user, assistant, tool, and model-context events are synchronized automatically: never duplicate ordinary turns with operation 'append'. Before answering after navigation, call session_tree with operation 'context' and treat its root-to-cursor messages as the active branch context. Use 'append' only for an explicit custom tree entry not already recorded by Harness. To explore an alternative, call 'fork' or 'branch' with a historical nodeId and branch name (or 'branch.summary' to record a summary); old nodes are never modified or deleted. Use 'branches' and 'tree' to inspect topology, and 'snapshot.save'/'snapshot.load' for explicit export or full-tree restore. All operations report failures as {ok:false,error:{code,message}}. Depending on the Harness build, jump/fork switch the model-visible history either through the native selected-surface API or through an official replace-surface emulation; when neither is available the tree is projection-only. The surface field reported by 'context' and 'session' states the active mode: native, stock, or projection.";
+function apply(ctx) {
+  ctx.systemPrompt.section({ name: "plugin:pi_agent_session_tree", order: 120, text: SESSION_TREE_PROMPT });
+  ctx.tools.register(defineTool({
+    name: "session_tree",
+    description: "Inspect and navigate the append-only tree projected from the durable Harness Session log. Native user/assistant/tool/model events synchronize automatically; use append only for an explicit custom entry, context to read the active cursor path, fork or branch from a historical node without deleting old history, clone the active path into an independent Harness session, and snapshot.save/snapshot.load for explicit export or restore.",
+    parameters: {
+      operation: { type: "string", required: true },
+      sessionId: { type: "string" },
+      nodeId: { type: "string" },
+      branch: { type: "string" },
+      summary: { type: "string" },
+      message: { type: "json" },
+      snapshot: { type: "json" },
+      metadata: { type: "json" },
+      targetSessionId: { type: "string" },
+      content: { type: "json" },
+      model: { type: "string" },
+      usage: { type: "json" },
+      cost: { type: "number" },
+      error: { type: "string" }
+    },
+    output: {
+      schema: { type: "json" },
+      render: (_args, value) => [{ type: "text", text: JSON.stringify(value, null, 2) }]
+    },
+    async execute(args, exec) {
+      try {
+        return await runToolOperation(ctx, args, exec);
+      } catch (error) {
+        return {
+          ok: false,
+          error: { code: "INVALID_ARGUMENT", message: error instanceof Error ? error.message : "invalid request" }
+        };
+      }
+    }
+  }));
+  ctx.commands.register({
+    name: "tree",
+    description: "Open or refresh the right-sidebar session tree",
+    handler: (invocation) => runTreeCommand(ctx, invocation)
+  });
+  ctx.commands.register({ name: "fork", description: "Fork the selected session-tree node", handler: (invocation) => runForkCommand(invocation) });
+  ctx.commands.register({ name: "clone", description: "Clone the selected session-tree node into a new Harness session", handler: (invocation) => runCloneCommand(ctx, invocation) });
+  ctx.commands.register({ name: "session", description: "Show current session tree status", handler: (invocation) => runSessionCommand(invocation) });
+}
+async function runToolOperation(ctx, args, exec) {
+  if (exec.agent === void 0) {
+    return { ok: false, error: { code: "INVALID_ARGUMENT", message: "session_tree requires an agent-backed session" } };
+  }
+  const sessionId = args.sessionId ?? exec.agent.session.id;
+  const isOwnSession = sessionId === exec.agent.session.id;
+  if (isOwnSession) syncSessionTree(exec.agent);
+  if (args.operation !== "sessions" && args.operation !== "clone" && !isOwnSession) {
+    return { ok: false, error: { code: "INVALID_ARGUMENT", message: "session_tree can only modify the calling agent session" } };
+  }
+  if (args.operation === "clone" && args.targetSessionId === void 0) {
+    return { ok: false, error: { code: "INVALID_ARGUMENT", message: "targetSessionId is required" } };
+  }
+  switch (args.operation) {
+    case "create": {
+      const tree2 = sessionTreeStore.get(sessionId) ?? sessionTreeStore.create(sessionId);
+      return { ok: true, value: { sessionId: tree2.sessionId } };
+    }
+    case "sessions":
+      return { ok: true, value: sessionTreeStore.list() };
+    case "clone": {
+      if (args.targetSessionId === void 0) return { ok: false, error: { code: "INVALID_ARGUMENT", message: "targetSessionId is required" } };
+      if (sessionId !== exec.agent.session.id) return { ok: false, error: { code: "INVALID_ARGUMENT", message: "clone must target the calling agent session" } };
+      return cloneActiveSession(ctx, exec.agent, args.targetSessionId);
+    }
+    case "snapshot.load": {
+      if (args.snapshot === void 0) {
+        return { ok: false, error: { code: "INVALID_ARGUMENT", message: "snapshot is required" } };
+      }
+      const snapshot = args.snapshot;
+      if (snapshot.sessionId !== sessionId) {
+        return { ok: false, error: { code: "INVALID_SNAPSHOT", message: `snapshot session '${snapshot.sessionId}' does not match the calling session '${sessionId}'` } };
+      }
+      if (sessionId !== exec.agent.session.id) return { ok: false, error: { code: "INVALID_ARGUMENT", message: "snapshot.load requires the calling agent session" } };
+      const candidate = newSessionTreeFromSnapshot(sessionId, snapshot);
+      if (!candidate.ok) return { ok: false, error: { code: "INVALID_SNAPSHOT", message: candidate.error } };
+      const event = appendSessionTreeEvent(exec.agent.session, "session-tree/snapshot", { snapshot });
+      if (event !== void 0) candidate.value.markSessionEventSeq(event.seq);
+      sessionTreeStore.replace(sessionId, candidate.value);
+      applyTreeCursorToSession(exec.agent, candidate.value);
+      persistSessionTree(candidate.value);
+      return { ok: true, value: { sessionId } };
+    }
+    default:
+      break;
+  }
+  const required = sessionTreeStore.require(sessionId);
+  if (!required.ok) return required;
+  const tree = required.value;
+  switch (args.operation) {
+    case "append": {
+      if (args.message === void 0) {
+        return { ok: false, error: { code: "INVALID_ARGUMENT", message: "message is required" } };
+      }
+      const request = args.message;
+      if (typeof request.role !== "string" || typeof request.content !== "string") {
+        return { ok: false, error: { code: "INVALID_ARGUMENT", message: "message.role and message.content are required" } };
+      }
+      const checkpoint = tree.checkpoint();
+      const appended = tree.append(
+        {
+          role: request.role,
+          content: request.content,
+          ...request.name === void 0 ? {} : { name: request.name },
+          ...request.toolCallId === void 0 ? {} : { toolCallId: request.toolCallId }
+        },
+        {
+          ...args.branch === void 0 ? {} : { branch: args.branch },
+          ...args.summary === void 0 ? {} : { summary: args.summary },
+          ...args.metadata === void 0 ? {} : { metadata: args.metadata },
+          ...args.content === void 0 ? {} : { content: args.content },
+          ...args.model === void 0 ? {} : { model: args.model },
+          ...args.usage === void 0 ? {} : { usage: args.usage },
+          ...args.cost === void 0 ? {} : { cost: args.cost },
+          ...args.error === void 0 ? {} : { error: args.error }
+        }
+      );
+      if (appended.ok && sessionId === exec.agent.session.id) {
+        try {
+          const event = appendSessionTreeEvent(exec.agent.session, "session-tree/node", { node: appended.value });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          persistSessionTree(tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return appended;
+    }
+    case "list":
+      return { ok: true, value: tree.list() };
+    case "branches":
+      return { ok: true, value: tree.branches() };
+    case "tree":
+      return { ok: true, value: tree.view() };
+    case "session":
+      return { ok: true, value: { ...tree.info(), surface: sessionTreeSurfaceMode(exec.agent.session) } };
+    case "jump": {
+      const checkpoint = tree.checkpoint();
+      const moved = tree.jump(args.nodeId ?? null);
+      if (moved.ok && sessionId === exec.agent.session.id) {
+        try {
+          const event = appendSessionTreeEvent(exec.agent.session, "session-tree/cursor", { nodeId: args.nodeId ?? null });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          if (args.nodeId != null) {
+            const selected = tree.select(args.nodeId);
+            if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+            const selection = appendSessionTreeEvent(exec.agent.session, "session-tree/selection", { nodeId: args.nodeId });
+            if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+          }
+          applyTreeCursorToSession(exec.agent, tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return moved;
+    }
+    case "fork": {
+      if (args.nodeId === void 0) return { ok: false, error: { code: "INVALID_ARGUMENT", message: "nodeId is required" } };
+      const checkpoint = tree.checkpoint();
+      const forked = tree.fork(args.nodeId, args.branch);
+      if (forked.ok && sessionId === exec.agent.session.id) {
+        try {
+          const selected = tree.select(args.nodeId);
+          if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+          const event = appendSessionTreeEvent(exec.agent.session, "session-tree/branch", { nodeId: args.nodeId, branch: forked.value.branch });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          const selection = appendSessionTreeEvent(exec.agent.session, "session-tree/selection", { nodeId: args.nodeId });
+          if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+          applyTreeCursorToSession(exec.agent, tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return forked;
+    }
+    case "context":
+      return { ok: true, value: { cursor: tree.cursor, surface: sessionTreeSurfaceMode(exec.agent.session), messages: tree.messages(args.nodeId ?? tree.cursor) } };
+    case "branch": {
+      if (args.nodeId === void 0 || args.branch === void 0) {
+        return { ok: false, error: { code: "INVALID_ARGUMENT", message: "nodeId and branch are required" } };
+      }
+      const checkpoint = tree.checkpoint();
+      const branched = tree.branch(args.nodeId, args.branch);
+      if (branched.ok && sessionId === exec.agent.session.id) {
+        try {
+          const selected = tree.select(args.nodeId);
+          if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+          const event = appendSessionTreeEvent(exec.agent.session, "session-tree/branch", { nodeId: args.nodeId, branch: args.branch });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          const selection = appendSessionTreeEvent(exec.agent.session, "session-tree/selection", { nodeId: args.nodeId });
+          if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+          applyTreeCursorToSession(exec.agent, tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return branched;
+    }
+    case "branch.summary": {
+      if (args.nodeId === void 0 || args.summary === void 0) {
+        return { ok: false, error: { code: "INVALID_ARGUMENT", message: "nodeId and summary are required" } };
+      }
+      const checkpoint = tree.checkpoint();
+      const summarized = tree.branchWithSummary(args.nodeId, args.summary);
+      if (summarized.ok && sessionId === exec.agent.session.id) {
+        try {
+          const event = appendSessionTreeEvent(exec.agent.session, "session-tree/node", { node: summarized.value });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          applyTreeCursorToSession(exec.agent, tree);
+          persistSessionTree(tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return summarized;
+    }
+    case "snapshot.save":
+      return { ok: true, value: tree.snapshot() };
+    default:
+      return { ok: false, error: { code: "INVALID_ARGUMENT", message: `unknown operation '${args.operation}'` } };
+  }
+}
+function runForkCommand(invocation) {
+  const [branch = `fork-${Date.now().toString(36)}`] = invocation.rawInput.trim().split(/\s+/u).filter(Boolean);
+  const tree = syncSessionTree(invocation.agent);
+  if (tree.selectedNode === null) return errorCommand("\u8BF7\u5148\u5728\u53F3\u4FA7\u4F1A\u8BDD\u6811\u9009\u4E2D\u76EE\u6807\u8282\u70B9");
+  const checkpoint = tree.checkpoint();
+  const forked = tree.fork(tree.selectedNode, branch);
+  if (!forked.ok) return jsonCommand(forked);
+  try {
+    const selected = tree.select(forked.value.cursor);
+    if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+    const event = appendSessionTreeEvent(invocation.agent.session, "session-tree/branch", { nodeId: forked.value.cursor, branch: forked.value.branch });
+    if (event !== void 0) tree.markSessionEventSeq(event.seq);
+    const selection = appendSessionTreeEvent(invocation.agent.session, "session-tree/selection", { nodeId: forked.value.cursor });
+    if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+    applyTreeCursorToSession(invocation.agent, tree);
+  } catch (error) {
+    tree.rollback(checkpoint);
+    throw error;
+  }
+  return jsonCommand(forked);
+}
+async function cloneActiveSession(ctx, agent, target, nodeId) {
+  const tree = syncSessionTree(agent);
+  const focusId = nodeId ?? tree.cursor;
+  const seed = agent.session.events.filter((event) => !isSessionTreeRestoreEvent(event)).map((event, index) => {
+    const record = JSON.parse(JSON.stringify(event));
+    if (record.type === "session-tree/snapshot") {
+      record.data = { ...record.data, snapshot: { ...record.data.snapshot, sessionId: toSessionId(target) } };
+    }
+    record.seq = index;
+    return record;
+  });
+  const seedTime = Date.now();
+  if (supportsDurableSessionTreeEvents(agent.session)) {
+    seed.push({
+      type: "session-tree/cursor",
+      seq: seed.length,
+      time: seedTime + seed.length,
+      data: { nodeId: focusId }
+    });
+    if (focusId !== null) {
+      seed.push({
+        type: "session-tree/selection",
+        seq: seed.length,
+        time: seedTime + seed.length,
+        data: { nodeId: focusId }
+      });
+    }
+  }
+  seedCloneTree(toSessionId(target), tree, focusId, Math.max(seed.length - 1, 0));
+  try {
+    await ctx.agents.create({
+      sessionId: toSessionId(target),
+      seed,
+      meta: { parentSession: agent.session.id, seedLength: seed.length },
+      agentOptions: agent.options
+    });
+  } catch (error) {
+    if (!(error instanceof Error) || !error.message.includes("no agent factory registered")) {
+      throw error;
+    }
+  }
+  return { ok: true, value: { sessionId: target } };
+}
+function seedCloneTree(targetId, source, focusId, nativeEventSeq) {
+  const snapshot = source.snapshot();
+  const focusNode = focusId === null ? void 0 : snapshot.nodes.find((node) => node.nodeId === focusId);
+  const activeBranch = focusNode?.branch ?? snapshot.activeBranch;
+  const branchHeads = { ...snapshot.branchHeads };
+  if (focusNode !== void 0) branchHeads[focusNode.branch] = focusNode.nodeId;
+  const clonedTree = new SessionTree(targetId, {
+    version: 1,
+    sessionId: targetId,
+    cursor: focusId,
+    activeBranch,
+    ...focusId === null && Object.keys(branchHeads).length === 0 ? {} : { branchHeads },
+    selectedNodeId: focusId,
+    ...nativeEventSeq < 0 ? {} : { nativeEventSeq },
+    nodes: snapshot.nodes
+  });
+  sessionTreeStore.replace(targetId, clonedTree);
+  persistSessionTree(clonedTree);
+}
+function newSessionTreeFromSnapshot(sessionId, snapshot) {
+  try {
+    return { ok: true, value: new SessionTree(sessionId, snapshot) };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "invalid snapshot" };
+  }
+}
+async function runCloneCommand(ctx, invocation) {
+  const tree = syncSessionTree(invocation.agent);
+  if (tree.selectedNode === null) return errorCommand("\u8BF7\u5148\u5728\u53F3\u4FA7\u4F1A\u8BDD\u6811\u9009\u4E2D\u76EE\u6807\u8282\u70B9");
+  const target = `${invocation.agent.session.id}-clone-${Date.now().toString(36)}`;
+  try {
+    return jsonCommand(await cloneActiveSession(ctx, invocation.agent, target, tree.selectedNode));
+  } catch (error) {
+    return { kind: "error", text: JSON.stringify({ ok: false, error: { code: "INVALID_ARGUMENT", message: error instanceof Error ? error.message : "clone failed" } }) };
+  }
+}
+function runSessionCommand(invocation) {
+  return jsonCommand({ ok: true, value: { ...syncSessionTree(invocation.agent).info(), surface: sessionTreeSurfaceMode(invocation.agent.session) } });
+}
+function jsonCommand(value, map) {
+  const result = map === void 0 ? value : value.ok ? map(value.value) : value;
+  const failed = typeof result === "object" && result !== null && result.ok === false;
+  return { kind: failed ? "error" : "success", text: JSON.stringify(result) };
+}
+function errorCommand(message) {
+  return { kind: "error", text: JSON.stringify({ ok: false, error: { code: "INVALID_ARGUMENT", message } }) };
+}
+async function runTreeCommand(ctx, invocation) {
+  const parts = invocation.rawInput.trim().split(/\s+/u).filter(Boolean);
+  const sessionId = invocation.agent.session.id;
+  const tree = syncSessionTree(invocation.agent);
+  const surface = sessionTreeSurfaceMode(invocation.agent.session);
+  const [head, ...rest] = parts;
+  const action = head === "snapshot" ? `snapshot.${rest[0] ?? ""}` : head ?? "list";
+  const json = (value) => {
+    const failed = typeof value === "object" && value !== null && value.ok === false;
+    return { kind: failed ? "error" : "success", text: JSON.stringify(value) };
+  };
+  switch (action) {
+    // Spreading the node array would collapse it into numeric keys; keep it a
+    // real array under `nodes` so JSON consumers can iterate it.
+    case "list":
+      return json({ ok: true, value: { nodes: tree.list(), surface } });
+    case "branches":
+      return json({ ok: true, value: tree.branches() });
+    case "tree":
+      return json({ ok: true, value: { ...tree.view(), surface } });
+    case "session":
+      return json({ ok: true, value: { ...tree.info(), surface } });
+    case "fork": {
+      if (tree.selectedNode === null) return json({ ok: false, error: { code: "INVALID_ARGUMENT", message: "\u8BF7\u5148\u5728\u53F3\u4FA7\u4F1A\u8BDD\u6811\u9009\u4E2D\u76EE\u6807\u8282\u70B9" } });
+      const checkpoint = tree.checkpoint();
+      const result = tree.fork(tree.selectedNode, rest[0] ?? "fork");
+      if (result.ok) {
+        try {
+          const selected = tree.select(result.value.cursor);
+          if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+          const event = appendSessionTreeEvent(invocation.agent.session, "session-tree/branch", { nodeId: result.value.cursor, branch: result.value.branch });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          const selection = appendSessionTreeEvent(invocation.agent.session, "session-tree/selection", { nodeId: result.value.cursor });
+          if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+          applyTreeCursorToSession(invocation.agent, tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return json(result);
+    }
+    case "clone": {
+      if (tree.selectedNode === null) return json({ ok: false, error: { code: "INVALID_ARGUMENT", message: "\u8BF7\u5148\u5728\u53F3\u4FA7\u4F1A\u8BDD\u6811\u9009\u4E2D\u76EE\u6807\u8282\u70B9" } });
+      const target = rest[0] ?? `${sessionId}-clone-${Date.now().toString(36)}`;
+      try {
+        return json(await cloneActiveSession(ctx, invocation.agent, target, tree.selectedNode));
+      } catch (error) {
+        return json({ ok: false, error: { code: "INVALID_ARGUMENT", message: error instanceof Error ? error.message : "clone failed" } });
+      }
+    }
+    case "context":
+      return json({ ok: true, value: { cursor: tree.cursor, selectedNodeId: tree.selectedNode, surface, messages: tree.messages(tree.selectedNode ?? tree.cursor) } });
+    case "jump": {
+      const nodeId = rest[0] ?? tree.selectedNode;
+      if (nodeId === null) return json({ ok: false, error: { code: "INVALID_ARGUMENT", message: "\u8BF7\u5148\u5728\u53F3\u4FA7\u4F1A\u8BDD\u6811\u9009\u4E2D\u76EE\u6807\u8282\u70B9" } });
+      const checkpoint = tree.checkpoint();
+      const result = tree.jump(nodeId);
+      if (result.ok) {
+        try {
+          const event = appendSessionTreeEvent(invocation.agent.session, "session-tree/cursor", { nodeId });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          const selected = tree.select(nodeId);
+          if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+          const selection = appendSessionTreeEvent(invocation.agent.session, "session-tree/selection", { nodeId });
+          if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+          applyTreeCursorToSession(invocation.agent, tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return json(result);
+    }
+    case "branch": {
+      const nodeId = tree.selectedNode ?? "";
+      const branch = rest[0] ?? "fork";
+      const checkpoint = tree.checkpoint();
+      const result = tree.branch(nodeId, branch);
+      if (result.ok) {
+        try {
+          const selected = tree.select(nodeId);
+          if (!selected.ok) throw new Error(`${selected.error.code}: ${selected.error.message}`);
+          const event = appendSessionTreeEvent(invocation.agent.session, "session-tree/branch", { nodeId, branch });
+          if (event !== void 0) tree.markSessionEventSeq(event.seq);
+          const selection = appendSessionTreeEvent(invocation.agent.session, "session-tree/selection", { nodeId });
+          if (selection !== void 0) tree.markSessionEventSeq(selection.seq);
+          applyTreeCursorToSession(invocation.agent, tree);
+        } catch (error) {
+          tree.rollback(checkpoint);
+          throw error;
+        }
+      }
+      return json(result);
+    }
+    case "snapshot.save":
+      return json({ ok: true, value: tree.snapshot() });
+    case "snapshot.load": {
+      const raw = rest.slice(1).join(" ").trim();
+      if (raw === "") {
+        return { kind: "error", text: JSON.stringify({ ok: false, error: { code: "INVALID_ARGUMENT", message: "snapshot JSON is required" } }) };
+      }
+      try {
+        const snapshot = JSON.parse(raw);
+        if (snapshot.sessionId !== sessionId) {
+          return json({ ok: false, error: { code: "INVALID_SNAPSHOT", message: `snapshot session '${snapshot.sessionId}' does not match the calling session '${sessionId}'` } });
+        }
+        const candidate = new SessionTree(sessionId, snapshot);
+        try {
+          const event = appendSessionTreeEvent(invocation.agent.session, "session-tree/snapshot", { snapshot });
+          if (event !== void 0) candidate.markSessionEventSeq(event.seq);
+          sessionTreeStore.replace(sessionId, candidate);
+          applyTreeCursorToSession(invocation.agent, candidate);
+          persistSessionTree(candidate);
+          return json({ ok: true, value: { sessionId } });
+        } catch (error) {
+          throw error;
+        }
+      } catch (error) {
+        return { kind: "error", text: JSON.stringify({ ok: false, error: { code: "INVALID_SNAPSHOT", message: error instanceof Error ? error.message : "invalid snapshot JSON" } }) };
+      }
+    }
+    default:
+      return {
+        kind: "error",
+        text: JSON.stringify({
+          ok: false,
+          error: {
+            code: "INVALID_ARGUMENT",
+            message: "Usage: /tree [list|branches|tree|context|jump <nodeId>|branch <nodeId> <name>|snapshot save|snapshot load <json>]"
+          }
+        })
+      };
+  }
+}
+export {
+  SESSION_TREE_PROMPT,
+  apply,
+  inject,
+  name
+};

package/lib/invariant.js

@@ -0,0 +1,12 @@
+// packages/extensions/tool-session-tree/src/invariant.ts
+var PACKAGE_NAME = "@robiteame/dsh-tool-session-tree";
+var name = "tool-session-tree-invariant";
+var inject = ["invariants"];
+var install = () => {
+};
+var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+export {
+  apply,
+  inject,
+  name
+};

package/lib/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Model-facing tool and slash-command companion of the session-tree service:
+ * the `session_tree` tool, the `/tree` command family, and a system-prompt
+ * section. All state lives in the shared `sessionTreeStore` from
+ * `@robiteame/dsh-pi-agent-session-tree`, so the model, the command line,
+ * and the browser panel observe the same trees.
+ *
+ * Design notes
+ * - Harness Session events remain the durable history source. The prompt tells
+ *   the model to read the active branch with `context`, never duplicate native
+ *   turns with `append`, and never edit historical nodes.
+ * - Every operation returns the standard `{ok, value}|{ok:false,error}` JSON
+ *   envelope; a thrown body also settles as that envelope, so tool results
+ *   are always lossless JSON.
+ *
+ * @module @robiteame/dsh-tool-session-tree
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "tool-session-tree";
+export declare const inject: string[];
+/** System-prompt fragment steering the agent to the tree as its only history. */
+export declare const SESSION_TREE_PROMPT = "SessionTree is the append-only projection of this agent's durable Harness Session log. Native user, assistant, tool, and model-context events are synchronized automatically: never duplicate ordinary turns with operation 'append'. Before answering after navigation, call session_tree with operation 'context' and treat its root-to-cursor messages as the active branch context. Use 'append' only for an explicit custom tree entry not already recorded by Harness. To explore an alternative, call 'fork' or 'branch' with a historical nodeId and branch name (or 'branch.summary' to record a summary); old nodes are never modified or deleted. Use 'branches' and 'tree' to inspect topology, and 'snapshot.save'/'snapshot.load' for explicit export or full-tree restore. All operations report failures as {ok:false,error:{code,message}}. Depending on the Harness build, jump/fork switch the model-visible history either through the native selected-surface API or through an official replace-surface emulation; when neither is available the tree is projection-only. The surface field reported by 'context' and 'session' states the active mode: native, stock, or projection.";
+/** Register the tool, the command family, and the prompt section. */
+export declare function apply(ctx: Context): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@robiteame/dsh-tool-session-tree`.
+ * @module @robiteame/dsh-tool-session-tree/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-session-tree-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@robiteame/dsh-tool-session-tree",
+  "description": "session_tree tool, /tree command family, and system-prompt section over the shared append-only session-tree store",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robiteame/dsh-session-tree-extension.git",
+    "directory": "packages/extensions/tool-session-tree"
+  },
+  "bugs": {
+    "url": "https://github.com/robiteame/dsh-session-tree-extension/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build.mjs tool",
+    "watch": "node ../../../scripts/build.mjs tool"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-commands": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.3",
+    "@robiteame/dsh-pi-agent-session-tree": "^0.1.0"
+  },
+  "devDependencies": {
+    "@robiteame/dsh-pi-agent-session-tree": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}