@nodetool-ai/websocket 0.7.0-rc.22 → 0.8.1

package/README.md

@@ -0,0 +1,50 @@
+# @nodetool-ai/websocket
+
+The Fastify HTTP + WebSocket server — the main NodeTool API (default port 7777).
+Hosts the unified websocket runner for workflow and chat operations plus the
+tRPC routers and REST endpoints.
+
+## Responsibilities
+
+- `WebSocketClientSession` — per-connection runner with a job concurrency queue.
+- tRPC routers (`src/trpc/`) with a consistent error shape (`apiCode`).
+- REST endpoints (assets, workflows, models, …) and MsgPack WebSocket messages.
+
+## Run
+
+```bash
+npm run dev:server          # from repo root (tsx --watch)
+node packages/websocket/dist/server.js   # built server
+```
+
+## Develop
+
+```bash
+npm run build --workspace=packages/websocket
+npm run test  --workspace=packages/websocket
+npm run lint  --workspace=packages/websocket
+```
+
+## Environment variables
+
+- `NODETOOL_WS_MAX_MESSAGE_BYTES` — largest inbound WebSocket frame accepted
+  before deserialization (bytes; default 256 MiB). A larger frame is rejected
+  with a structured error; the connection stays open.
+- `NODETOOL_VALIDATE_OUTBOUND_WS` — validates every outbound (server→client)
+  frame whose `type` matches a known protocol schema
+  (`@nodetool-ai/protocol`'s `processingMessageSchemas` /
+  `outboundControlMessageSchemas`) before it goes on the wire. `1`/`true`
+  forces it on, `0`/`false` forces it off. Unset, it defaults to on under
+  `NODE_ENV=test` or Vitest (`VITEST`) and off otherwise — a malformed frame
+  throws in that case, so a bug that produces one fails the test that
+  exercised it instead of shipping to production. Frames with an
+  unrecognized or absent `type` (the ad hoc `{ error, details }` command
+  replies) are never validated.
+
+Inbound frames (client commands) are always validated against the Zod command
+schemas in `@nodetool-ai/protocol` (`webSocketCommandEnvelopeSchema`,
+`commandDataSchemas`) — there is no opt-out, since a malformed inbound frame
+that isn't rejected is exactly what a real client should never be able to send.
+
+API reference: see the `nodetool-api-reference` skill and the root
+[AGENTS.md](../../AGENTS.md).

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:17.965Z

