@elinpf/dsh-ops-tool-trace 0.1.0

package/lib/invariant.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-trace.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-trace-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+declare const apply: (ctx: any) => Promise<void>;
+export { apply, inject, name };
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.js

@@ -0,0 +1,27 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-trace.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-tool-trace';
+/** Cordis companion plugin name. */
+const name = 'ops-trace-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this tool owns no independent durable shape beyond
+ * the session events it appends. The projection fold is pure and stateless;
+ * accepted mutations are checked by the tool's state-machine validation
+ * before they reach the log, and the fold is idempotent.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+const apply = async (ctx) => {
+    ctx.invariants.register(PACKAGE_NAME, install);
+};
+export { apply, inject, name };
+//# sourceMappingURL=invariant.js.map

package/lib/node-status.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Runtime home of the node-status vocabulary (moved out of types.ts, which is
+ * types-only). The zod projection schema, the tool's output JSON schema, and
+ * the status_filter enum all derive from NODE_STATUSES — one source of truth.
+ *
+ * @module @elinpf/dsh-ops-tool-trace
+ */
+import type { ForestState, TreeState } from './types.js';
+/**
+ * The six node statuses from the state machine — the single source of truth
+ * for the status set.
+ *
+ * - `goal` — a stable target (milestone or final goal); uses dashed connectors
+ * - `pending` — a step not yet started; uses thin dashed connectors
+ * - `in_progress` — actively being worked on
+ * - `done` — completed
+ * - `dead_end` — proven unviable; NOT a terminal state (can re-explore)
+ * - `resolved` — final goal achieved; terminal state
+ */
+export declare const NODE_STATUSES: readonly ["goal", "pending", "in_progress", "done", "dead_end", "resolved"];
+export type NodeStatus = typeof NODE_STATUSES[number];
+/**
+ * The active tree is the last unresolved one, or the last tree if all are resolved.
+ */
+export declare function activeTree(forest: ForestState): TreeState | null;
+//# sourceMappingURL=node-status.d.ts.map

package/lib/reminders.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Reminder rules for the trace tool.
+ *
+ * Before this module existed, each reminder check re-parsed the full session
+ * event history on every pre-step — including JSON-parsing every historical
+ * tool call's arguments — and hand-rolled its own latch map. The latch-reset
+ * infinite loop came from exactly that arrangement: replaying history and
+ * mutating latch state in the same function.
+ *
+ * Now: {@link buildReminderContext} derives a small context once (step
+ * positions from the event log — no argument parsing — and the live tree
+ * from the SessionForestStore, which already owns it), and rules are pure
+ * functions of that context. {@link ReminderLatch} is the single latch
+ * abstraction: a monotonic per-session version with a minimum gap and a
+ * fire cap.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/reminders
+ */
+import type { ForestState, TreeState } from './types.js';
+import type { SessionForestStore } from './session-forests.js';
+/** What a reminder rule sees. Derived once per pre-step, shared by all rules. */
+export interface ReminderContext {
+    sessionId: string;
+    /** Latest step position, encoded as turn * 1000 + step. */
+    currentStep: number;
+    /** Step position of the last trace call; 0 = never called. */
+    lastTraceStep: number;
+    /** The live forest (from the store, not a re-fold). */
+    forest: ForestState;
+    /** The active tree — null when no investigation exists. */
+    tree: TreeState | null;
+}
+/**
+ * Derive the reminder context for one pre-step. Returns null when there is no
+ * session event stream to judge from.
+ */
+export declare function buildReminderContext(agent: unknown, store: SessionForestStore): ReminderContext | null;
+/**
+ * One latch abstraction for all reminder rules: fire when `version` has
+ * advanced at least the required gap since the last fire, at most
+ * `maxFires` times per session. Because the version is an input (computed
+ * from the context, never reset by replaying history), re-evaluating the
+ * same state is always idempotent.
+ *
+ * `minGap` may be a function of the number of previous fires, so a rule can
+ * back off instead of going permanently silent (the 2026-08-27 live trial: a
+ * fixed cap of 5 went quiet after step ~2070, then 36 trace-less steps
+ * without a nudge). The idle rule doubles its gap after each fire with a
+ * 40-step ceiling, and resets the backoff when the agent answers a reminder
+ * (see createIdleRule). Anti-spam is about frequency, not a total budget.
+ */
+export declare class ReminderLatch {
+    private readonly minGap;
+    private readonly maxFires;
+    private readonly last;
+    constructor(minGap: number | ((fires: number) => number), maxFires: number);
+    /** The version of one session's last fire, for compliance checks. */
+    firedAt(sessionId: string): number | undefined;
+    /** Forget one session's fire history. */
+    reset(sessionId: string): void;
+    shouldFire(sessionId: string, version: number): boolean;
+}
+/**
+ * The idle rule: nudge when an active investigation hasn't updated trace in
+ * 5+ steps. Silent when there is no tree or the tree is resolved.
+ */
+export declare function createIdleRule(latch: ReminderLatch, gapSteps?: number): (ctx: ReminderContext) => string | null;
+/**
+ * The nesting rule: fires when steps pile up flat under milestones — no step
+ * nested under another step — while completed nodes already carry findings.
+ *
+ * Kinds are not stored on nodes, so shape is judged by depth: milestone at
+ * depth 1, step at depth 2; a step nested under a step lives at depth ≥ 3.
+ * "Flat" = at least 3 nodes at depth 2 and nothing deeper.
+ */
+export declare function createNestingRule(latch: ReminderLatch, flatSteps?: number): (ctx: ReminderContext) => string | null;
+//# sourceMappingURL=reminders.d.ts.map

