dsh-trellis 0.1.0 → 0.1.2

package/lib/wait-tool.js

@@ -1,149 +1,192 @@
-/**
- * Event-driven waiting for DeepSeek Harness continuable subagents.
- *
- * Trellis dispatches role agents in DSH's default background mode so the main
- * agent can keep doing independent work. When that work is exhausted, this
- * tool provides a native synchronization point: it waits for `subagent/end`,
- * which DSH emits only after the child's settlement notice has been queued for
- * the parent. It deliberately replaces shell sleeps and polling loops.
- *
- * @module dsh-trellis/wait-tool
- */
-import { defineTool } from "@deepseek-ai/dsh-tools";
-
-function createSettlementWaiter(parentCtx, subagentId, signal) {
-  let disposeListener = () => {};
-  let settled = false;
-  let resolvePromise;
-  let rejectPromise;
-
-  const cleanup = () => {
-    disposeListener?.();
-    signal?.removeEventListener("abort", onAbort);
-  };
-  const onAbort = () => {
-    if (settled) return;
-    settled = true;
-    cleanup();
-    rejectPromise(signal.reason ?? new Error("Trellis subagent wait cancelled."));
-  };
-  const promise = new Promise((resolve, reject) => {
-    resolvePromise = resolve;
-    rejectPromise = reject;
-  });
-
-  disposeListener =
-    parentCtx.on("subagent/end", (info) => {
-      if (settled || info.id !== subagentId) return;
-      settled = true;
-      cleanup();
-      resolvePromise(info.stopReason);
-    }) ?? (() => {});
-  signal?.addEventListener("abort", onAbort, { once: true });
-  if (signal?.aborted) onAbort();
-
-  return {
-    promise,
-    cancel() {
-      if (settled) return;
-      settled = true;
-      cleanup();
-    },
-  };
-}
-
-/** Register the Trellis-only, event-driven subagent wait tool. */
-export function registerWaitTool(ctx) {
-  return ctx.tools.register(
-    defineTool({
-      name: "trellis_wait",
-      description:
-        "Wait efficiently for one direct background Trellis subagent after independent work is exhausted. This is event-driven: it returns only after DeepSeek Harness has queued the child's native settlement notice. Use the subagent id returned by `subagent`; never replace this with shell sleep, polling, or job_output.",
-      parameters: {
-        subagent_id: {
-          type: "string",
-          required: true,
-          description:
-            "Direct continuable subagent id returned by the `subagent` tool.",
-        },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            subagentId: { type: "string", required: true },
-            state: { type: "string", required: true },
-            stopReason: { type: "string", required: true },
-          },
-        },
-        render(_args, value) {
-          if (value.state === "already-inactive") {
-            return [
-              {
-                type: "text",
-                text: `subagent ${value.subagentId} is already inactive; consume its queued settlement notice or inspect its transcript`,
-              },
-            ];
-          }
-          return [
-            {
-              type: "text",
-              text: `subagent ${value.subagentId} settled (${value.stopReason}); its native settlement notice is queued`,
-            },
-          ];
-        },
-      },
-      async execute(args, exec) {
-        const parent = exec.agent;
-        if (!parent)
-          throw new Error(
-            "trellis_wait requires a calling agent (exec.agent was undefined)",
-          );
-
-        // Install the listener before reading the durable catalog so settlement
-        // cannot slip through the validation/read-to-wait window.
-        const waiter = createSettlementWaiter(
-          parent.ctx,
-          args.subagent_id,
-          exec.signal,
-        );
-        try {
-          const entries = await ctx.subagents.listChildren(
-            parent.id,
-            exec.signal,
-          );
-          const child = entries.find(
-            (entry) =>
-              entry.kind === "child" &&
-              entry.mode === "continuable" &&
-              entry.id === args.subagent_id,
-          );
-          if (child === undefined) {
-            throw new Error(
-              `trellis_wait can only wait for a direct continuable subagent of this session: ${args.subagent_id}`,
-            );
-          }
-          if (child.activity === "inactive") {
-            waiter.cancel();
-            return {
-              subagentId: args.subagent_id,
-              state: "already-inactive",
-              stopReason: "unknown",
-            };
-          }
-
-          const stopReason = await waiter.promise;
-          return {
-            subagentId: args.subagent_id,
-            state: "settled",
-            stopReason,
-          };
-        } catch (error) {
-          waiter.cancel();
-          throw error;
-        }
-      },
-    }),
-  );
-}
+/**
+ * Event-driven waiting for DeepSeek Harness continuable subagents.
+ *
+ * Trellis dispatches role agents in DSH's default background mode so the main
+ * agent can keep doing independent work. When that work is exhausted, this
+ * tool provides a native synchronization point: it waits for `subagent/end`,
+ * which DSH emits only after the child's settlement notice has been queued for
+ * the parent. It deliberately replaces shell sleeps and polling loops.
+ *
+ * @module dsh-trellis/wait-tool
+ */
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+function createSettlementWaiter(parentCtx, subagentId, signal) {
+  let disposeListener = () => {};
+  let settled = false;
+  let resolvePromise;
+  let rejectPromise;
+
+  const cleanup = () => {
+    disposeListener?.();
+    signal?.removeEventListener("abort", onAbort);
+  };
+  const onAbort = () => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    rejectPromise(signal.reason ?? new Error("Trellis subagent wait cancelled."));
+  };
+  const promise = new Promise((resolve, reject) => {
+    resolvePromise = resolve;
+    rejectPromise = reject;
+  });
+
+  disposeListener =
+    parentCtx.on("subagent/end", (info) => {
+      if (settled || info.id !== subagentId) return;
+      settled = true;
+      cleanup();
+      resolvePromise(info);
+    }) ?? (() => {});
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+
+  return {
+    promise,
+    cancel() {
+      if (settled) return;
+      settled = true;
+      cleanup();
+    },
+  };
+}
+
+/** Map a DSH stop reason to a gate-safe Trellis outcome. */
+export function settlementOutcome(stopReason) {
+  if (stopReason === "completed") return "completed";
+  if (stopReason === "aborted") return "aborted";
+  if (stopReason === "unknown") return "unknown";
+  return "failed";
+}
+
+function settledResult(subagentId, info) {
+  const stopReason =
+    typeof info?.stopReason === "string" ? info.stopReason : "unknown";
+  return {
+    subagentId,
+    state: "settled",
+    outcome: settlementOutcome(stopReason),
+    stopReason,
+    runId: typeof info?.runId === "string" ? info.runId : "",
+    provider: typeof info?.provider === "string" ? info.provider : "",
+    assistantOutputBlocks: Array.isArray(info?.lastAssistantMessage)
+      ? info.lastAssistantMessage.length
+      : 0,
+    settlementNoticeQueued: true,
+  };
+}
+
+function inactiveResult(subagentId) {
+  return {
+    subagentId,
+    state: "already-inactive",
+    outcome: "unknown",
+    stopReason: "unknown",
+    runId: "",
+    provider: "",
+    assistantOutputBlocks: 0,
+    settlementNoticeQueued: false,
+  };
+}
+
+/** Register the Trellis-only, event-driven subagent wait tool. */
+export function registerWaitTool(ctx) {
+  return ctx.tools.register(
+    defineTool({
+      name: "trellis_wait",
+      description:
+        "Wait efficiently for one direct background Trellis subagent after independent work is exhausted. This is an event-driven synchronization barrier over DSH's native settlement lifecycle. Use the subagent id returned by `subagent`; never replace this with shell sleep, polling, or job_output. On DSH rc.8+, an idle parent can instead yield and be woken by the native settlement notice.",
+      parameters: {
+        subagent_id: {
+          type: "string",
+          required: true,
+          description:
+            "Direct continuable subagent id returned by the `subagent` tool.",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            subagentId: { type: "string", required: true },
+            state: { type: "string", required: true },
+            outcome: { type: "string", required: true },
+            stopReason: { type: "string", required: true },
+            runId: { type: "string", required: true },
+            provider: { type: "string", required: true },
+            assistantOutputBlocks: { type: "number", required: true },
+            settlementNoticeQueued: { type: "boolean", required: true },
+          },
+        },
+        render(_args, value) {
+          if (value.state === "already-inactive") {
+            return [
+              {
+                type: "text",
+                text: `subagent ${value.subagentId} is already inactive; no stop reason can be proven from the catalog snapshot, so inspect its transcript or an already-visible settlement notice before passing a gate`,
+              },
+            ];
+          }
+          if (value.outcome !== "completed") {
+            return [
+              {
+                type: "text",
+                text: `subagent ${value.subagentId} settled with ${value.outcome} (${value.stopReason}); do not treat this gate as passed; its native settlement notice is queued`,
+              },
+            ];
+          }
+          return [
+            {
+              type: "text",
+              text: `subagent ${value.subagentId} completed; its native settlement notice is queued`,
+            },
+          ];
+        },
+      },
+      async execute(args, exec) {
+        const parent = exec.agent;
+        if (!parent)
+          throw new Error(
+            "trellis_wait requires a calling agent (exec.agent was undefined)",
+          );
+
+        // Install the listener before reading the durable catalog so settlement
+        // cannot slip through the validation/read-to-wait window.
+        const waiter = createSettlementWaiter(
+          parent.ctx,
+          args.subagent_id,
+          exec.signal,
+        );
+        try {
+          const entries = await ctx.subagents.listChildren(
+            parent.id,
+            exec.signal,
+          );
+          const child = entries.find(
+            (entry) =>
+              entry.kind === "child" &&
+              entry.mode === "continuable" &&
+              entry.id === args.subagent_id,
+          );
+          if (child === undefined) {
+            throw new Error(
+              `trellis_wait can only wait for a direct continuable subagent of this session: ${args.subagent_id}`,
+            );
+          }
+          if (child.activity === "inactive") {
+            waiter.cancel();
+            return inactiveResult(args.subagent_id);
+          }
+
+          const info = await waiter.promise;
+          return settledResult(args.subagent_id, info);
+        } catch (error) {
+          waiter.cancel();
+          throw error;
+        }
+      },
+    }),
+  );
+}