package/dist/agent/run-node-tool.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `run_node` — execute a single NodeTool node by type and return its output.
+ *
+ * Lives in the websocket package because running a node requires the kernel
+ * machinery (executor resolution, node hydration, WorkflowRunner) that the
+ * runner owns. The tool itself is a thin wrapper around a `runNode` callback
+ * supplied by the runner.
+ */
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import { Tool } from "@nodetool-ai/agents";
+/**
+ * HOLDOUT (anti-slop/no-unknown-returns): a node's output is an arbitrary
+ * workflow value (or an `{ error }` bag when the run failed) — the open domain
+ * NodeTool has no named union for.
+ */
+export type RunNodeFn = (nodeType: string, inputs: Record<string, unknown>) => Promise<unknown>;
+export declare class RunNodeTool extends Tool {
+    readonly name = "run_node";
+    readonly description: string;
+    protected readonly jsonSchema: {
+        type: "object";
+        properties: {
+            node_type: {
+                type: "string";
+                description: string;
+            };
+            inputs: {
+                type: "object";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private readonly runNode;
+    constructor(runNode: RunNodeFn);
+    process(_context: ProcessingContext, params: Record<string, unknown>): Promise<unknown>;
+    userMessage(params: Record<string, unknown>): string;
+}
+//# sourceMappingURL=run-node-tool.d.ts.map

package/dist/agent/run-node-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-node-tool.d.ts","sourceRoot":"","sources":["../../src/agent/run-node-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG3C;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,qBAAa,WAAY,SAAQ,IAAI;IACnC,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,WAAW,SAIF;IAClB,SAAS,CAAC,QAAQ,CAAC,UAAU;QAC3B,IAAI,EAAE,QAAQ;QACd,UAAU;YACR,SAAS;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW;;YAIb,MAAM;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW;;;QAKf,QAAQ;MACR;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IAEpC,YAAY,OAAO,EAAE,SAAS,EAG7B;IAKK,OAAO,CACX,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAQlB;IAED,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAGnD;CACF"}

package/dist/agent/run-node-tool.js

@@ -0,0 +1,55 @@
+/**
+ * `run_node` — execute a single NodeTool node by type and return its output.
+ *
+ * Lives in the websocket package because running a node requires the kernel
+ * machinery (executor resolution, node hydration, WorkflowRunner) that the
+ * runner owns. The tool itself is a thin wrapper around a `runNode` callback
+ * supplied by the runner.
+ */
+import { Tool } from "@nodetool-ai/agents";
+import { isObjectLike } from "../lib/wire-values.js";
+export class RunNodeTool extends Tool {
+    name = "run_node";
+    description = "Run a single NodeTool node by its fully-qualified type and return its " +
+        "output. Use list_nodes / search_nodes / get_node_info to discover node " +
+        "types and their inputs first. For multi-node pipelines, prefer " +
+        "run_workflow.";
+    jsonSchema = {
+        type: "object",
+        properties: {
+            node_type: {
+                type: "string",
+                description: "Fully-qualified node type, e.g. 'nodetool.text.Concat' or " +
+                    "'nodetool.image.Blur'."
+            },
+            inputs: {
+                type: "object",
+                description: "Input values keyed by the node's property names. Omit for nodes " +
+                    "with no required inputs."
+            }
+        },
+        required: ["node_type"]
+    };
+    runNode;
+    constructor(runNode) {
+        super();
+        this.runNode = runNode;
+    }
+    // HOLDOUT (anti-slop/no-unknown-returns): the base `Tool.process` contract
+    // in `@nodetool-ai/agents` returns `Promise<unknown>`, and the value here is
+    // the node's own output.
+    async process(_context, params) {
+        const nodeType = String(params["node_type"] ?? "");
+        if (!nodeType)
+            return { error: "node_type is required" };
+        const inputs = isObjectLike(params["inputs"])
+            ? params["inputs"]
+            : {};
+        return this.runNode(nodeType, inputs);
+    }
+    userMessage(params) {
+        const t = params["node_type"];
+        return t ? `Running node ${t}` : "Running node";
+    }
+}
+//# sourceMappingURL=run-node-tool.js.map

package/dist/agent/run-node-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-node-tool.js","sourceRoot":"","sources":["../../src/agent/run-node-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAYrD,MAAM,OAAO,WAAY,SAAQ,IAAI;IAC1B,IAAI,GAAG,UAAU,CAAC;IAClB,WAAW,GAClB,wEAAwE;QACxE,yEAAyE;QACzE,iEAAiE;QACjE,eAAe,CAAC;IACC,UAAU,GAAG;QAC9B,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,SAAS,EAAE;gBACT,IAAI,EAAE,QAAiB;gBACvB,WAAW,EACT,4DAA4D;oBAC5D,wBAAwB;aAC3B;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAiB;gBACvB,WAAW,EACT,kEAAkE;oBAClE,0BAA0B;aAC7B;SACF;QACD,QAAQ,EAAE,CAAC,WAAW,CAAC;KACxB,CAAC;IAEe,OAAO,CAAY;IAEpC,YAAY,OAAkB;QAC5B,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,2EAA2E;IAC3E,6EAA6E;IAC7E,yBAAyB;IACzB,KAAK,CAAC,OAAO,CACX,QAA2B,EAC3B,MAA+B;QAE/B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC;QACzD,MAAM,MAAM,GACV,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,CAAC,CAAE,MAAM,CAAC,QAAQ,CAA6B;YAC/C,CAAC,CAAC,EAAE,CAAC;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,WAAW,CAAC,MAA+B;QACzC,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QAC9B,OAAO,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC;IAClD,CAAC;CACF"}

package/dist/chat-prediction-forwarder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Forwards ProcessingContext `prediction` events onto a chat socket.
+ *
+ * The chat turn's context already emits provider/model/capability on every
+ * `runProviderPrediction` call. Without this listener those events stay in
+ * the context queue and never reach ChatUI.
+ */
+import type { ProcessingMessage } from "@nodetool-ai/protocol";
+export declare function attachChatPredictionForwarder(addMessageListener: (listener: (msg: ProcessingMessage) => void) => () => void, send: (msg: Record<string, unknown>) => void, ids: {
+    threadId: string | null;
+    workflowId?: string | null;
+}): () => void;
+//# sourceMappingURL=chat-prediction-forwarder.d.ts.map

package/dist/chat-prediction-forwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-prediction-forwarder.d.ts","sourceRoot":"","sources":["../src/chat-prediction-forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,wBAAgB,6BAA6B,CAC3C,kBAAkB,EAAE,CAClB,QAAQ,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,KACvC,MAAM,IAAI,EACf,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC5C,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC3D,MAAM,IAAI,CAeZ"}

package/dist/chat-prediction-forwarder.js

@@ -0,0 +1,22 @@
+/**
+ * Forwards ProcessingContext `prediction` events onto a chat socket.
+ *
+ * The chat turn's context already emits provider/model/capability on every
+ * `runProviderPrediction` call. Without this listener those events stay in
+ * the context queue and never reach ChatUI.
+ */
+export function attachChatPredictionForwarder(addMessageListener, send, ids) {
+    return addMessageListener((msg) => {
+        if (msg.type !== "prediction") {
+            return;
+        }
+        const forwarded = {
+            ...msg,
+            thread_id: ids.threadId
+        };
+        send(ids.workflowId == null
+            ? forwarded
+            : { ...forwarded, workflow_id: ids.workflowId });
+    });
+}
+//# sourceMappingURL=chat-prediction-forwarder.js.map

package/dist/chat-prediction-forwarder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-prediction-forwarder.js","sourceRoot":"","sources":["../src/chat-prediction-forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,UAAU,6BAA6B,CAC3C,kBAEe,EACf,IAA4C,EAC5C,GAA4D;IAE5D,OAAO,kBAAkB,CAAC,CAAC,GAAG,EAAE,EAAE;QAChC,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAG;YAChB,GAAG,GAAG;YACN,SAAS,EAAE,GAAG,CAAC,QAAQ;SACU,CAAC;QACpC,IAAI,CACF,GAAG,CAAC,UAAU,IAAI,IAAI;YACpB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,WAAW,EAAE,GAAG,CAAC,UAAU,EAAE,CAClD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/chat-tool-call-repair.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Keeping a chat transcript well-formed when a turn does not finish.
+ *
+ * A superseding user message cancels the turn in flight (`beginChatTurn`), and
+ * the assistant message announcing a tool call has usually already been
+ * persisted by then. Without the result row that belongs with it, the thread
+ * holds a tool call nobody answered — which Anthropic rejects outright ("
+ * `tool_use` ids were found without `tool_result` blocks"), so switching model
+ * on such a thread fails every later turn.
+ *
+ * Two users, one wording:
+ *  - the runner writes {@link SUPERSEDED_TOOL_RESULT} for calls left open when
+ *    a turn tears down, so the row is never missing in the first place;
+ *  - {@link repairOrphanedToolCalls} patches history at *load* time, for the
+ *    threads already carrying an orphan. It returns a new array and writes
+ *    nothing back — repairing the stored rows is a separate decision.
+ */
+import type { Message as ProviderMessage } from "@nodetool-ai/runtime";
+/**
+ * What an abandoned tool call reports to the model.
+ *
+ * The wording is deliberate. When a turn is superseded the tool has often
+ * ALREADY run: the provider loop checks its abort signal before dispatching a
+ * call, never during, so a call in flight runs to completion and only its
+ * result is lost. Telling the model the call did not execute would invite it
+ * to repeat a side effect that already landed — worse than saying nothing.
+ * State the interruption, admit the outcome is unknown, and send the model to
+ * look.
+ */
+export declare const SUPERSEDED_TOOL_RESULT: string;
+/** Ids of tool calls in `messages` that no later tool message answers. */
+export declare function orphanedToolCallIds(messages: readonly ProviderMessage[]): string[];
+/** The tool message a never-answered call gets. */
+export declare function supersededToolMessage(toolCallId: string, threadId?: string | null): ProviderMessage;
+/**
+ * Insert a synthetic result for every tool call the transcript leaves open.
+ *
+ * Each missing result is placed directly after the tool messages that already
+ * follow its assistant message, which is where the provider converters expect
+ * it. A call whose assistant message is absent from `messages` is left alone:
+ * on the resume fast path the array is a slice of the thread, and the real
+ * result may simply sit outside it.
+ */
+export declare function repairOrphanedToolCalls(messages: readonly ProviderMessage[]): ProviderMessage[];
+//# sourceMappingURL=chat-tool-call-repair.d.ts.map

package/dist/chat-tool-call-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-tool-call-repair.d.ts","sourceRoot":"","sources":["../src/chat-tool-call-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,QAItB,CAAC;AAEd,0EAA0E;AAC1E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,MAAM,EAAE,CAiBV;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,eAAe,CAWjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,eAAe,EAAE,CAuBnB"}

package/dist/chat-tool-call-repair.js

@@ -0,0 +1,100 @@
+/**
+ * Keeping a chat transcript well-formed when a turn does not finish.
+ *
+ * A superseding user message cancels the turn in flight (`beginChatTurn`), and
+ * the assistant message announcing a tool call has usually already been
+ * persisted by then. Without the result row that belongs with it, the thread
+ * holds a tool call nobody answered — which Anthropic rejects outright ("
+ * `tool_use` ids were found without `tool_result` blocks"), so switching model
+ * on such a thread fails every later turn.
+ *
+ * Two users, one wording:
+ *  - the runner writes {@link SUPERSEDED_TOOL_RESULT} for calls left open when
+ *    a turn tears down, so the row is never missing in the first place;
+ *  - {@link repairOrphanedToolCalls} patches history at *load* time, for the
+ *    threads already carrying an orphan. It returns a new array and writes
+ *    nothing back — repairing the stored rows is a separate decision.
+ */
+import { isString } from "./lib/wire-values.js";
+/**
+ * What an abandoned tool call reports to the model.
+ *
+ * The wording is deliberate. When a turn is superseded the tool has often
+ * ALREADY run: the provider loop checks its abort signal before dispatching a
+ * call, never during, so a call in flight runs to completion and only its
+ * result is lost. Telling the model the call did not execute would invite it
+ * to repeat a side effect that already landed — worse than saying nothing.
+ * State the interruption, admit the outcome is unknown, and send the model to
+ * look.
+ */
+export const SUPERSEDED_TOOL_RESULT = "[interrupted] A new user message ended this turn before the result of " +
+    "this tool call was recorded. The call may already have run and taken " +
+    "effect — its outcome is unknown. Check the current state before running " +
+    "it again.";
+/** Ids of tool calls in `messages` that no later tool message answers. */
+export function orphanedToolCallIds(messages) {
+    const answered = new Set();
+    for (const m of messages) {
+        if (m.role === "tool" && isString(m.toolCallId)) {
+            answered.add(m.toolCallId);
+        }
+    }
+    const orphans = [];
+    for (const m of messages) {
+        if (m.role !== "assistant" || !Array.isArray(m.toolCalls))
+            continue;
+        for (const call of m.toolCalls) {
+            if (isString(call.id) && !answered.has(call.id)) {
+                orphans.push(call.id);
+            }
+        }
+    }
+    return orphans;
+}
+/** The tool message a never-answered call gets. */
+export function supersededToolMessage(toolCallId, threadId) {
+    const message = {
+        role: "tool",
+        content: SUPERSEDED_TOOL_RESULT,
+        toolCallId,
+        toolCalls: null
+    };
+    if (threadId !== undefined) {
+        message.threadId = threadId;
+    }
+    return message;
+}
+/**
+ * Insert a synthetic result for every tool call the transcript leaves open.
+ *
+ * Each missing result is placed directly after the tool messages that already
+ * follow its assistant message, which is where the provider converters expect
+ * it. A call whose assistant message is absent from `messages` is left alone:
+ * on the resume fast path the array is a slice of the thread, and the real
+ * result may simply sit outside it.
+ */
+export function repairOrphanedToolCalls(messages) {
+    const orphans = new Set(orphanedToolCallIds(messages));
+    if (orphans.size === 0)
+        return [...messages];
+    const out = [];
+    for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        out.push(m);
+        if (m.role !== "assistant" || !Array.isArray(m.toolCalls))
+            continue;
+        const missing = m.toolCalls.filter((call) => isString(call.id) && orphans.has(call.id));
+        if (missing.length === 0)
+            continue;
+        // Step over the real results this assistant did get, so the synthetic ones
+        // join that block instead of splitting it.
+        while (i + 1 < messages.length && messages[i + 1].role === "tool") {
+            out.push(messages[++i]);
+        }
+        for (const call of missing) {
+            out.push(supersededToolMessage(call.id, m.threadId));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=chat-tool-call-repair.js.map

package/dist/chat-tool-call-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-tool-call-repair.js","sourceRoot":"","sources":["../src/chat-tool-call-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,wEAAwE;IACxE,uEAAuE;IACvE,0EAA0E;IAC1E,WAAW,CAAC;AAEd,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CACjC,QAAoC;IAEpC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC;YAChD,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;YAAE,SAAS;QACpE,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,qBAAqB,CACnC,UAAkB,EAClB,QAAwB;IAExB,MAAM,OAAO,GAAoB;QAC/B,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,sBAAsB;QAC/B,UAAU;QACV,SAAS,EAAE,IAAI;KAChB,CAAC;IACF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAoC;IAEpC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;IAE7C,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACZ,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;YAAE,SAAS;QACpE,MAAM,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAChC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CACpD,CAAC;QACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,2EAA2E;QAC3E,2CAA2C;QAC3C,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAClE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/chat-turn-registry.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Detachable chat/agent turns.
+ *
+ * The WebSocket runner is per-connection, so before this module existed a
+ * dropped socket aborted the in-flight chat turn (`disconnect()` →
+ * `cancelChatTurn()`): a laptop lid-close killed the agent mid-work and the
+ * client had nothing to reattach to. A {@link ChatTurnSession} decouples the
+ * turn from the socket: every frame the turn emits is stamped with a
+ * monotonically increasing `chat_seq` and appended to a bounded buffer, and
+ * delivery goes to whichever connection is currently attached — or nowhere,
+ * while the client is away. On reconnect the client sends
+ * `{command: "resume_chat", data: {thread_id, last_seq}}` and gets the missed
+ * tail replayed, followed by live frames if the turn is still running.
+ *
+ * Sessions are keyed by user+thread in a process-wide registry (one turn per
+ * thread; a new turn supersedes and aborts the previous one, matching the
+ * single-turn semantics `beginChatTurn` already enforces per connection).
+ * A running turn uses its execution budget even while detached. An optional
+ * `NODETOOL_CHAT_DETACH_GRACE_MS` can impose an additional disconnect limit
+ * (disabled by default). Finished sessions use a retention timer:
+ *   - retention: a finished session is kept for
+ *     `NODETOOL_CHAT_REPLAY_RETENTION_MS` (default 5 min) so a client that
+ *     reconnects just after the turn ended still gets the tail, then dropped.
+ *
+ * Assistant/tool messages are persisted to the DB independently of this
+ * buffer, so an expired or truncated replay degrades to the client refetching
+ * thread history over REST — nothing is lost except unpersisted stream chunks.
+ */
+/**
+ * Why a turn was aborted. Rides `controller.abort(reason)`, so the handler
+ * reading `signal.reason` can tell a shutdown from the user's own Stop — the
+ * one case that leaves a note in the transcript.
+ */
+export type ChatTurnAbortReason = "stop" | "superseded" | "shutdown";
+/** A connection that can deliver frames to its client. */
+interface ChatTurnDeliveryTarget {
+    deliver(message: Record<string, unknown>): Promise<void>;
+}
+/**
+ * The executing connection's per-turn hooks. Kept on the session so a
+ * different connection (post-reconnect) can route a client's `tool_result` /
+ * approval / `stop` back to the runner that actually owns the turn.
+ */
+export interface ChatTurnExecutionHooks {
+    resolveToolResult(toolCallId: string, payload: Record<string, unknown>): void;
+    resolveApproval(approvalId: string, payload: Record<string, unknown>): void;
+    cancelPendingCalls(threadId: string): void;
+}
+interface ChatTurnAttachResult {
+    /** Frames with `chat_seq` greater than the requested `last_seq`. */
+    replay: Array<Record<string, unknown>>;
+    /** True when `last_seq` predates what the bounded buffer still holds. */
+    incomplete: boolean;
+}
+export declare class ChatTurnSession {
+    private readonly controller;
+    readonly hooks: ChatTurnExecutionHooks;
+    private readonly onDrop;
+    /** Told when the turn settles, so the registry can answer `drained`. */
+    private readonly onFinish;
+    readonly userId: string;
+    readonly threadId: string;
+    status: "running" | "finished";
+    private seq;
+    private buffer;
+    /** Highest seq evicted from the bounded buffer (0 = nothing evicted). */
+    private evictedThroughSeq;
+    private target;
+    /**
+     * Serializes delivery: replayed frames enqueue before any live frame that
+     * arrives after attach, so the client always sees seq order.
+     */
+    private deliveryChain;
+    private detachTimer;
+    private retentionTimer;
+    constructor(userId: string, threadId: string, controller: AbortController, hooks: ChatTurnExecutionHooks, onDrop: (session: ChatTurnSession) => void, startSeq: number, 
+    /** Told when the turn settles, so the registry can answer `drained`. */
+    onFinish?: () => void);
+    get lastSeq(): number;
+    /**
+     * Where a client with no frame state (a freshly reloaded page) should
+     * start its replay: after the turn's last `message` frame. Everything up
+     * to and including that frame is persisted to the DB and reachable over
+     * REST; what follows — stream chunks of the in-progress reply, status
+     * updates, pending tool/approval requests — exists only in this buffer.
+     * With no `message` frame buffered yet, replay starts at the oldest
+     * frame still held.
+     */
+    freshAttachSeq(): number;
+    /**
+     * Stamp, buffer, and (when a connection is attached) deliver one frame.
+     * Returns the stamped copy.
+     */
+    emit(message: Record<string, unknown>): {
+        chat_seq: number;
+    };
+    /**
+     * Attach a connection and hand back the frames it missed. Live frames
+     * emitted after this call are delivered to the new target, strictly after
+     * the returned replay is delivered (both ride {@link deliveryChain} when
+     * sent via {@link deliverReplay}).
+     */
+    attach(target: ChatTurnDeliveryTarget, lastSeq: number): ChatTurnAttachResult;
+    /** Deliver frames on the session's ordered delivery chain. */
+    deliverReplay(target: ChatTurnDeliveryTarget, frames: Array<Record<string, unknown>>): Promise<void>;
+    /**
+     * The attached connection went away. A running turn keeps executing and
+     * buffering under its existing execution budget. Operators may configure
+     * an additional detach timeout.
+     */
+    detach(target?: ChatTurnDeliveryTarget): void;
+    /**
+     * Abort the turn. The reason reaches the handler as `signal.reason`: only
+     * `"shutdown"` is something the user did not do and does not already know
+     * about, so only that one is written into the transcript.
+     */
+    abort(reason: ChatTurnAbortReason): void;
+    /**
+     * The turn's promise settled. The session sticks around (still replayable)
+     * for the retention window, then drops out of the registry.
+     */
+    finish(): void;
+    /** Release timers when the registry drops the session. */
+    dispose(): void;
+    private clearDetachTimer;
+    private enqueueDelivery;
+}
+export declare class ChatTurnRegistry {
+    private sessions;
+    /**
+     * Per-thread seq high-water marks, so a new turn continues numbering where
+     * the previous one left off and a client's `last_seq` from an older turn
+     * can never accidentally skip a newer turn's frames. Bounded: oldest
+     * entries are evicted past {@link MAX_SEQ_ENTRIES}.
+     */
+    private lastSeqByThread;
+    private static readonly MAX_SEQ_ENTRIES;
+    /** Resolvers waiting for {@link runningCount} to reach zero. */
+    private drainWaiters;
+    private key;
+    /**
+     * Open a session for a new turn. An existing session for the same thread is
+     * superseded: aborted (if still running) and dropped, exactly as a new
+     * `chat_message` on a live connection cancels the previous turn.
+     */
+    open(userId: string, threadId: string, controller: AbortController, hooks: ChatTurnExecutionHooks): ChatTurnSession;
+    get(userId: string, threadId: string): ChatTurnSession | null;
+    /** Sessions still running for a user — what a fresh client can reattach to. */
+    listRunningForUser(userId: string): ChatTurnSession[];
+    /** Turns this process is still executing. What a drain waits on. */
+    runningCount(): number;
+    /** Abort every running turn with one reason. Returns how many were aborted. */
+    abortAll(reason: ChatTurnAbortReason): number;
+    /** Abort local turns whose conversation is being deleted with its project. */
+    abortThreads(userId: string, threadIds: ReadonlySet<string>): number;
+    /**
+     * Resolve true once no turn is running, false when `timeoutMs` elapses
+     * first. A turn is running until its handler has settled, which is what
+     * writes the stand-in tool-result rows — so a shutdown that waits on this
+     * leaves a well-formed transcript behind.
+     */
+    drained(timeoutMs: number): Promise<boolean>;
+    private notifyDrainWaiters;
+    drop(session: ChatTurnSession): void;
+}
+/** Process-wide registry: sessions survive their originating connection. */
+export declare const chatTurnRegistry: ChatTurnRegistry;
+export {};
+//# sourceMappingURL=chat-turn-registry.d.ts.map

package/dist/chat-turn-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-turn-registry.d.ts","sourceRoot":"","sources":["../src/chat-turn-registry.ts"],"names":[],"mappings":"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"}