package/lib/session-forests.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SessionForestStore — the single owner of a session's in-process forest.
+ *
+ * Two state holders exist: this store's map (live, synchronously mutated) and
+ * the session projection (durable, rebuilt from the session log). Before this
+ * module existed, the reconciliation protocol between them — "map wins during
+ * a turn, the projection seeds on first access, the log append precedes
+ * execute" — lived in comments inside the tool's execute switch, and every
+ * historical state bug came from a caller misapplying that protocol. Now the
+ * protocol is code, behind two methods:
+ *
+ * - {@link current} — read the session's forest, seeding from the projection
+ *   on first access. Projection failures are reported loudly once per session
+ *   instead of silently starting an empty forest.
+ * - {@link apply} — mutate the forest with one trace call. Fully synchronous:
+ *   the read → seed → fold → write critical section contains no `await`, so
+ *   no concurrent call can interleave. The create_tree double-fold guard
+ *   (phantom tree) lives here, not in the caller.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/session-forests
+ */
+import type { ForestState, TraceArgs } from './types.js';
+/** Minimal event shape the fold consumes. */
+export interface FoldableEvent {
+    type: string;
+    data: {
+        name?: string;
+        turn?: number;
+        step?: number;
+        arguments?: string;
+    };
+}
+/** Reads the durable projection state for seeding. Null when absent. */
+export type ForestSnapshotter = (session: {
+    id: string;
+}) => ForestState | null;
+/** Folds one tool/call-shaped event into forest state (the projection fold). */
+export type ForestFold = (state: ForestState | null, event: FoldableEvent) => ForestState | null;
+export declare class SessionForestStore {
+    private readonly snapshot;
+    private readonly fold;
+    private readonly warn;
+    private readonly forests;
+    private readonly seedFailureReported;
+    constructor(snapshot: ForestSnapshotter, fold: ForestFold, warn: (message: string) => void);
+    /**
+     * The current forest for a session. Seeds from the projection on first
+     * access (session replay / process restart); afterwards the in-process map
+     * is authoritative so parallel calls in one turn see each other immediately.
+     */
+    current(session: {
+        id: string;
+    }): {
+        forest: ForestState;
+        seeded: boolean;
+    };
+    /**
+     * Apply one trace call to the session's forest and return the result.
+     * Synchronous by design — see the module docstring.
+     */
+    apply(session: {
+        id: string;
+    }, args: TraceArgs, turn: number): ForestState;
+    /** Drop all in-process state (fiber disposal). */
+    clear(): void;
+}
+//# sourceMappingURL=session-forests.d.ts.map