package/package.json

@@ -1,79 +1,114 @@
-{
-  "name": "dsh-trellis",
-  "version": "0.1.0",
-  "description": "Trellis workflow integration for DeepSeek Harness: per-turn workflow-state breadcrumbs, utility commands, and native session identity.",
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml"
-  ],
-  "author": "SajoLuo",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/SajoLuo/dsh-trellis.git"
-  },
-  "homepage": "https://github.com/SajoLuo/dsh-trellis#readme",
-  "bugs": {
-    "url": "https://github.com/SajoLuo/dsh-trellis/issues"
-  },
-  "keywords": [
-    "deepseek-harness",
-    "dsh",
-    "trellis",
-    "workflow",
-    "ai-agent"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "packageManager": "pnpm@10.33.0",
-  "dsh": {
-    "bundle": {
-      "patch": "cordis.patch.yml"
-    }
-  },
-  "scripts": {
-    "test": "node --test \"test/*.test.js\""
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "peerDependenciesMeta": {
-    "@deepseek-ai/cordis": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-commands": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-llm": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-shell-env": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
-    },
-    "@deepseek-ai/schemastery": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  }
-}
+{
+  "name": "dsh-trellis",
+  "version": "0.1.2",
+  "description": "Trellis workflow integration for DeepSeek Harness: per-turn workflow-state breadcrumbs, utility commands, and native session identity.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "author": "SajoLuo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SajoLuo/dsh-trellis.git"
+  },
+  "homepage": "https://github.com/SajoLuo/dsh-trellis#readme",
+  "bugs": {
+    "url": "https://github.com/SajoLuo/dsh-trellis/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "trellis",
+    "workflow",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "dsh": {
+    "bundle": {
+      "patch": "cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build:client": "tsdown",
+    "test": "node --test \"test/*.test.js\"",
+    "prepack": "pnpm run build:client"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-shell-env": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings-plugins": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-shell-env": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-subagent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-shell-env": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-subagent": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2"
+  }
+}