@elinpf/dsh-ops-tool-trace 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-tool-trace"
+description:
+  zh: "运维模式调查树工具 — 用扩散-收敛树替代 todo_write"
+  en: "Investigation tree tool for ops mode — replaces todo_write with a diverge-converge tree"

package/README.md

@@ -0,0 +1,46 @@
+# @elinpf/dsh-ops-tool-trace
+
+An investigation tree tool for DeepSeek Harness ops mode — replaces `todo_write` with a diverge-converge tree of steps, milestones, dead ends, and a resolved terminal.
+
+## What it does
+
+Agent-driven investigation tracking: the agent maintains a tree of investigation steps via the `todo_tree` model tool. Each call appends an incremental event to the session log; a session projection folds these into the current tree state; the client renders a git-graph-style flat list with colored lanes, expandable rows, and status glyphs.
+
+- **8 actions**: `create_tree`, `add_step`, `add_milestone`, `start`, `complete`, `abandon`, `resolve`, `note`
+- **6 statuses**: `goal`, `pending`, `in_progress`, `done`, `dead_end`, `resolved`
+- **Dead ends are not deleted** — they stay on the tree as part of the exploration record
+- **Branch** with `branch=true` to explore side paths in parallel lanes
+- Every call returns the full tree + a status summary (advisor, not gatekeeper)
+
+## Installation
+
+Add to `dsh-web-app` dependencies and reference in the ops preset's `agent.cordis.yml`:
+
+```yaml
+- id: tool-ops-trace
+  name: '@elinpf/dsh-ops-tool-trace'
+```
+
+## Model Experience
+
+### todo_tree tool
+
+#### What the model sees
+
+A tool description explaining the 8 actions and when to use each. A system prompt section with usage guidance.
+
+#### Token effect
+
+Tool schema + description (~200 tokens). System prompt section (~300 tokens).
+
+#### KV Cache effect
+
+Stable across turns — tool description and prompt section are static.
+
+## Known Limitations and Deferred Work
+
+- No cross-session continuity (v1: one tree per session)
+- No human editing (pure agent-driven)
+- Lane/depth computed client-side (layout is derived, not stored)
+- Subagents cannot directly write to the tree — main agent must relay their results
+- No replay/timeline scrub UI (events are in the session log, but no dedicated timeline view)

package/README.zh.md