package/lib/tree-layout.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tree layout — the single pure module for turning a flat node list into a
+ * displayable tree.
+ *
+ * Before this module, the traversal machinery was written three times: the
+ * host renderers (src/index.ts) had buildTreeIndex/sortChildren, the web
+ * client (src/client.ts) had its own depthOf/treeOrder, and the reminder
+ * rules (src/reminders.ts) had a third depthOf. Worse, the two displays
+ * disagreed: the model saw siblings status-sorted (active work first) while
+ * the human saw insertion order — the same tree, two layouts. Now both sides
+ * share these functions, so the human sees the tree in the same order the
+ * model reasoned about it.
+ *
+ * Everything here is a pure function of the node list — safe to call from
+ * render paths that re-run on session-log replay.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/tree-layout
+ */
+import type { TreeNode } from './types.js';
+/** Status → display rank: active work first, done/dead after, goal last. */
+export declare const STATUS_ORDER: Record<string, number>;
+/** Sort siblings: in_progress first, then pending, done, dead_end; the goal
+ *  node (convergence terminal) always last. */
+export declare function sortChildren(nodes: TreeNode[]): TreeNode[];
+/** Build child map and find root from a flat node list. */
+export declare function buildTreeIndex(nodes: TreeNode[]): {
+    children: Record<string, TreeNode[]>;
+    root: TreeNode | null;
+};
+/**
+ * Depth of a node via its parent chain (root = 0). Cycle-safe: a parent loop
+ * stops instead of recursing forever. Callers computing depths for many
+ * nodes in one pass may share a `cache` across calls.
+ */
+export declare function depthOf(nodes: TreeNode[], id: string, cache?: Record<string, number>): number;
+/**
+ * DFS flattening for display: children follow their parent, siblings in
+ * sortChildren order. Orphans (parent id not present in the list) are
+ * appended at the end so no node is ever dropped from view.
+ */
+export declare function flattenTree(nodes: TreeNode[]): TreeNode[];
+//# sourceMappingURL=tree-layout.d.ts.map

package/lib/tree-layout.js

@@ -0,0 +1,98 @@
+/**
+ * Tree layout — the single pure module for turning a flat node list into a
+ * displayable tree.
+ *
+ * Before this module, the traversal machinery was written three times: the
+ * host renderers (src/index.ts) had buildTreeIndex/sortChildren, the web
+ * client (src/client.ts) had its own depthOf/treeOrder, and the reminder
+ * rules (src/reminders.ts) had a third depthOf. Worse, the two displays
+ * disagreed: the model saw siblings status-sorted (active work first) while
+ * the human saw insertion order — the same tree, two layouts. Now both sides
+ * share these functions, so the human sees the tree in the same order the
+ * model reasoned about it.
+ *
+ * Everything here is a pure function of the node list — safe to call from
+ * render paths that re-run on session-log replay.
+ *
+ * @module @elinpf/dsh-ops-tool-trace/tree-layout
+ */
+/** Status → display rank: active work first, done/dead after, goal last. */
+export const STATUS_ORDER = {
+    in_progress: 0, pending: 1, done: 2, dead_end: 3, goal: 4, resolved: 5,
+};
+/** Sort siblings: in_progress first, then pending, done, dead_end; the goal
+ *  node (convergence terminal) always last. */
+export function sortChildren(nodes) {
+    return [...nodes].sort((a, b) => {
+        const aIsGoal = a.id === 'goal';
+        const bIsGoal = b.id === 'goal';
+        if (aIsGoal && !bIsGoal)
+            return 1;
+        if (!aIsGoal && bIsGoal)
+            return -1;
+        return (STATUS_ORDER[a.status] ?? 9) - (STATUS_ORDER[b.status] ?? 9);
+    });
+}
+/** Build child map and find root from a flat node list. */
+export function buildTreeIndex(nodes) {
+    const children = {};
+    let root = null;
+    for (const n of nodes) {
+        if (n.parent === null) {
+            root = n;
+        }
+        else {
+            if (!children[n.parent])
+                children[n.parent] = [];
+            children[n.parent].push(n);
+        }
+    }
+    return { children, root };
+}
+/**
+ * Depth of a node via its parent chain (root = 0). Cycle-safe: a parent loop
+ * stops instead of recursing forever. Callers computing depths for many
+ * nodes in one pass may share a `cache` across calls.
+ */
+export function depthOf(nodes, id, cache = {}) {
+    if (id in cache)
+        return cache[id];
+    let depth = 0;
+    let current = nodes.find((n) => n.id === id);
+    const seen = new Set();
+    while (current && current.parent !== null && !seen.has(current.id)) {
+        seen.add(current.id);
+        depth++;
+        current = nodes.find((n) => n.id === current.parent);
+    }
+    cache[id] = depth;
+    return depth;
+}
+/**
+ * DFS flattening for display: children follow their parent, siblings in
+ * sortChildren order. Orphans (parent id not present in the list) are
+ * appended at the end so no node is ever dropped from view.
+ */
+export function flattenTree(nodes) {
+    const { children, root } = buildTreeIndex(nodes);
+    const result = [];
+    const visited = new Set();
+    function visit(node) {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        result.push(node);
+        const kids = children[node.id];
+        if (kids)
+            for (const k of sortChildren(kids))
+                visit(k);
+    }
+    if (root)
+        visit(root);
+    for (const n of nodes) {
+        if (!visited.has(n))
+            result.push(n);
+    }
+    return result;
+}
+//# sourceMappingURL=tree-layout.js.map

