@herdctl/chat 0.3.14 → 0.4.0

package/dist/__tests__/sdk-message-translator.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for the transport-agnostic SDKMessage → chat-event translator.
+ */
+export {};
+//# sourceMappingURL=sdk-message-translator.test.d.ts.map

package/dist/__tests__/sdk-message-translator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-message-translator.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/sdk-message-translator.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/sdk-message-translator.test.js

@@ -0,0 +1,184 @@
+/**
+ * Tests for the transport-agnostic SDKMessage → chat-event translator.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { createSDKMessageHandler, SDKMessageTranslator, } from "../sdk-message-translator.js";
+// =============================================================================
+// Helpers — build SDK messages in the shape the extractors expect
+// =============================================================================
+function assistantText(text) {
+    return { type: "assistant", message: { content: [{ type: "text", text }] } };
+}
+function assistantToolUse(id, name, input) {
+    return {
+        type: "assistant",
+        message: { content: [{ type: "tool_use", id, name, input }] },
+    };
+}
+function toolResult(toolUseId, output, isError = false) {
+    return {
+        type: "user",
+        message: {
+            content: [
+                { type: "tool_result", tool_use_id: toolUseId, content: output, is_error: isError },
+            ],
+        },
+    };
+}
+describe("SDKMessageTranslator", () => {
+    describe("text deltas", () => {
+        it("emits assistant text via onText", async () => {
+            const onText = vi.fn();
+            const t = new SDKMessageTranslator({ onText });
+            await t.handle(assistantText("Hello "));
+            await t.handle(assistantText("world"));
+            expect(onText).toHaveBeenNthCalledWith(1, "Hello ");
+            expect(onText).toHaveBeenNthCalledWith(2, "world");
+        });
+        it("ignores non-assistant/non-user messages", async () => {
+            const onText = vi.fn();
+            const onToolCall = vi.fn();
+            const t = new SDKMessageTranslator({ onText, onToolCall });
+            await t.handle({ type: "system" });
+            await t.handle({ type: "result" });
+            await t.handle({ type: "stream_event" });
+            expect(onText).not.toHaveBeenCalled();
+            expect(onToolCall).not.toHaveBeenCalled();
+        });
+        it("does not emit onText for an assistant message with no text", async () => {
+            const onText = vi.fn();
+            const t = new SDKMessageTranslator({ onText });
+            await t.handle(assistantToolUse("t1", "Bash", { command: "ls" }));
+            expect(onText).not.toHaveBeenCalled();
+        });
+    });
+    describe("boundaries", () => {
+        it("emits a boundary between two consecutive assistant text turns", async () => {
+            const order = [];
+            const t = new SDKMessageTranslator({
+                onText: (text) => {
+                    order.push(`text:${text}`);
+                },
+                onBoundary: () => {
+                    order.push("boundary");
+                },
+            });
+            await t.handle(assistantText("first"));
+            await t.handle(assistantText("second"));
+            expect(order).toEqual(["text:first", "boundary", "text:second"]);
+        });
+        it("does not emit a boundary before the first text", async () => {
+            const onBoundary = vi.fn();
+            const t = new SDKMessageTranslator({ onText: vi.fn(), onBoundary });
+            await t.handle(assistantText("only"));
+            expect(onBoundary).not.toHaveBeenCalled();
+        });
+        it("does not emit a boundary for text that immediately follows a tool result", async () => {
+            const onBoundary = vi.fn();
+            const t = new SDKMessageTranslator({ onText: vi.fn(), onBoundary, onToolCall: vi.fn() });
+            await t.handle(assistantText("before tool"));
+            await t.handle(assistantToolUse("t1", "Read", { file_path: "/a" }));
+            await t.handle(toolResult("t1", "file contents"));
+            await t.handle(assistantText("after tool"));
+            // The tool result resets the text flag, so the post-tool text is NOT a boundary.
+            expect(onBoundary).not.toHaveBeenCalled();
+        });
+    });
+    describe("tool calls", () => {
+        it("pairs a tool_use with its result, including name, input summary and duration", async () => {
+            const calls = [];
+            let clock = 1000;
+            const t = new SDKMessageTranslator({ onToolCall: (c) => void calls.push(c) }, { now: () => clock });
+            await t.handle(assistantToolUse("t1", "Bash", { command: "echo hi" }));
+            clock = 1250; // 250ms later
+            await t.handle(toolResult("t1", "hi"));
+            expect(calls).toHaveLength(1);
+            expect(calls[0]).toEqual({
+                toolName: "Bash",
+                inputSummary: "echo hi",
+                output: "hi",
+                isError: false,
+                durationMs: 250,
+                toolUseId: "t1",
+            });
+        });
+        it("marks error results", async () => {
+            const calls = [];
+            const t = new SDKMessageTranslator({ onToolCall: (c) => void calls.push(c) });
+            await t.handle(assistantToolUse("t1", "Bash", { command: "false" }));
+            await t.handle(toolResult("t1", "boom", true));
+            expect(calls[0].isError).toBe(true);
+            expect(calls[0].output).toBe("boom");
+        });
+        it("falls back to 'Tool' when there is no matching tool_use", async () => {
+            const calls = [];
+            const t = new SDKMessageTranslator({ onToolCall: (c) => void calls.push(c) });
+            // Result arrives with no preceding tool_use of that id
+            await t.handle(toolResult("orphan", "result"));
+            expect(calls).toHaveLength(1);
+            expect(calls[0].toolName).toBe("Tool");
+            expect(calls[0].durationMs).toBeUndefined();
+            expect(calls[0].inputSummary).toBeUndefined();
+        });
+        it("does not emit tool calls when toolResults is false but still consumes pending uses", async () => {
+            const onToolCall = vi.fn();
+            const t = new SDKMessageTranslator({ onToolCall }, { toolResults: false });
+            await t.handle(assistantToolUse("t1", "Bash", { command: "ls" }));
+            await t.handle(toolResult("t1", "out"));
+            expect(onToolCall).not.toHaveBeenCalled();
+        });
+    });
+    describe("backpressure", () => {
+        it("awaits async handlers in order", async () => {
+            const order = [];
+            const t = new SDKMessageTranslator({
+                onText: async (text) => {
+                    await new Promise((r) => setTimeout(r, 5));
+                    order.push(`text:${text}`);
+                },
+                onBoundary: async () => {
+                    order.push("boundary");
+                },
+            });
+            await t.handle(assistantText("a"));
+            await t.handle(assistantText("b"));
+            expect(order).toEqual(["text:a", "boundary", "text:b"]);
+        });
+    });
+    describe("reset()", () => {
+        it("clears pending tool uses and text state", async () => {
+            const onBoundary = vi.fn();
+            const calls = [];
+            const t = new SDKMessageTranslator({
+                onText: vi.fn(),
+                onBoundary,
+                onToolCall: (c) => void calls.push(c),
+            });
+            await t.handle(assistantText("turn 1"));
+            await t.handle(assistantToolUse("t1", "Bash", { command: "x" }));
+            t.reset();
+            // After reset: previous text flag cleared (no boundary on next text)
+            await t.handle(assistantText("turn 2"));
+            expect(onBoundary).not.toHaveBeenCalled();
+            // After reset: the orphaned tool_use no longer pairs
+            await t.handle(toolResult("t1", "late"));
+            expect(calls[0].toolName).toBe("Tool");
+        });
+    });
+});
+describe("createSDKMessageHandler", () => {
+    it("returns an onMessage handler driving a fresh translator", async () => {
+        const onText = vi.fn();
+        const calls = [];
+        const handler = createSDKMessageHandler({
+            onText,
+            onToolCall: (c) => void calls.push(c),
+        });
+        await handler(assistantText("hi"));
+        await handler(assistantToolUse("t1", "Read", { file_path: "/f" }));
+        await handler(toolResult("t1", "contents"));
+        expect(onText).toHaveBeenCalledWith("hi");
+        expect(calls[0]).toMatchObject({ toolName: "Read", inputSummary: "/f", output: "contents" });
+    });
+});
+//# sourceMappingURL=sdk-message-translator.test.js.map

package/dist/__tests__/sdk-message-translator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-message-translator.test.js","sourceRoot":"","sources":["../../src/__tests__/sdk-message-translator.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { DEFAULT_MESSAGE_DELAY_MS, DEFAULT_SPLIT_POINTS, findSplitPoint, formatC
 export { StreamingResponder, type StreamingResponderOptions, } from "./streaming-responder.js";
 export { type ContentBlock, extractMessageContent, hasTextContent, isTextContentBlock, type SDKMessage, type TextContentBlock, } from "./message-extraction.js";
 export { extractToolResultContent, extractToolResults, extractToolUseBlocks, getToolInputSummary, TOOL_EMOJIS, type ToolResult, type ToolUseBlock, } from "./tool-parsing.js";
+export { createSDKMessageHandler, type SDKMessageHandlers, SDKMessageTranslator, type SDKMessageTranslatorOptions, type TranslatedToolCall, } from "./sdk-message-translator.js";
 export { checkDMUserFilter, type DMConfig, type DMFilterResult, getDMMode, isDMEnabled, shouldProcessInMode, } from "./dm-filter.js";
 export { AlreadyConnectedError, ChatConnectionError, ChatConnectorError, ChatErrorCode, InvalidTokenError, isAlreadyConnectedError, isChatConnectionError, isChatConnectorError, isInvalidTokenError, isMissingTokenError, MissingTokenError, } from "./errors.js";
 export { type ClassifiedError, ErrorCategory, isAuthError, isRateLimitError, isTransientError, type RetryOptions, type RetryResult, safeExecute, safeExecuteWithReply, USER_ERROR_MESSAGES, type UserErrorMessageKey, withRetry, } from "./error-handler.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAEL,KAAK,cAAc,EAEnB,oBAAoB,EAEpB,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,oBAAoB,EAEpB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,qBAAqB,EACrB,2BAA2B,EAE3B,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAMpC,YAAY,EAEV,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EAEnB,kBAAkB,EAClB,gBAAgB,EAEhB,mBAAmB,EAEnB,cAAc,EACd,mBAAmB,IAAI,4BAA4B,EAEnD,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAEL,wBAAwB,EACxB,oBAAoB,EAEpB,cAAc,EACd,eAAe,EAEf,KAAK,mBAAmB,EACxB,cAAc,EACd,UAAU,EACV,KAAK,WAAW,EAChB,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,KAAK,YAAY,EACjB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAElB,oBAAoB,EACpB,mBAAmB,EAEnB,WAAW,EACX,KAAK,UAAU,EAEf,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,iBAAiB,EACjB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EAEnB,kBAAkB,EAElB,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EAErB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAMrB,OAAO,EAEL,KAAK,eAAe,EAEpB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,WAAW,EACX,oBAAoB,EAEpB,mBAAmB,EACnB,KAAK,mBAAmB,EAExB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAM5B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAEL,KAAK,cAAc,EAEnB,oBAAoB,EAEpB,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,oBAAoB,EAEpB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,qBAAqB,EACrB,2BAA2B,EAE3B,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAMpC,YAAY,EAEV,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EAEnB,kBAAkB,EAClB,gBAAgB,EAEhB,mBAAmB,EAEnB,cAAc,EACd,mBAAmB,IAAI,4BAA4B,EAEnD,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAEL,wBAAwB,EACxB,oBAAoB,EAEpB,cAAc,EACd,eAAe,EAEf,KAAK,mBAAmB,EACxB,cAAc,EACd,UAAU,EACV,KAAK,WAAW,EAChB,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EACL,KAAK,YAAY,EACjB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAElB,oBAAoB,EACpB,mBAAmB,EAEnB,WAAW,EACX,KAAK,UAAU,EAEf,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAEL,uBAAuB,EACvB,KAAK,kBAAkB,EAEvB,oBAAoB,EACpB,KAAK,2BAA2B,EAEhC,KAAK,kBAAkB,GACxB,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EACL,iBAAiB,EACjB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EAEnB,kBAAkB,EAElB,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EAErB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAMrB,OAAO,EAEL,KAAK,eAAe,EAEpB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,WAAW,EACX,oBAAoB,EAEpB,mBAAmB,EACnB,KAAK,mBAAmB,EAExB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAM5B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -47,6 +47,14 @@ extractToolUseBlocks, getToolInputSummary,
 // Constants
 TOOL_EMOJIS, } from "./tool-parsing.js";
 // =============================================================================
+// SDK Message Translation
+// =============================================================================
+export { 
+// Factory
+createSDKMessageHandler, 
+// Class
+SDKMessageTranslator, } from "./sdk-message-translator.js";
+// =============================================================================
 // DM Filtering
 // =============================================================================
 export { checkDMUserFilter, getDMMode, isDMEnabled, shouldProcessInMode, } from "./dm-filter.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,OAAO;AAGL,UAAU;AACV,oBAAoB;AACpB,QAAQ;AACR,kBAAkB,EAGlB,sBAAsB,EACtB,oBAAoB;AACpB,oBAAoB;AACpB,yBAAyB,EAEzB,qBAAqB,EACrB,2BAA2B;AAC3B,SAAS;AACT,gBAAgB,EAChB,mBAAmB,EAGnB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAyBpC,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,OAAO;AACL,YAAY;AACZ,wBAAwB,EACxB,oBAAoB;AACpB,YAAY;AACZ,cAAc,EACd,eAAe,EAGf,cAAc,EACd,UAAU,EAEV,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAElC,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,OAAO,EAEL,qBAAqB,EACrB,cAAc,EACd,kBAAkB,GAGnB,MAAM,yBAAyB,CAAC;AAEjC,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF,OAAO,EACL,wBAAwB,EACxB,kBAAkB;AAClB,YAAY;AACZ,oBAAoB,EACpB,mBAAmB;AACnB,YAAY;AACZ,WAAW,GAIZ,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EAGjB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,SAAS;AACT,gFAAgF;AAEhF,OAAO,EACL,qBAAqB,EACrB,mBAAmB;AACnB,gBAAgB;AAChB,kBAAkB;AAClB,cAAc;AACd,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB;AACrB,cAAc;AACd,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,OAAO;AAGL,aAAa;AACb,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAGhB,WAAW,EACX,oBAAoB;AACpB,YAAY;AACZ,mBAAmB;AAEnB,YAAY;AACZ,SAAS,GACV,MAAM,oBAAoB,CAAC;AAE5B,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,OAAO;AAGL,UAAU;AACV,oBAAoB;AACpB,QAAQ;AACR,kBAAkB,EAGlB,sBAAsB,EACtB,oBAAoB;AACpB,oBAAoB;AACpB,yBAAyB,EAEzB,qBAAqB,EACrB,2BAA2B;AAC3B,SAAS;AACT,gBAAgB,EAChB,mBAAmB,EAGnB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAyBpC,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,OAAO;AACL,YAAY;AACZ,wBAAwB,EACxB,oBAAoB;AACpB,YAAY;AACZ,cAAc,EACd,eAAe,EAGf,cAAc,EACd,UAAU,EAEV,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAElC,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,OAAO,EAEL,qBAAqB,EACrB,cAAc,EACd,kBAAkB,GAGnB,MAAM,yBAAyB,CAAC;AAEjC,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF,OAAO,EACL,wBAAwB,EACxB,kBAAkB;AAClB,YAAY;AACZ,oBAAoB,EACpB,mBAAmB;AACnB,YAAY;AACZ,WAAW,GAIZ,MAAM,mBAAmB,CAAC;AAE3B,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF,OAAO;AACL,UAAU;AACV,uBAAuB;AAEvB,QAAQ;AACR,oBAAoB,GAIrB,MAAM,6BAA6B,CAAC;AAErC,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EAGjB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,SAAS;AACT,gFAAgF;AAEhF,OAAO,EACL,qBAAqB,EACrB,mBAAmB;AACnB,gBAAgB;AAChB,kBAAkB;AAClB,cAAc;AACd,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB;AACrB,cAAc;AACd,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,OAAO;AAGL,aAAa;AACb,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAGhB,WAAW,EACX,oBAAoB;AACpB,YAAY;AACZ,mBAAmB;AAEnB,YAAY;AACZ,SAAS,GACV,MAAM,oBAAoB,CAAC;AAE5B,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,GACf,MAAM,wBAAwB,CAAC"}

package/dist/sdk-message-translator.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Transport-agnostic SDKMessage → chat-event translation
+ *
+ * Every chat surface built on herdctl (Discord, Slack, the web dashboard, and
+ * downstream apps like paddock) consumes the same stream of `SDKMessage`s from
+ * `FleetManager.trigger({ onMessage })` and turns it into the same handful of
+ * UI events:
+ *   - assistant text deltas,
+ *   - a boundary between distinct assistant turns,
+ *   - paired tool calls (a `tool_use` matched to its later `tool_result`,
+ *     enriched with an input summary and a wall-clock duration).
+ *
+ * That translation was previously reimplemented per connector (see
+ * `@herdctl/web`'s WebChatManager and paddock's `ws.ts`). This module extracts
+ * it into one stateful translator so transports only have to supply the
+ * destination handlers.
+ *
+ * @module sdk-message-translator
+ */
+import { type SDKMessage } from "./message-extraction.js";
+/**
+ * A paired tool call: a `tool_use` block matched with its `tool_result`.
+ */
+export interface TranslatedToolCall {
+    /** Tool name (e.g. "Bash", "Read"); "Tool" if the pairing could not be resolved */
+    toolName: string;
+    /** Human-readable summary of the tool input (e.g. the bash command or file path) */
+    inputSummary?: string;
+    /** Tool output text (may be empty) */
+    output: string;
+    /** Whether the tool reported an error */
+    isError: boolean;
+    /** Wall-clock duration between the tool_use and its result, in milliseconds */
+    durationMs?: number;
+    /** The originating tool_use id, when present */
+    toolUseId?: string;
+}
+/**
+ * Handlers invoked as SDK messages are translated. All are optional and may be
+ * async; the translator awaits them in order so transports can apply
+ * backpressure (e.g. a slow WebSocket send).
+ */
+export interface SDKMessageHandlers {
+    /** Called with each assistant text delta as it streams in. */
+    onText?: (text: string) => void | Promise<void>;
+    /**
+     * Called when a new assistant turn begins after a previous one produced text
+     * (or after a tool call interrupts the text), so transports can split bubbles.
+     */
+    onBoundary?: () => void | Promise<void>;
+    /** Called once per tool result, paired with its originating tool_use. */
+    onToolCall?: (toolCall: TranslatedToolCall) => void | Promise<void>;
+}
+/**
+ * Options for {@link SDKMessageTranslator}.
+ */
+export interface SDKMessageTranslatorOptions {
+    /**
+     * Emit tool calls via `onToolCall`. When `false`, tool_use blocks are still
+     * tracked (so boundaries stay correct) but no `onToolCall` is fired.
+     * Defaults to `true`.
+     */
+    toolResults?: boolean;
+    /**
+     * Clock used for duration measurement. Injectable for deterministic tests.
+     * Defaults to `Date.now`.
+     */
+    now?: () => number;
+}
+/**
+ * Stateful translator from the Claude Agent SDK message stream to chat-UI events.
+ *
+ * Feed every `SDKMessage` from a trigger's `onMessage` callback into
+ * {@link SDKMessageTranslator.handle}; it extracts assistant text, tracks
+ * `tool_use` blocks so they can be paired with their later `tool_result`s, and
+ * emits boundaries between distinct assistant turns.
+ *
+ * One instance corresponds to one trigger/turn (it holds per-turn state such as
+ * pending tool uses). Create a fresh translator per `trigger()` call.
+ *
+ * @example
+ * ```typescript
+ * const translator = new SDKMessageTranslator({
+ *   onText: (t) => ws.send({ type: "chat:response", text: t }),
+ *   onToolCall: (c) => ws.send({ type: "chat:tool_call", ...c }),
+ *   onBoundary: () => ws.send({ type: "chat:boundary" }),
+ * });
+ *
+ * await fleet.trigger("agent", undefined, {
+ *   prompt,
+ *   onMessage: (m) => translator.handle(m),
+ * });
+ * ```
+ */
+export declare class SDKMessageTranslator {
+    private readonly handlers;
+    private readonly toolResults;
+    private readonly now;
+    /** tool_use id -> pending call awaiting its result */
+    private readonly pendingToolUses;
+    /** Whether the current assistant turn has already emitted text */
+    private hasAssistantText;
+    constructor(handlers: SDKMessageHandlers, options?: SDKMessageTranslatorOptions);
+    /**
+     * Translate a single SDK message, invoking the configured handlers.
+     *
+     * Safe to call with any SDK message type — non-assistant/non-user messages
+     * (system, result, stream events, etc.) are ignored.
+     *
+     * @param message - One message from the trigger's `onMessage` stream
+     */
+    handle(message: SDKMessage): Promise<void>;
+    /**
+     * Reset per-turn state. Call between reused turns if you keep one translator
+     * across multiple triggers (not required when creating one per trigger).
+     */
+    reset(): void;
+    private handleAssistant;
+    private handleUser;
+}
+/**
+ * Build an `onMessage` callback that drives a fresh {@link SDKMessageTranslator}.
+ *
+ * Convenience for the common case: pass the returned function straight to
+ * `FleetManager.trigger({ onMessage })`. Creates one translator bound to the
+ * given handlers, so this represents a single trigger/turn.
+ *
+ * @param handlers - Destination handlers for text/boundary/tool events
+ * @param options - Translator options (toolResults toggle, injectable clock)
+ * @returns An async `onMessage` handler suitable for `TriggerOptions.onMessage`
+ *
+ * @example
+ * ```typescript
+ * await fleet.trigger("agent", undefined, {
+ *   prompt,
+ *   onMessage: createSDKMessageHandler({
+ *     onText: (t) => stream(t),
+ *     onToolCall: (c) => renderTool(c),
+ *   }),
+ * });
+ * ```
+ */
+export declare function createSDKMessageHandler(handlers: SDKMessageHandlers, options?: SDKMessageTranslatorOptions): (message: SDKMessage) => Promise<void>;
+//# sourceMappingURL=sdk-message-translator.d.ts.map