@@ -0,0 +1,46 @@
+# @elinpf/dsh-ops-tool-trace
+
+运维模式调查树工具 — 用扩散-收敛树替代 `todo_write`，记录步骤、里程碑、死胡同和已解决终端。
+
+## 功能
+
+Agent 驱动的调查跟踪：agent 通过 `todo_tree` 模型工具维护调查步骤树。每次调用向会话日志追加增量事件；session projection 将事件 fold 成当前树状态；client 渲染 git-graph 风格的扁平列表，带彩色轨道线、可展开行和状态图标。
+
+- **8 个动作**：`create_tree`、`add_step`、`add_milestone`、`start`、`complete`、`abandon`、`resolve`、`note`
+- **6 种状态**：`goal`、`pending`、`in_progress`、`done`、`dead_end`、`resolved`
+- **死胡同不删除** — 保留在树上作为探索记录
+- **分支**：`branch=true` 在并行轨道探索侧路径
+- 每次调用返回完整树 + 状态摘要（顾问，非守门员）
+
+## 安装
+
+添加到 `dsh-web-app` 依赖，并在 ops preset 的 `agent.cordis.yml` 中引用：
+
+```yaml
+- id: tool-ops-trace
+  name: '@elinpf/dsh-ops-tool-trace'
+```
+
+## 模型体验
+
+### todo_tree 工具
+
+#### 模型看到什么
+
+工具描述（8 个动作及使用时机）+ 系统提示词 section（使用指南）。
+
+#### Token 影响
+
+工具 schema + 描述（约 200 token）+ 系统提示词 section（约 300 token）。
+
+#### KV Cache 影响
+
+跨轮次稳定 — 工具描述和提示词 section 是静态的。
+
+## 已知限制和待办事项
+
+- 无跨会话连续性（v1：一个会话一棵树）
+- 无人工编辑（纯 agent 驱动）
+- lane/depth 在 client 侧计算（布局是派生的，不存储）
+- 子 agent 不能直接写树 — 主 agent 需代为操作
+- 无回放/时间轴 UI（事件在会话日志中，但无专门时间线视图）

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/doctrine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The trace doctrine — one home per sentence.
+ *
+ * The same handful of ideas (what the tree is, the trigger-node rule, the
+ * hypothesis form, where the full doc lives) used to be re-phrased in every
+ * prompt surface: the tool description, the parameter descriptions, the
+ * system-prompt core, the help text, and the reminder messages. They drifted
+ * in wording if not in content. Now each canonical sentence lives here once
+ * and the surfaces compose from it — same words everywhere, so the model
+ * gets one consistent vocabulary to anchor on.
+ *
+ * Surfaces deliberately keep their own granularity: the tool description is
+ * a one-liner, the system prompt carries the minimal core, and HELP_TEXT is
+ * the full reference. Progressive disclosure is the point; duplication is not.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/doctrine
+ */
+/** What the tree is, in one line. */
+export declare const TREE_ONE_LINER = "\u7EF4\u62A4\u4E8B\u4EF6\u6392\u67E5\u7684\u8C03\u67E5\u6811: goal \u2192 milestone(\u5F85\u9A8C\u8BC1\u5047\u8BBE) \u2192 step(\u9A8C\u8BC1\u52A8\u4F5C)";
+/** The question behind every parent_id decision. Also quoted verbatim by the
+ *  nesting reminder. */
+export declare const TRIGGER_NODE_QUESTION = "\u6211\u4E3A\u4EC0\u4E48\u73B0\u5728\u8981\u505A\u8FD9\u4E2A\u52A8\u4F5C?";
+/** The trigger-node mapping: where a new node hangs, by what triggered it. */
+export declare const TRIGGER_NODE_MAPPING = "\u8DDF\u8FDB\u67D0 step \u7684\u53D1\u73B0 \u2192 \u6302\u90A3\u4E2A step; \u9A8C\u8BC1\u67D0\u5047\u8BBE \u2192 \u6302\u8BE5 milestone; \u9876\u5C42\u5047\u8BBE \u2192 \"goal\"";
+/** The full trigger-node rule, one line (system-prompt core + parent_id
+ *  parameter description). */
+export declare const TRIGGER_NODE_RULE = "parent_id \u7684\u552F\u4E00\u89C4\u5219 \u2014 \u6211\u4E3A\u4EC0\u4E48\u73B0\u5728\u8981\u505A\u8FD9\u4E2A\u52A8\u4F5C? \u8DDF\u8FDB\u67D0 step \u7684\u53D1\u73B0 \u2192 \u6302\u90A3\u4E2A step; \u9A8C\u8BC1\u67D0\u5047\u8BBE \u2192 \u6302\u8BE5 milestone; \u9876\u5C42\u5047\u8BBE \u2192 \"goal\"\u3002";
+/** A milestone must be writable in this form, or it is not a hypothesis. */
+export declare const HYPOTHESIS_FORM = "\"\u6211\u6000\u7591 X, \u56E0\u4E3A\u770B\u5230\u4E86 Y\"";
+/**
+ * Hard-gate error for resolve on the goal while nodes are still undecided
+ * (not done / not dead_end). Lists the undecided nodes and points at the
+ * two ways forward: decide them (complete/abandon), or force — the explicit
+ * escape hatch for abandoning an investigation mid-way.
+ */
+export declare function resolveGateError(undecided: Array<{
+    id: string;
+    status: string;
+}>): string;
+/** Where the full documentation lives. */
+export declare const HELP_POINTER = "\u5B8C\u6574\u7528\u6CD5\u4E0E\u7EAA\u5F8B: \u8C03 `trace` action=help\u3002";
+/**
+ * Soft hint for add_step: the parent is a milestone that already has
+ * completed steps with findings, so the new step may belong under one of
+ * those steps (drill-down) instead of flat under the milestone. A hint,
+ * never a rejection — flat-hanging is sometimes right. Fires ONCE per tree
+ * (latched in the tool); the pre-step nesting reminder is the backstop.
+ */
+export declare function milestoneFollowUpHint(doneStepIds: string[]): string;
+/** One-liner for the tool registry description. */
+export declare const TOOL_DESCRIPTION = "\u7EF4\u62A4\u4E8B\u4EF6\u6392\u67E5\u7684\u8C03\u67E5\u6811: goal \u2192 milestone(\u5F85\u9A8C\u8BC1\u5047\u8BBE) \u2192 step(\u9A8C\u8BC1\u52A8\u4F5C)\u3002\u6BCF\u4E2A\u8282\u70B9\u7684 parent_id \u662F\u5B83\u7684\u89E6\u53D1\u8282\u70B9\u2014\u2014\u8BA9\u4F60\u6B64\u523B\u60F3\u505A\u8FD9\u4E2A\u52A8\u4F5C\u7684\u90A3\u4E2A\u8282\u70B9\u3002\u5B8C\u6574\u7528\u6CD5\u4E0E\u7EAA\u5F8B: \u8C03 `trace` action=help\u3002";
+/**
+ * Minimal always-on core for the system prompt (registered through
+ * ops-prompts as a methodology section). The full doc is progressively
+ * disclosed through the `help` action; reminders deliver individual rules
+ * just-in-time.
+ */
+export declare const STATIC_PROMPT: string;
+/**
+ * Full usage documentation, progressively disclosed: the system prompt only
+ * carries the minimal core plus a pointer; the model pulls this via
+ * `trace` action=help when it needs the details.
+ */
+export declare const HELP_TEXT: string;
+//# sourceMappingURL=doctrine.d.ts.map