package/lib/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Type definitions for the ops-trace plugin.
+ *
+ * @module @elinpf/dsh-ops-tool-trace
+ */
+export type { NodeStatus } from './node-status.js';
+import type { NodeStatus } from './node-status.js';
+/**
+ * A single node in the investigation tree.
+ * Lane and depth are NOT stored here — they are derived client-side.
+ */
+export interface TreeNode {
+    /** Unique id within the tree. The root node has id 'goal'. */
+    id: string;
+    /** One-line description of this node. */
+    title: string;
+    /** Current status per the 05 state machine. */
+    status: NodeStatus;
+    /** Parent node id; `null` for the goal node (tree root). */
+    parent: string | null;
+    /** Turns that operated on this node. */
+    turns: number[];
+    /** Resolution summary (written by `complete` or `resolve`). */
+    summary: string | null;
+    /** Creation-time rationale (add_step/add_milestone): the hypothesis's
+     *  "because" clause or the step's concrete target. */
+    detail: string | null;
+    /** Causal edges: other node ids that are the root cause of this node. */
+    caused_by: string[];
+}
+/**
+ * One investigation tree (goal + its milestones and steps).
+ */
+export interface TreeState {
+    /** All nodes in this tree. */
+    nodes: TreeNode[];
+    /** Whether this tree's goal has been resolved. */
+    resolved: boolean;
+}
+/**
+ * The full session state carried in a projection snapshot.
+ * A forest of independent investigation trees — resolved trees are kept
+ * for reference; the active tree is the latest unresolved one.
+ */
+export interface ForestState {
+    /** All trees in chronological order. */
+    trees: TreeState[];
+}
+/** The 11 actions the `trace` tool accepts. */
+export type TraceAction = 'create_tree' | 'add_step' | 'add_milestone' | 'start' | 'complete' | 'abandon' | 'reopen' | 'resolve' | 'link' | 'view' | 'help';
+/**
+ * Return value of every `trace` call.
+ * `tree` is the active tree that was operated on (or the resolved one).
+ */
+export interface TraceResult {
+    /** The active tree that was operated on. */
+    tree: TreeState;
+    /** Status summary of the active tree. */
+    summary: {
+        total: number;
+        counts: Record<NodeStatus, number>;
+        incomplete: Array<{
+            id: string;
+            title: string;
+            status: NodeStatus;
+        }>;
+        warning: string | null;
+    };
+    /** ID of the newly created node (add_step/add_milestone only). */
+    new_node?: string;
+    /** Non-blocking advisory hint (add_step only): the chosen parent looks
+     *  like a flat-hang mistake. Never a rejection — see doctrine.ts. */
+    hint?: string;
+}
+/**
+ * A single causal-edge pair used by the `link` action.
+ */
+export interface LinkPair {
+    id: string;
+    caused_by: string;
+}
+/**
+ * Tool arguments for `trace`. All fields are optional except `action`;
+ * which fields are required depends on the action (enforced at execute time).
+ */
+export interface TraceArgs {
+    action: TraceAction;
+    goal_title?: string;
+    id?: string;
+    parent_id?: string;
+    title?: string;
+    ids?: string[];
+    summary?: string;
+    detail?: string;
+    caused_by?: string;
+    links?: LinkPair[];
+    status_filter?: NodeStatus;
+    /** view output format: 'full' (default, with detail/summary) or 'tree'
+     *  (indented outline, shape only). */
+    format?: 'full' | 'tree';
+    /** Escape hatch for resolve on the goal: force tree closure while nodes
+     *  are still undecided (result carries a WARN). For abandoning an
+     *  investigation mid-way. Effective only when resolve targets the goal. */
+    force?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the ops-trace plugin.
+ *
+ * @module @elinpf/dsh-ops-tool-trace
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@elinpf/dsh-ops-tool-trace",
+  "version": "0.1.0",
+  "description": "Investigation tree tool for ops mode — replaces todo_write with a diverge-converge tree of steps, milestones, dead ends, and a resolved terminal.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./tree-layout": {
+      "types": "./lib/tree-layout.d.ts",
+      "default": "./lib/tree-layout.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types.js",
+    "lib/tree-layout.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@elinpf/dsh-ops-prompts": "^0.1.0",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-attachment": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-brand": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-scope": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-timeout": "0.0.1-rc.5",
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-llm": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-session-projection": "0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11",
+    "@elinpf/dsh-ops-prompts": "0.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}