package/dist/sdk-message-translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-message-translator.d.ts","sourceRoot":"","sources":["../src/sdk-message-translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAOjF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,yEAAyE;IACzE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,kEAAkE;IAClE,OAAO,CAAC,gBAAgB,CAAS;gBAErB,QAAQ,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,2BAA2B;IAM/E;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD;;;OAGG;IACH,KAAK,IAAI,IAAI;YAOC,eAAe;YAyBf,UAAU;CAqCzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,2BAA2B,GACpC,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAGxC"}

package/dist/sdk-message-translator.js

@@ -0,0 +1,167 @@
+/**
+ * Transport-agnostic SDKMessage → chat-event translation
+ *
+ * Every chat surface built on herdctl (Discord, Slack, the web dashboard, and
+ * downstream apps like paddock) consumes the same stream of `SDKMessage`s from
+ * `FleetManager.trigger({ onMessage })` and turns it into the same handful of
+ * UI events:
+ *   - assistant text deltas,
+ *   - a boundary between distinct assistant turns,
+ *   - paired tool calls (a `tool_use` matched to its later `tool_result`,
+ *     enriched with an input summary and a wall-clock duration).
+ *
+ * That translation was previously reimplemented per connector (see
+ * `@herdctl/web`'s WebChatManager and paddock's `ws.ts`). This module extracts
+ * it into one stateful translator so transports only have to supply the
+ * destination handlers.
+ *
+ * @module sdk-message-translator
+ */
+import { extractMessageContent } from "./message-extraction.js";
+import { extractToolResults, extractToolUseBlocks, getToolInputSummary } from "./tool-parsing.js";
+/**
+ * Stateful translator from the Claude Agent SDK message stream to chat-UI events.
+ *
+ * Feed every `SDKMessage` from a trigger's `onMessage` callback into
+ * {@link SDKMessageTranslator.handle}; it extracts assistant text, tracks
+ * `tool_use` blocks so they can be paired with their later `tool_result`s, and
+ * emits boundaries between distinct assistant turns.
+ *
+ * One instance corresponds to one trigger/turn (it holds per-turn state such as
+ * pending tool uses). Create a fresh translator per `trigger()` call.
+ *
+ * @example
+ * ```typescript
+ * const translator = new SDKMessageTranslator({
+ *   onText: (t) => ws.send({ type: "chat:response", text: t }),
+ *   onToolCall: (c) => ws.send({ type: "chat:tool_call", ...c }),
+ *   onBoundary: () => ws.send({ type: "chat:boundary" }),
+ * });
+ *
+ * await fleet.trigger("agent", undefined, {
+ *   prompt,
+ *   onMessage: (m) => translator.handle(m),
+ * });
+ * ```
+ */
+export class SDKMessageTranslator {
+    handlers;
+    toolResults;
+    now;
+    /** tool_use id -> pending call awaiting its result */
+    pendingToolUses = new Map();
+    /** Whether the current assistant turn has already emitted text */
+    hasAssistantText = false;
+    constructor(handlers, options) {
+        this.handlers = handlers;
+        this.toolResults = options?.toolResults ?? true;
+        this.now = options?.now ?? Date.now;
+    }
+    /**
+     * Translate a single SDK message, invoking the configured handlers.
+     *
+     * Safe to call with any SDK message type — non-assistant/non-user messages
+     * (system, result, stream events, etc.) are ignored.
+     *
+     * @param message - One message from the trigger's `onMessage` stream
+     */
+    async handle(message) {
+        if (message.type === "assistant") {
+            await this.handleAssistant(message);
+        }
+        else if (message.type === "user") {
+            await this.handleUser(message);
+        }
+    }
+    /**
+     * Reset per-turn state. Call between reused turns if you keep one translator
+     * across multiple triggers (not required when creating one per trigger).
+     */
+    reset() {
+        this.pendingToolUses.clear();
+        this.hasAssistantText = false;
+    }
+    // ---------------------------------------------------------------------------
+    async handleAssistant(message) {
+        const content = extractMessageContent(message);
+        if (content) {
+            // A new assistant turn after a previous one produced text → boundary.
+            if (this.hasAssistantText) {
+                this.hasAssistantText = false;
+                await this.handlers.onBoundary?.();
+            }
+            this.hasAssistantText = true;
+            await this.handlers.onText?.(content);
+        }
+        // Track tool_use blocks so we can pair them with results later. We track
+        // even when toolResults is disabled so boundary handling stays correct.
+        for (const block of extractToolUseBlocks(message)) {
+            if (block.id) {
+                this.pendingToolUses.set(block.id, {
+                    name: block.name,
+                    input: block.input,
+                    startTime: this.now(),
+                });
+            }
+        }
+    }
+    async handleUser(message) {
+        const results = extractToolResults(message);
+        if (results.length === 0) {
+            return;
+        }
+        // A tool result ends the current text run; the next assistant text is a new
+        // bubble. Drop the text flag so we don't emit a spurious boundary, but the
+        // transport already received the text via onText.
+        this.hasAssistantText = false;
+        if (!this.toolResults || !this.handlers.onToolCall) {
+            // Still consume pending tool uses so the map doesn't leak.
+            for (const result of results) {
+                if (result.toolUseId)
+                    this.pendingToolUses.delete(result.toolUseId);
+            }
+            return;
+        }
+        for (const result of results) {
+            const toolUse = result.toolUseId ? this.pendingToolUses.get(result.toolUseId) : undefined;
+            if (result.toolUseId) {
+                this.pendingToolUses.delete(result.toolUseId);
+            }
+            await this.handlers.onToolCall({
+                toolName: toolUse?.name ?? "Tool",
+                inputSummary: toolUse ? getToolInputSummary(toolUse.name, toolUse.input) : undefined,
+                output: result.output,
+                isError: result.isError,
+                durationMs: toolUse ? this.now() - toolUse.startTime : undefined,
+                toolUseId: result.toolUseId,
+            });
+        }
+    }
+}
+/**
+ * Build an `onMessage` callback that drives a fresh {@link SDKMessageTranslator}.
+ *
+ * Convenience for the common case: pass the returned function straight to
+ * `FleetManager.trigger({ onMessage })`. Creates one translator bound to the
+ * given handlers, so this represents a single trigger/turn.
+ *
+ * @param handlers - Destination handlers for text/boundary/tool events
+ * @param options - Translator options (toolResults toggle, injectable clock)
+ * @returns An async `onMessage` handler suitable for `TriggerOptions.onMessage`
+ *
+ * @example
+ * ```typescript
+ * await fleet.trigger("agent", undefined, {
+ *   prompt,
+ *   onMessage: createSDKMessageHandler({
+ *     onText: (t) => stream(t),
+ *     onToolCall: (c) => renderTool(c),
+ *   }),
+ * });
+ * ```
+ */
+export function createSDKMessageHandler(handlers, options) {
+    const translator = new SDKMessageTranslator(handlers, options);
+    return (message) => translator.handle(message);
+}
+//# sourceMappingURL=sdk-message-translator.js.map

package/dist/sdk-message-translator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-message-translator.js","sourceRoot":"","sources":["../src/sdk-message-translator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herdctl/chat",
-  "version": "0.3.14",
+  "version": "0.4.0",
   "description": "Shared chat infrastructure for herdctl connectors",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,7 @@
   "dependencies": {
     "yaml": "^2.3.0",
     "zod": "^3.22.0",
-    "@herdctl/core": "5.10.1"
+    "@herdctl/core": "5.11.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",