package/lib/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Ops-trace: an investigation tree tool that replaces `todo_write` in the ops preset.
+ *
+ * Agent-driven, append-only event log, tree + unique resolved convergence terminal.
+ * See `.scratch/ops-trace/research/` for the full design.
+ *
+ * @module @elinpf/dsh-ops-tool-trace
+ */
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import type { Context } from '@deepseek-ai/cordis';
+import type { OpsPromptsHandle } from '@elinpf/dsh-ops-prompts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        opsPrompts?: OpsPromptsHandle;
+        sessionProjections?: {
+            register(def: {
+                key: string;
+                schema: unknown;
+                init: () => ForestState | null;
+                apply: (state: ForestState | null, event: FoldEvent) => ForestState | null;
+                view: (state: ForestState | null) => ForestState | null;
+                stateVersion: number;
+            }): () => void;
+            snapshot(session: {
+                id: string;
+            }): {
+                values: {
+                    trace?: ForestState | null;
+                };
+            };
+        };
+    }
+}
+import type { ForestState } from './types.js';
+declare const name = "ops-trace";
+declare const inject: string[];
+/**
+ * Schemastery configuration for the ops-trace tool consumer.
+ */
+declare const Config: z<Schemastery.ObjectS<{
+    /** Idle reminder: nudge after this many steps without a trace update (default 5). */
+    idleReminderGapSteps: z<number, number>;
+    /** Idle reminder backoff ceiling (steps): the refire gap doubles per fire up to this cap (default 40). */
+    idleReminderBackoffCeilingSteps: z<number, number>;
+    /** Nesting reminder: fires when this many steps hang flat under milestones with nothing deeper (default 3). */
+    nestingReminderFlatSteps: z<number, number>;
+}>, Schemastery.ObjectT<{
+    /** Idle reminder: nudge after this many steps without a trace update (default 5). */
+    idleReminderGapSteps: z<number, number>;
+    /** Idle reminder backoff ceiling (steps): the refire gap doubles per fire up to this cap (default 40). */
+    idleReminderBackoffCeilingSteps: z<number, number>;
+    /** Nesting reminder: fires when this many steps hang flat under milestones with nothing deeper (default 3). */
+    nestingReminderFlatSteps: z<number, number>;
+}>>;
+/**
+ * Fold one tool/call event into tree state (pure function, allocation-fresh).
+ * The projection reads tool/call events where name === 'trace' and
+ * parses the arguments JSON to reconstruct the tree.
+ * No custom session event types are needed — tool/call is a known type.
+ */
+/** Minimal event shape that foldEvent reads from the session log. */
+export interface FoldEvent {
+    type: string;
+    data: {
+        name?: string;
+        turn?: number;
+        step?: number;
+        arguments?: string;
+    };
+}
+declare function foldEvent(state: ForestState | null, event: FoldEvent): ForestState | null;
+export declare const treeNodeSchema: zod.ZodObject<{
+    id: zod.ZodString;
+    title: zod.ZodString;
+    status: zod.ZodEnum<{
+        goal: "goal";
+        pending: "pending";
+        in_progress: "in_progress";
+        done: "done";
+        dead_end: "dead_end";
+        resolved: "resolved";
+    }>;
+    parent: zod.ZodNullable<zod.ZodString>;
+    turns: zod.ZodArray<zod.ZodNumber>;
+    summary: zod.ZodNullable<zod.ZodString>;
+    detail: zod.ZodNullable<zod.ZodString>;
+    caused_by: zod.ZodArray<zod.ZodString>;
+}, zod.core.$strip>;
+/**
+ * JSON-schema shape of one node, for the tool's output contract. The third
+ * declaration of the node shape (after the TreeNode interface and
+ * treeNodeSchema above) — its status enum derives from NODE_STATUSES, and
+ * tests/contract.spec.ts asserts all three field sets agree.
+ */
+export declare const treeNodeJsonSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly title: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly required: true;
+            readonly enum: readonly ["goal", "pending", "in_progress", "done", "dead_end", "resolved"];
+        };
+        readonly parent: {
+            readonly required: true;
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+        readonly turns: {
+            readonly type: "array";
+            readonly required: true;
+            readonly items: {
+                readonly type: "number";
+            };
+        };
+        readonly summary: {
+            readonly required: true;
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+        readonly detail: {
+            readonly required: true;
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+        };
+        readonly caused_by: {
+            readonly type: "array";
+            readonly required: true;
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+};
+declare const traceProjectionSchema: zod.ZodUnion<readonly [zod.ZodObject<{
+    trees: zod.ZodArray<zod.ZodObject<{
+        nodes: zod.ZodArray<zod.ZodObject<{
+            id: zod.ZodString;
+            title: zod.ZodString;
+            status: zod.ZodEnum<{
+                goal: "goal";
+                pending: "pending";
+                in_progress: "in_progress";
+                done: "done";
+                dead_end: "dead_end";
+                resolved: "resolved";
+            }>;
+            parent: zod.ZodNullable<zod.ZodString>;
+            turns: zod.ZodArray<zod.ZodNumber>;
+            summary: zod.ZodNullable<zod.ZodString>;
+            detail: zod.ZodNullable<zod.ZodString>;
+            caused_by: zod.ZodArray<zod.ZodString>;
+        }, zod.core.$strip>>;
+        resolved: zod.ZodBoolean;
+    }, zod.core.$strip>>;
+}, zod.core.$strip>, zod.ZodNull]>;
+/**
+ * The shared projection definition, registered host-plane by ops-trace-ui
+ * (the panel's package) and consumed here through snapshots. One home for
+ * key/schema/fold/stateVersion so the two packages can never drift apart.
+ */
+export declare const traceProjection: {
+    key: string;
+    schema: zod.ZodUnion<readonly [zod.ZodObject<{
+        trees: zod.ZodArray<zod.ZodObject<{
+            nodes: zod.ZodArray<zod.ZodObject<{
+                id: zod.ZodString;
+                title: zod.ZodString;
+                status: zod.ZodEnum<{
+                    goal: "goal";
+                    pending: "pending";
+                    in_progress: "in_progress";
+                    done: "done";
+                    dead_end: "dead_end";
+                    resolved: "resolved";
+                }>;
+                parent: zod.ZodNullable<zod.ZodString>;
+                turns: zod.ZodArray<zod.ZodNumber>;
+                summary: zod.ZodNullable<zod.ZodString>;
+                detail: zod.ZodNullable<zod.ZodString>;
+                caused_by: zod.ZodArray<zod.ZodString>;
+            }, zod.core.$strip>>;
+            resolved: zod.ZodBoolean;
+        }, zod.core.$strip>>;
+    }, zod.core.$strip>, zod.ZodNull]>;
+    init: () => ForestState | null;
+    apply: typeof foldEvent;
+    view: (s: ForestState | null) => ForestState | null;
+    stateVersion: number;
+};
+declare function apply(ctx: Context, config: {
+    idleReminderGapSteps: number;
+    idleReminderBackoffCeilingSteps: number;
+    nestingReminderFlatSteps: number;
+}): void;
+export { Config, apply, inject, name, foldEvent, traceProjectionSchema };
+//# sourceMappingURL=index.d.ts.map