@kortyx/agent 0.2.0

package/dist/orchestrator.js

@@ -0,0 +1,391 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orchestrateGraphStream = orchestrateGraphStream;
+const memory_1 = require("@kortyx/memory");
+const runtime_1 = require("@kortyx/runtime");
+const langgraph_1 = require("@langchain/langgraph");
+const stream_1 = require("stream");
+const transform_graph_stream_for_ui_1 = require("./stream/transform-graph-stream-for-ui");
+async function orchestrateGraphStream({ sessionId, graph, state, config, saveMemory, selectWorkflow, }) {
+    const out = new stream_1.PassThrough({ objectMode: true });
+    let currentGraph = graph;
+    let currentState = state;
+    let finished = false;
+    try {
+        const sid = config?.session?.id;
+        if (sid && typeof sid === "string") {
+            out.write({ type: "session", sessionId: sid });
+        }
+    }
+    catch { }
+    const pending = {
+        to: null,
+        payload: {},
+    };
+    const streamedNodes = new Set();
+    let lastStatusMsg = "";
+    let lastStatusAt = 0;
+    let pendingRecordToken = null;
+    let activeIsResume = false;
+    let wroteHumanInput = false;
+    const forwardEmit = (event, payload) => {
+        if (event === "error") {
+            const msg = String(payload?.message ?? "Unexpected error");
+            out.write({ type: "error", message: msg });
+            out.write({ type: "done" });
+            finished = true;
+            out.end();
+            return;
+        }
+        if (event === "status") {
+            const msg = String(payload?.message ?? "");
+            const now = Date.now();
+            if (msg && msg === lastStatusMsg && now - lastStatusAt < 250)
+                return;
+            lastStatusMsg = msg;
+            lastStatusAt = now;
+            out.write({ type: "status", message: msg });
+            return;
+        }
+        if (event === "text-start") {
+            const node = payload?.node;
+            if (!node)
+                return;
+            out.write({ type: "text-start", node });
+            streamedNodes.add(node);
+            return;
+        }
+        if (event === "text-delta") {
+            const node = payload?.node;
+            const delta = String(payload?.delta ?? "");
+            if (!node || !delta)
+                return;
+            out.write({ type: "text-delta", delta, node });
+            streamedNodes.add(node);
+            return;
+        }
+        if (event === "text-end") {
+            const node = payload?.node;
+            if (!node)
+                return;
+            out.write({ type: "text-end", node });
+            return;
+        }
+        if (event === "message") {
+            const node = payload?.node;
+            const text = String(payload?.content ?? "");
+            out.write({ type: "message", node, content: text });
+            return;
+        }
+        if (event === "structured_data") {
+            out.write({
+                type: "structured-data",
+                node: payload?.node,
+                dataType: payload?.dataType,
+                data: payload?.data,
+            });
+            return;
+        }
+        if (event === "transition") {
+            out.write({
+                type: "transition",
+                transitionTo: payload?.transitionTo,
+                payload: payload?.payload ?? {},
+            });
+            pending.to = payload?.transitionTo ?? null;
+            pending.payload =
+                payload?.payload ?? {};
+            return;
+        }
+        if (event === "interrupt") {
+            if (activeIsResume)
+                return;
+            try {
+                const p = payload;
+                console.log(`[orchestrator] interrupt node=${p?.node} workflow=${p?.workflow} options=${Array.isArray(p?.input?.options) ? p.input.options.length : 0}`);
+            }
+            catch { }
+            const p = payload;
+            const local = {
+                node: p?.node,
+                workflow: p?.workflow,
+                input: p?.input,
+            };
+            const token = (0, runtime_1.makeResumeToken)();
+            const requestId = (0, runtime_1.makeRequestId)("human");
+            pendingRecordToken = token;
+            const options = Array.isArray(local.input?.options)
+                ? local.input.options
+                : [];
+            const kind = local.input?.kind ||
+                (local.input?.multiple ? "multi-choice" : "choice");
+            const isText = kind === "text";
+            const record = {
+                token,
+                requestId,
+                sessionId: sessionId,
+                workflow: local.workflow || currentState.currentWorkflow,
+                node: local.node || "",
+                state: { ...currentState, awaitingHumanInput: true },
+                schema: isText
+                    ? {
+                        kind: kind,
+                        multiple: Boolean(local.input?.multiple),
+                        ...(local.input?.question
+                            ? { question: local.input.question }
+                            : {}),
+                    }
+                    : {
+                        kind: kind,
+                        multiple: Boolean(local.input?.multiple),
+                        question: String(local.input?.question || "Please choose an option."),
+                    },
+                options: options.map((o) => ({
+                    id: String(o.id),
+                    label: String(o.label),
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    value: o.value,
+                })),
+                createdAt: Date.now(),
+                ttlMs: 15 * 60 * 1000,
+            };
+            (0, memory_1.savePendingRequest)(record);
+            out.write({
+                type: "interrupt",
+                requestId: record.requestId,
+                resumeToken: record.token,
+                workflow: record.workflow,
+                node: record.node,
+                input: {
+                    kind: record.schema.kind,
+                    multiple: record.schema.multiple,
+                    question: record.schema.question,
+                    options: record.options.map((o) => ({
+                        id: o.id,
+                        label: o.label,
+                        description: o.description,
+                    })),
+                },
+            });
+            wroteHumanInput = true;
+            return;
+        }
+    };
+    (async () => {
+        while (true) {
+            let workflowFinalState = null;
+            currentGraph.config = currentGraph.config || {};
+            currentGraph.config.emit = forwardEmit;
+            const threadId = currentGraph.config?.session?.id ||
+                sessionId ||
+                "anonymous-session";
+            out.write({
+                type: "status",
+                message: `🧵 thread_id=${threadId} workflow=${currentState.currentWorkflow}`,
+            });
+            const isResume = Boolean(currentGraph.config?.resume);
+            activeIsResume = isResume;
+            const resumeUpdate = currentGraph.config?.resumeUpdate;
+            const resumeValue = currentGraph.config?.resumeValue;
+            const invokeState = isResume
+                ? resumeValue !== undefined
+                    ? new langgraph_1.Command({ resume: resumeValue })
+                    : resumeUpdate
+                        ? new langgraph_1.Command({ update: resumeUpdate })
+                        : null
+                : currentState;
+            const runtimeStream = currentGraph.streamEvents(invokeState, {
+                version: "v2",
+                configurable: {
+                    thread_id: threadId,
+                    checkpoint_ns: String(currentState.currentWorkflow || "default"),
+                },
+            });
+            try {
+                out.write({
+                    type: "status",
+                    message: `▶️ streamEvents invoke: resume=${Boolean(currentGraph.config?.resume)} thread_id=${threadId} ns=${String(currentState.currentWorkflow || "default")}`,
+                });
+            }
+            catch { }
+            const uiStream = (0, transform_graph_stream_for_ui_1.transformGraphStreamForUI)(runtimeStream, {
+                debug: Boolean(config?.features?.tracing),
+            });
+            let loopTransitionTo = null;
+            let loopTransitionPayload = {};
+            for await (const chunk of uiStream) {
+                if (finished)
+                    break;
+                const node = chunk.node;
+                if (chunk.type === "interrupt" &&
+                    (!chunk.resumeToken || !chunk.requestId)) {
+                    if (wroteHumanInput) {
+                        continue;
+                    }
+                    const hi = chunk;
+                    const token = (0, runtime_1.makeResumeToken)();
+                    const requestId = (0, runtime_1.makeRequestId)("human");
+                    pendingRecordToken = token;
+                    const options = Array.isArray(hi.input?.options)
+                        ? hi.input.options
+                        : [];
+                    const kind = hi.input?.kind || (hi.input?.multiple ? "multi-choice" : "choice");
+                    const isText = kind === "text";
+                    const record = {
+                        token,
+                        requestId,
+                        sessionId: sessionId,
+                        workflow: currentState.currentWorkflow,
+                        node: node || "",
+                        state: {
+                            ...currentState,
+                            awaitingHumanInput: true,
+                        },
+                        schema: isText
+                            ? {
+                                kind: kind,
+                                multiple: Boolean(hi.input?.multiple),
+                                ...(hi.input?.question
+                                    ? { question: hi.input.question }
+                                    : {}),
+                            }
+                            : {
+                                kind: kind,
+                                multiple: Boolean(hi.input?.multiple),
+                                question: String(hi.input?.question || "Please choose an option."),
+                            },
+                        options: options.map((o) => ({
+                            id: String(o.id),
+                            label: String(o.label),
+                            description: typeof o.description === "string" ? o.description : undefined,
+                            value: o.value,
+                        })),
+                        createdAt: Date.now(),
+                        ttlMs: 15 * 60 * 1000,
+                    };
+                    (0, memory_1.savePendingRequest)(record);
+                    out.write({
+                        type: "interrupt",
+                        requestId,
+                        resumeToken: token,
+                        workflow: record.workflow,
+                        node: record.node,
+                        input: {
+                            kind: record.schema.kind,
+                            multiple: record.schema.multiple,
+                            question: record.schema.question,
+                            options: record.options.map((o) => ({
+                                id: o.id,
+                                label: o.label,
+                                description: o.description,
+                            })),
+                        },
+                    });
+                    wroteHumanInput = true;
+                    continue;
+                }
+                if (chunk.type === "text-delta") {
+                    if (typeof chunk.delta === "string" && chunk.delta.length > 60) {
+                        const text = chunk.delta;
+                        for (let i = 0; i < text.length; i += 60) {
+                            out.write({
+                                type: "text-delta",
+                                delta: text.slice(i, i + 60),
+                                node,
+                            });
+                        }
+                        if (node)
+                            streamedNodes.add(node);
+                    }
+                    else {
+                        out.write(chunk);
+                        if (node)
+                            streamedNodes.add(node);
+                    }
+                }
+                else {
+                    out.write(chunk);
+                }
+                if (saveMemory && sessionId && chunk.type !== "status") {
+                    await saveMemory(sessionId, { ...currentState });
+                }
+                if (chunk.type === "transition") {
+                    loopTransitionTo = String(chunk.transitionTo || "");
+                    loopTransitionPayload = chunk.payload ?? {};
+                    break;
+                }
+                if (chunk.type === "done") {
+                    workflowFinalState = chunk.data ?? null;
+                    break;
+                }
+            }
+            if (finished)
+                return;
+            const transitionTo = loopTransitionTo || pending.to;
+            const transitionPayload = Object.keys(loopTransitionPayload).length
+                ? loopTransitionPayload
+                : pending.payload;
+            pending.to = null;
+            pending.payload = {};
+            if (transitionTo) {
+                try {
+                    const nextWorkflow = await selectWorkflow(transitionTo);
+                    const nextGraph = await (0, runtime_1.createLangGraph)(nextWorkflow, {
+                        ...config,
+                        emit: forwardEmit,
+                    });
+                    const mergedData = {
+                        ...(workflowFinalState?.data ?? currentState.data ?? {}),
+                        ...(transitionPayload ?? {}),
+                    };
+                    const newInput = typeof transitionPayload?.rawInput ===
+                        "string"
+                        ? transitionPayload
+                            .rawInput
+                        : currentState.input;
+                    currentState = {
+                        ...currentState,
+                        currentWorkflow: transitionTo,
+                        input: newInput,
+                        data: mergedData,
+                        ui: {},
+                    };
+                    if (saveMemory && sessionId) {
+                        await saveMemory(sessionId, currentState);
+                    }
+                    currentGraph = nextGraph;
+                    continue;
+                }
+                catch (err) {
+                    out.write({
+                        type: "status",
+                        message: `⚠️ Transition failed to '${transitionTo}': ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                    out.end();
+                    return;
+                }
+            }
+            if (workflowFinalState) {
+                if (workflowFinalState && pendingRecordToken) {
+                    (0, memory_1.updatePendingRequest)(pendingRecordToken, {
+                        state: workflowFinalState,
+                    });
+                }
+                finished = true;
+                out.write({ type: "done", data: workflowFinalState });
+                out.end();
+                return;
+            }
+            if (!finished) {
+                out.write({ type: "done" });
+                out.end();
+            }
+            return;
+        }
+    })().catch((err) => {
+        console.error("[error:orchestrateGraphStream]", err);
+        out.write({ type: "status", message: `Error: ${err.message}` });
+        out.end();
+    });
+    return out;
+}

package/dist/stream/transform-graph-stream-for-ui.d.ts

@@ -0,0 +1,10 @@
+import type { StreamChunk } from "@kortyx/stream";
+import type { StreamEvent } from "@langchain/core/tracers/log_stream";
+interface TransformOptions {
+    debug?: boolean;
+    visibleNodes?: string[];
+    forwardModelStream?: boolean;
+}
+export declare function transformGraphStreamForUI(stream: AsyncIterable<StreamEvent>, options?: TransformOptions): AsyncGenerator<StreamChunk>;
+export {};
+//# sourceMappingURL=transform-graph-stream-for-ui.d.ts.map

package/dist/stream/transform-graph-stream-for-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-graph-stream-for-ui.d.ts","sourceRoot":"","sources":["../../src/stream/transform-graph-stream-for-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEtE,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AASD,wBAAuB,yBAAyB,CAC9C,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,EAClC,OAAO,GAAE,gBAAqB,GAC7B,cAAc,CAAC,WAAW,CAAC,CAgO7B"}

package/dist/stream/transform-graph-stream-for-ui.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformGraphStreamForUI = transformGraphStreamForUI;
+const utils_1 = require("@kortyx/utils");
+async function* transformGraphStreamForUI(stream, options = {}) {
+    const { debug = false, forwardModelStream = false } = options;
+    let currentNode = null;
+    const streamedTextByNode = new Map();
+    const startedNodes = new Set();
+    const endedNodes = new Set();
+    let sawInterrupt = false;
+    function findChoiceSchema(obj) {
+        try {
+            if (!obj || typeof obj !== "object")
+                return null;
+            if (typeof obj.kind === "string" &&
+                (obj.kind === "choice" || obj.kind === "multi-choice") &&
+                Array.isArray(obj.options)) {
+                return obj;
+            }
+            for (const v of Object.values(obj)) {
+                const inner = findChoiceSchema(v);
+                if (inner)
+                    return inner;
+            }
+        }
+        catch { }
+        return null;
+    }
+    for await (const event of stream) {
+        const { event: type, name, data } = event ?? {};
+        if (debug)
+            console.log(`[debug:event]`, JSON.stringify(event, null, 2));
+        switch (type) {
+            case "on_chain_start":
+                if (name && !name.startsWith("ChannelWrite")) {
+                    currentNode = name;
+                    if (name === "__start__" || name === "__end__")
+                        break;
+                    if (startedNodes.has(name))
+                        break;
+                    startedNodes.add(name);
+                    if (debug)
+                        console.log(`[debug:start] node=${name}`);
+                    yield { type: "status", message: `Processing node: ${name}` };
+                }
+                break;
+            case "on_graph_interrupt": {
+                sawInterrupt = true;
+                if (debug)
+                    console.log(`[debug:on_graph_interrupt]`, JSON.stringify({ name, data }, null, 2));
+                const where = (typeof name === "string" && name) ||
+                    data?.node ||
+                    "unknown";
+                const schema = findChoiceSchema(data);
+                if (schema) {
+                    const isText = schema.kind === "text";
+                    const options = Array.isArray(schema.options)
+                        ? schema.options
+                            .map((o) => ({
+                            id: String(o.id ?? ""),
+                            label: String(o.label ?? ""),
+                            ...(o.description
+                                ? { description: String(o.description) }
+                                : {}),
+                        }))
+                            .filter((o) => o.id && o.label)
+                        : [];
+                    yield {
+                        type: "interrupt",
+                        requestId: "",
+                        resumeToken: "",
+                        node: typeof where === "string" ? where : undefined,
+                        input: {
+                            kind: schema.kind,
+                            multiple: Boolean(schema.multiple),
+                            ...(isText
+                                ? { question: schema.question }
+                                : {
+                                    question: typeof schema.question === "string"
+                                        ? schema.question
+                                        : "Please choose",
+                                }),
+                            ...(options.length > 0 ? { options } : {}),
+                        },
+                    };
+                }
+                else {
+                    yield { type: "status", message: `⏸️ Interrupted at: ${where}` };
+                }
+                break;
+            }
+            case "on_chat_model_stream":
+                if (forwardModelStream && data?.chunk?.content) {
+                    if (currentNode && !streamedTextByNode.get(currentNode)) {
+                        yield { type: "text-start", node: currentNode };
+                        streamedTextByNode.set(currentNode, true);
+                    }
+                    const delta = (0, utils_1.contentToText)(data.chunk.content);
+                    if (delta) {
+                        yield {
+                            type: "text-delta",
+                            delta,
+                            node: currentNode ?? "ai",
+                        };
+                    }
+                }
+                break;
+            case "on_chain_end": {
+                const nodeName = name;
+                const output = data?.output;
+                if (debug)
+                    console.log(`[debug:on_chain_end:${nodeName}] output=`, JSON.stringify(output, null, 2));
+                if (!output || nodeName?.startsWith("ChannelWrite"))
+                    break;
+                if (nodeName && streamedTextByNode.get(nodeName)) {
+                    yield { type: "text-end", node: nodeName };
+                    streamedTextByNode.delete(nodeName);
+                }
+                if (nodeName !== "__start__" && nodeName !== "__end__") {
+                    if (!endedNodes.has(nodeName)) {
+                        yield { type: "status", message: `✅ Completed node: ${nodeName}` };
+                        endedNodes.add(nodeName);
+                    }
+                }
+                currentNode = null;
+                break;
+            }
+            case "on_graph_end": {
+                if (debug)
+                    console.log(`[debug:on_graph_end]`, JSON.stringify(data, null, 2));
+                const out = data?.output ?? null;
+                const interrupts = out && out.__interrupt__;
+                if (interrupts && Array.isArray(interrupts) && interrupts.length > 0) {
+                    const first = interrupts[0];
+                    const val = first?.value ?? first;
+                    const schema = findChoiceSchema(val);
+                    if (schema && Array.isArray(schema.options)) {
+                        const isText = schema.kind === "text";
+                        const options = Array.isArray(schema.options)
+                            ? schema.options
+                                .map((o) => ({
+                                id: String(o.id ?? ""),
+                                label: String(o.label ?? ""),
+                                ...(o.description
+                                    ? { description: String(o.description) }
+                                    : {}),
+                            }))
+                                .filter((o) => o.id && o.label)
+                            : [];
+                        yield {
+                            type: "interrupt",
+                            requestId: "",
+                            resumeToken: "",
+                            input: {
+                                kind: schema.kind,
+                                multiple: Boolean(schema.multiple),
+                                ...(isText
+                                    ? { question: schema.question }
+                                    : {
+                                        question: typeof schema.question === "string"
+                                            ? schema.question
+                                            : "Please choose",
+                                    }),
+                                ...(options.length > 0 ? { options } : {}),
+                            },
+                        };
+                    }
+                    else {
+                        yield { type: "status", message: "⏸️ Interrupt received" };
+                    }
+                }
+                if (sawInterrupt && debug)
+                    yield { type: "status", message: "🔚 Graph ended after interrupt" };
+                yield { type: "done", data: out };
+                break;
+            }
+            default:
+                if (typeof type === "string" && type.includes("interrupt")) {
+                    sawInterrupt = true;
+                    if (debug)
+                        console.log(`[debug:interrupt_like]`, JSON.stringify({ type, name, data }, null, 2));
+                    yield {
+                        type: "status",
+                        message: `⏸️ Interrupt event: ${type} ${name ?? ""}`.trim(),
+                    };
+                }
+                else if (debug) {
+                    console.warn(`[debug:unknown_event]`, type);
+                }
+                break;
+        }
+    }
+}

package/dist/types/chat-message.d.ts

@@ -0,0 +1,8 @@
+export type ChatMessage = {
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp?: number | undefined;
+    id?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+};
+//# sourceMappingURL=chat-message.d.ts.map

package/dist/types/chat-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-message.d.ts","sourceRoot":"","sources":["../../src/types/chat-message.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAChD,CAAC"}

package/dist/types/chat-message.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/extract-latest-message.d.ts

@@ -0,0 +1,3 @@
+import type { ChatMessage } from "../types/chat-message";
+export declare function extractLatestUserMessage(messages: ChatMessage[]): string;
+//# sourceMappingURL=extract-latest-message.d.ts.map

package/dist/utils/extract-latest-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-latest-message.d.ts","sourceRoot":"","sources":["../../src/utils/extract-latest-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAUxE"}

package/dist/utils/extract-latest-message.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLatestUserMessage = extractLatestUserMessage;
+function extractLatestUserMessage(messages) {
+    if (!messages || messages.length === 0)
+        return "";
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        if (msg?.role === "user" && msg?.content?.trim()) {
+            return msg.content.trim();
+        }
+    }
+    return "";
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@kortyx/agent",
+  "version": "0.2.0",
+  "private": false,
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@langchain/core": "^1.0.1",
+    "@langchain/langgraph": "^1.0.1",
+    "@kortyx/core": "0.2.0",
+    "@kortyx/providers": "0.2.0",
+    "@kortyx/runtime": "0.2.0",
+    "@kortyx/memory": "0.2.0",
+    "@kortyx/stream": "0.2.0",
+    "@kortyx/utils": "0.2.0"
+  },
+  "devDependencies": {
+    "turbo": "^2.5.4",
+    "typescript": "5.7.2"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "predev": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "lint": "echo 'Linting @kortyx/agent...' && echo 'Lint passed!'",
+    "test": "echo 'Testing @kortyx/agent...' && echo 'All tests passed!'",
+    "type-check": "tsc --noEmit"
+  }
+}