@adminforth/agent 2.0.9 → 2.1.0

package/dist/{agent/simpleAgent.d.ts → llm/agentModels.d.ts}

@@ -2,22 +2,26 @@ import type { BaseChatModel } from "@langchain/core/language_models/chat_models"
 import { type CompletionAdapter } from "adminforth";
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
 import type { LLMResult } from "@langchain/core/outputs";
+import type { Messages, Command } from "@langchain/langgraph";
 import { createSequenceDebugMiddleware } from "./middleware/sequenceDebug.js";
+import type { AgentModelPurpose } from "../application/ports.js";
+import type { AgentTurnContext, AgentTurnObservability } from "../domain/turnTypes.js";
+export type { AgentModeCompletionAdapter, AgentModelPurpose } from "../application/ports.js";
 export type AgentChatModel = BaseChatModel<any, any>;
-export type AgentModelPurpose = "primary" | "summary";
-export type AgentModeCompletionAdapter = CompletionAdapter & {
-    getLangChainAgentSpec(params: {
-        maxTokens: number;
-        purpose: AgentModelPurpose;
-    }): Promise<{
-        model: unknown;
-        middleware?: unknown[];
-    }> | {
-        model: unknown;
-        middleware?: unknown[];
-    };
-};
 export type AgentMiddleware = ReturnType<typeof createSequenceDebugMiddleware>;
+export type AgentTurnModels = {
+    model: AgentChatModel;
+    summaryModel: AgentChatModel;
+    modelMiddleware?: AgentMiddleware[];
+};
+export type AgentRuntimeRunInput = {
+    models: AgentTurnModels;
+    input: {
+        messages: Messages;
+    } | Command;
+    context: AgentTurnContext;
+    observability: AgentTurnObservability;
+};
 type AgentChatModelSpec = {
     model: AgentChatModel;
     middleware: AgentMiddleware[];
@@ -27,8 +31,7 @@ declare class AgentLlmMetricsLogger extends BaseCallbackHandler {
     lc_prefer_streaming: boolean;
     private readonly pendingRuns;
     handleLLMStart(_llm: unknown, _prompts: string[], runId: string): Promise<void>;
-    handleLLMNewToken(_token: string, _chunk: unknown, runId: string): Promise<void>;
-    handleLLMEnd(output: LLMResult, runId: string): Promise<void>;
+    handleLLMEnd(_output: LLMResult, runId: string): Promise<void>;
     handleLLMError(_error: unknown, runId: string): Promise<void>;
 }
 export declare function createAgentLlmMetricsLogger(): AgentLlmMetricsLogger;
@@ -37,4 +40,3 @@ export declare function createAgentChatModel(params: {
     maxTokens: number;
     purpose: AgentModelPurpose;
 }): Promise<AgentChatModelSpec>;
-export {};

package/dist/llm/agentModels.js

@@ -0,0 +1,65 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+function isLangChainAgentCompletionAdapter(adapter) {
+    return typeof adapter
+        .getLangChainAgentSpec === "function";
+}
+function getAgentChatModelSpec(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const spec = yield params.adapter.getLangChainAgentSpec({
+            maxTokens: params.maxTokens,
+            purpose: params.purpose,
+        });
+        return {
+            model: spec.model,
+            middleware: ((_a = spec.middleware) !== null && _a !== void 0 ? _a : []),
+        };
+    });
+}
+class AgentLlmMetricsLogger extends BaseCallbackHandler {
+    constructor() {
+        super(...arguments);
+        this.name = "AgentLlmMetricsLogger";
+        this.lc_prefer_streaming = true;
+        this.pendingRuns = new Map();
+    }
+    handleLLMStart(_llm, _prompts, runId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.pendingRuns.set(runId, { startedAt: Date.now() });
+        });
+    }
+    handleLLMEnd(_output, runId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.pendingRuns.delete(runId);
+        });
+    }
+    handleLLMError(_error, runId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.pendingRuns.delete(runId);
+        });
+    }
+}
+export function createAgentLlmMetricsLogger() {
+    return new AgentLlmMetricsLogger();
+}
+export function createAgentChatModel(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!isLangChainAgentCompletionAdapter(params.adapter)) {
+            throw new Error("AdminForth Agent requires completionAdapter to implement getLangChainAgentSpec({ maxTokens, purpose }).");
+        }
+        return yield getAgentChatModelSpec({
+            adapter: params.adapter,
+            maxTokens: params.maxTokens,
+            purpose: params.purpose,
+        });
+    });
+}

package/dist/{agent/runtime/AgentRuntime.d.ts → llm/agentRuntime.d.ts}

@@ -1,7 +1,7 @@
 import type { IAdminForth } from "adminforth";
 import type { BaseCheckpointSaver } from "@langchain/langgraph";
-import type { AgentToolProvider } from "../tools/AgentToolProvider.js";
-import type { AgentRuntimeRunInput } from "../turn/turnTypes.js";
+import type { AgentToolProvider } from "../tools/agentToolProvider.js";
+import type { AgentRuntimeRunInput, AgentTurnModels } from "./agentModels.js";
 export type AgentRuntimeOptions = {
     name: string;
     getAdminforth: () => IAdminForth;
@@ -12,4 +12,13 @@ export declare class AgentRuntime {
     private readonly options;
     constructor(options: AgentRuntimeOptions);
     stream(input: AgentRuntimeRunInput): Promise<import("@langchain/core/utils/stream").IterableReadableStream<["messages", [import("langchain").BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>, Record<string, any>]] | ["updates", Record<string, Omit<import("langchain").BuiltInState<import("@langchain/core/messages").MessageStructure<import("langchain").ToolsToMessageToolSet<readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>>>, "jumpTo">>]>>;
+    /**
+     * Read the pending human-in-the-loop interrupts persisted for a thread from the
+     * checkpointer. Builds a minimal agent (model + checkpointer + HITL middleware) and
+     * queries its state — no model call is made. Returns raw LangGraph interrupt objects.
+     */
+    getPendingInterrupts(input: {
+        models: AgentTurnModels;
+        sessionId: string;
+    }): Promise<unknown[]>;
 }

package/dist/{agent/runtime/AgentRuntime.js → llm/agentRuntime.js}

@@ -8,10 +8,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { createAgent, summarizationMiddleware, humanInTheLoopMiddleware } from "langchain";
-import { createApiBasedToolsMiddleware } from "../middleware/apiBasedTools.js";
-import { createSequenceDebugMiddleware } from "../middleware/sequenceDebug.js";
-import { createAgentLlmMetricsLogger } from "../simpleAgent.js";
-import { contextSchema, toLangchainAgentContext } from "./AgentContext.js";
+import { createApiBasedToolsMiddleware } from "./middleware/apiToolsMiddleware.js";
+import { createSequenceDebugMiddleware } from "./middleware/sequenceDebug.js";
+import { createAgentLlmMetricsLogger } from "./agentModels.js";
+import { contextSchema, toLangchainAgentContext } from "./agentContext.js";
 function createHumanInTheLoopInterrupts(apiBasedTools) {
     return Object.fromEntries(Object.entries(apiBasedTools)
         .filter(([, apiBasedTool]) => { var _a; return ((_a = apiBasedTool.agent) === null || _a === void 0 ? void 0 : _a.isDangerous) === true; })
@@ -33,7 +33,10 @@ export class AgentRuntime {
             const tools = yield this.options.toolProvider.getTools(apiBasedTools);
             const adminforth = this.options.getAdminforth();
             const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(apiBasedTools, adminforth);
-            const sequenceDebugMiddleware = createSequenceDebugMiddleware(input.observability.sequenceDebugSink);
+            // The domain exposes only the narrow DebugSink; the concrete collector (with the
+            // model-call hooks the debug middleware needs) is an llm-layer detail.
+            const sequenceDebugSink = input.observability.sequenceDebugSink;
+            const sequenceDebugMiddleware = createSequenceDebugMiddleware(sequenceDebugSink);
             const hitlMiddleware = humanInTheLoopMiddleware({
                 interruptOn: createHumanInTheLoopInterrupts(apiBasedTools),
                 descriptionPrefix: "Tool execution pending approval",
@@ -65,8 +68,37 @@ export class AgentRuntime {
                 configurable: {
                     thread_id: input.context.sessionId,
                 },
-                context: toLangchainAgentContext(Object.assign(Object.assign({}, input.context), { adminBaseUrl: adminforth.config.baseUrlSlashed, emit: input.observability.emit, sequenceDebugSink: input.observability.sequenceDebugSink })),
+                context: toLangchainAgentContext(Object.assign(Object.assign({}, input.context), { adminBaseUrl: adminforth.config.baseUrlSlashed, emit: input.observability.emit, sequenceDebugSink })),
             });
         });
     }
+    /**
+     * Read the pending human-in-the-loop interrupts persisted for a thread from the
+     * checkpointer. Builds a minimal agent (model + checkpointer + HITL middleware) and
+     * queries its state — no model call is made. Returns raw LangGraph interrupt objects.
+     */
+    getPendingInterrupts(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const apiBasedTools = this.options.toolProvider.getApiBasedTools();
+            const tools = yield this.options.toolProvider.getTools(apiBasedTools);
+            const agent = createAgent({
+                name: this.options.name,
+                model: input.models.model,
+                checkpointer: this.options.getCheckpointer(),
+                tools,
+                contextSchema,
+                middleware: [
+                    humanInTheLoopMiddleware({
+                        interruptOn: createHumanInTheLoopInterrupts(apiBasedTools),
+                        descriptionPrefix: "Tool execution pending approval",
+                    }),
+                ],
+            });
+            const state = yield agent.getState({
+                configurable: { thread_id: input.sessionId },
+            });
+            const tasks = Array.isArray(state === null || state === void 0 ? void 0 : state.tasks) ? state.tasks : [];
+            return tasks.flatMap((task) => (Array.isArray(task === null || task === void 0 ? void 0 : task.interrupts) ? task.interrupts : []));
+        });
+    }
 }

package/dist/llm/langGraphLlm.d.ts

@@ -0,0 +1,25 @@
+import type { AgentRuntime } from "./agentRuntime.js";
+import type { AgentModelFactory } from "./modelFactory.js";
+import { type PreviousUserMessage } from "../domain/languageDetect.js";
+import type { AgentModeCompletionAdapter, LlmPort, LlmStreamInput } from "../application/ports.js";
+import type { PendingInterrupt } from "../domain/turnTypes.js";
+/**
+ * LangChain/LangGraph implementation of {@link LlmPort}. This is the single
+ * place that knows about the agent graph, model construction, and the raw
+ * stream shape; the application layer talks only to the port.
+ */
+export declare class LangGraphLlm implements LlmPort {
+    private readonly runtime;
+    private readonly modelFactory;
+    constructor(runtime: AgentRuntime, modelFactory: AgentModelFactory);
+    streamTurn(input: LlmStreamInput): Promise<AsyncGenerator<import("../domain/turnTypes.js").AgentStreamChunk, any, any>>;
+    detectLanguage(input: {
+        completionAdapter: AgentModeCompletionAdapter;
+        prompt: string;
+        previousUserMessages: PreviousUserMessage[];
+    }): Promise<import("../domain/languageDetect.js").DetectedLanguage | null>;
+    getPendingInterrupts(input: {
+        completionAdapter: AgentModeCompletionAdapter;
+        sessionId: string;
+    }): Promise<PendingInterrupt[]>;
+}

package/dist/llm/langGraphLlm.js

@@ -0,0 +1,54 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Command } from "@langchain/langgraph";
+import { HumanMessage, SystemMessage } from "langchain";
+import { detectUserLanguage } from "../domain/languageDetect.js";
+import { adaptRawStream, normalizeInterrupts } from "./streamAdapter.js";
+function toLangchainMessages(messages) {
+    return messages.map((message) => message.role === "system"
+        ? new SystemMessage(message.content)
+        : new HumanMessage(message.content));
+}
+/**
+ * LangChain/LangGraph implementation of {@link LlmPort}. This is the single
+ * place that knows about the agent graph, model construction, and the raw
+ * stream shape; the application layer talks only to the port.
+ */
+export class LangGraphLlm {
+    constructor(runtime, modelFactory) {
+        this.runtime = runtime;
+        this.modelFactory = modelFactory;
+    }
+    streamTurn(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const models = yield this.modelFactory.create(input.completionAdapter);
+            const runtimeInput = "resume" in input.input
+                ? new Command({ resume: input.input.resume })
+                : { messages: toLangchainMessages(input.input.messages) };
+            const rawStream = yield this.runtime.stream({
+                models,
+                input: runtimeInput,
+                context: input.context,
+                observability: input.observability,
+            });
+            return adaptRawStream(rawStream);
+        });
+    }
+    detectLanguage(input) {
+        return detectUserLanguage(input.completionAdapter, input.prompt, input.previousUserMessages);
+    }
+    getPendingInterrupts(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const models = yield this.modelFactory.create(input.completionAdapter);
+            const raw = yield this.runtime.getPendingInterrupts({ models, sessionId: input.sessionId });
+            return normalizeInterrupts(raw);
+        });
+    }
+}

package/dist/{agent/middleware/apiBasedTools.d.ts → llm/middleware/apiToolsMiddleware.d.ts}

@@ -1,3 +1,3 @@
 import { type IAdminForth } from "adminforth";
-import { type ApiBasedTool } from "../../apiBasedTools.js";
+import { type ApiBasedTool } from "../../tools/apiBasedTools.js";
 export declare function createApiBasedToolsMiddleware(apiBasedTools: Record<string, ApiBasedTool>, adminforth: IAdminForth): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>;

package/dist/{agent/middleware/apiBasedTools.js → llm/middleware/apiToolsMiddleware.js}

@@ -11,11 +11,11 @@ import { ToolMessage } from "@langchain/core/messages";
 import { isGraphInterrupt } from "@langchain/langgraph";
 import { createMiddleware } from "langchain";
 import { logger } from "adminforth";
-import { formatApiBasedToolCall, } from "../../apiBasedTools.js";
-import { createToolCallTracker, } from "../toolCallEvents.js";
-import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "../tools/index.js";
-import { createApiTool } from "../tools/apiTool.js";
-import { isAbortError } from "../../errors.js";
+import { formatApiBasedToolCall, } from "../../tools/apiBasedTools.js";
+import { createToolCallTracker, } from "../../domain/toolCallEvents.js";
+import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "../../tools/index.js";
+import { createApiTool } from "../../tools/apiTool.js";
+import { isAbortError } from "../../shared/errors.js";
 function getEnabledApiToolNames(messages) {
     const enabledToolNames = new Set();
     for (const message of messages) {
@@ -58,15 +58,13 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                     .filter((toolName) => !alwaysAvailableApiToolNames.has(toolName))
                     .map((toolName) => dynamicTools[toolName]);
                 const availableTools = [...request.tools, ...tools];
-                logger.info(`AdminForth Agent callable tools: ${availableTools.map((tool) => tool.name).join(", ")}`);
                 return handler(Object.assign(Object.assign({}, request), { tools: availableTools }));
             });
         },
         wrapToolCall(request, handler) {
             return __awaiter(this, void 0, void 0, function* () {
-                var _a, _b, _c;
+                var _a, _b;
                 const startedAt = Date.now();
-                const toolInput = JSON.stringify((_a = request.toolCall.args) !== null && _a !== void 0 ? _a : {});
                 if (!request.toolCall.id) {
                     throw new Error(`Tool call "${request.toolCall.name}" has no id.`);
                 }
@@ -79,7 +77,7 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                         data: event,
                     }));
                 };
-                const toolArgs = ((_b = request.toolCall.args) !== null && _b !== void 0 ? _b : {});
+                const toolArgs = ((_a = request.toolCall.args) !== null && _a !== void 0 ? _a : {});
                 let toolInfo;
                 if (request.toolCall.name === "fetch_skill") {
                     toolInfo = `Load ${toolArgs.skillName.split("_").join(" ")} skill`;
@@ -105,7 +103,6 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                     startedAt,
                 });
                 toolCallTracker.start();
-                logger.info(`Invoking tool "${request.toolCall.name}" with input: ${toolInput}`);
                 try {
                     const result = getEnabledApiToolNames(request.state.messages).has(request.toolCall.name)
                         ? yield handler(Object.assign(Object.assign({}, request), { tool: dynamicTools[request.toolCall.name] }))
@@ -120,7 +117,7 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                         throw error;
                     }
                     const message = error instanceof Error ? error.message : String(error);
-                    logger.error(`Error calling tool "${request.toolCall.name}": ${error instanceof Error ? (_c = error.stack) !== null && _c !== void 0 ? _c : error.message : String(error)}`);
+                    logger.error(`Error calling tool "${request.toolCall.name}": ${error instanceof Error ? (_b = error.stack) !== null && _b !== void 0 ? _b : error.message : String(error)}`);
                     toolCallTracker.finishError(`Error: ${message}`);
                     return new ToolMessage({
                         name: request.toolCall.name,
@@ -129,9 +126,6 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                         content: `Error: ${message}`,
                     });
                 }
-                finally {
-                    logger.info(`Tool "${request.toolCall.name}" finished in ${Date.now() - startedAt}ms`);
-                }
             });
         },
     });

package/dist/{agent → llm}/middleware/sequenceDebug.d.ts

@@ -1,4 +1,4 @@
-import type { ToolCallEvent } from "../toolCallEvents.js";
+import type { ToolCallEvent } from "../../domain/toolCallEvents.js";
 export type SequenceDebugResultType = "tool_calls" | "final_text";
 type SequenceDebugToolCall = {
     toolCallId: string;

package/dist/{agent/models/AgentModelFactory.d.ts → llm/modelFactory.d.ts}

@@ -1,5 +1,5 @@
 import type { CompletionAdapter } from "adminforth";
-import type { AgentTurnModels } from "../turn/turnTypes.js";
+import { type AgentTurnModels } from "./agentModels.js";
 export declare class AgentModelFactory {
     private readonly maxTokens;
     constructor(maxTokens: number);

package/dist/{agent/models/AgentModelFactory.js → llm/modelFactory.js}

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { createAgentChatModel } from "../simpleAgent.js";
+import { createAgentChatModel } from "./agentModels.js";
 export class AgentModelFactory {
     constructor(maxTokens) {
         this.maxTokens = maxTokens;

package/dist/llm/streamAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { AgentStreamChunk, PendingInterrupt } from "../domain/turnTypes.js";
+/**
+ * Normalize raw LangGraph interrupt object(s) into provider-agnostic descriptors.
+ * Kept in the llm layer so the LangGraph interrupt shape never reaches the app.
+ */
+export declare function normalizeInterrupts(interrupt: unknown): PendingInterrupt[];
+type RawStreamEntry = ["messages", [any, any]] | ["updates", Record<string, any>];
+/**
+ * Convert one raw LangGraph stream entry into zero or more normalized chunks.
+ * Pure and synchronous so the parsing rules can be unit-tested in isolation.
+ */
+export declare function parseRawStreamChunk(entry: RawStreamEntry): AgentStreamChunk[];
+/**
+ * Adapt the raw LangGraph `["messages" | "updates", ...]` stream into a typed
+ * `AgentStreamChunk` stream for the application layer.
+ */
+export declare function adaptRawStream(raw: AsyncIterable<RawStreamEntry>): AsyncGenerator<AgentStreamChunk>;
+export {};

package/dist/llm/streamAdapter.js

@@ -0,0 +1,117 @@
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+// Only tokens emitted by the model node(s) are surfaced to the user; other
+// graph nodes (tools, summarization, etc.) are internal.
+const STREAMABLE_NODES = ["model", "model_request"];
+function getInterruptItems(interrupt) {
+    return Array.isArray(interrupt) ? interrupt : [interrupt];
+}
+/**
+ * Normalize raw LangGraph interrupt object(s) into provider-agnostic descriptors.
+ * Kept in the llm layer so the LangGraph interrupt shape never reaches the app.
+ */
+export function normalizeInterrupts(interrupt) {
+    return getInterruptItems(interrupt).flatMap((item) => {
+        const value = item && typeof item === "object" && "value" in item
+            ? item.value
+            : item;
+        const actionRequests = value && typeof value === "object"
+            ? value.actionRequests
+            : undefined;
+        const interruptId = item && typeof item === "object"
+            ? item.id
+            : undefined;
+        return typeof interruptId === "string" && Array.isArray(actionRequests)
+            ? [{ id: interruptId, count: actionRequests.length }]
+            : [];
+    });
+}
+function extractBlocks(token) {
+    if (Array.isArray(token === null || token === void 0 ? void 0 : token.contentBlocks)) {
+        return token.contentBlocks;
+    }
+    if (Array.isArray(token === null || token === void 0 ? void 0 : token.content)) {
+        return token.content;
+    }
+    return [];
+}
+/**
+ * Convert one raw LangGraph stream entry into zero or more normalized chunks.
+ * Pure and synchronous so the parsing rules can be unit-tested in isolation.
+ */
+export function parseRawStreamChunk(entry) {
+    const [mode, chunk] = entry;
+    if (mode === "updates") {
+        if (chunk && typeof chunk === "object" && "__interrupt__" in chunk) {
+            const interrupt = chunk.__interrupt__;
+            return [{ kind: "interrupt", interrupt, descriptors: normalizeInterrupts(interrupt) }];
+        }
+        return [];
+    }
+    const [token, metadata] = chunk;
+    const nodeName = typeof (metadata === null || metadata === void 0 ? void 0 : metadata.langgraph_node) === "string" ? metadata.langgraph_node : "";
+    if (nodeName && !STREAMABLE_NODES.includes(nodeName)) {
+        return [];
+    }
+    const blocks = extractBlocks(token);
+    const chunks = [];
+    const reasoning = blocks
+        .filter((block) => (block === null || block === void 0 ? void 0 : block.type) === "reasoning")
+        .map((block) => { var _a; return String((_a = block.reasoning) !== null && _a !== void 0 ? _a : ""); })
+        .join("");
+    const text = blocks
+        .filter((block) => (block === null || block === void 0 ? void 0 : block.type) === "text")
+        .map((block) => { var _a; return String((_a = block.text) !== null && _a !== void 0 ? _a : ""); })
+        .join("");
+    if (reasoning) {
+        chunks.push({ kind: "reasoning", delta: reasoning });
+    }
+    if (text) {
+        chunks.push({ kind: "text", delta: text });
+    }
+    return chunks;
+}
+/**
+ * Adapt the raw LangGraph `["messages" | "updates", ...]` stream into a typed
+ * `AgentStreamChunk` stream for the application layer.
+ */
+export function adaptRawStream(raw) {
+    return __asyncGenerator(this, arguments, function* adaptRawStream_1() {
+        var _a, e_1, _b, _c;
+        try {
+            for (var _d = true, raw_1 = __asyncValues(raw), raw_1_1; raw_1_1 = yield __await(raw_1.next()), _a = raw_1_1.done, !_a; _d = true) {
+                _c = raw_1_1.value;
+                _d = false;
+                const entry = _c;
+                for (const chunk of parseRawStreamChunk(entry)) {
+                    yield yield __await(chunk);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = raw_1.return)) yield __await(_b.call(raw_1));
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    });
+}

package/dist/{sessionStore.d.ts → persistence/sessionStore.d.ts}

@@ -1,7 +1,7 @@
 import type { AdminUser, IAdminForth } from "adminforth";
 import type { ChatSurfaceIncomingMessage } from "adminforth";
-import type { PreviousUserMessage } from "./agent/languageDetect.js";
-import type { PluginOptions } from "./types.js";
+import type { PreviousUserMessage } from "../domain/languageDetect.js";
+import type { PluginOptions } from "../types.js";
 export declare const AGENT_SYSTEM_TURN_PROMPT = "__adminforth_system_message__";
 export declare class AgentSessionStore {
     private getAdminforth;
@@ -17,4 +17,14 @@ export declare class AgentSessionStore {
     getLatestTurn(sessionId: string): Promise<any>;
     getChatSurfaceSessionId(incoming: ChatSurfaceIncomingMessage): string;
     getOrCreateChatSurfaceSession(incoming: ChatSurfaceIncomingMessage, adminUser: AdminUser): Promise<string>;
+    touchSession(sessionId: string): Promise<void>;
+    saveTurnResponse(input: {
+        turnId: string;
+        responseText: string;
+        debugHistory?: unknown;
+    }): Promise<void>;
+    getResumeState(sessionId: string): Promise<{
+        turnId: string;
+        initialResponse: string;
+    }>;
 }

package/dist/{sessionStore.js → persistence/sessionStore.js}

@@ -86,4 +86,37 @@ export class AgentSessionStore {
             return sessionId;
         });
     }
+    touchSession(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.getAdminforth().resource(this.options.sessionResource.resourceId).update(sessionId, {
+                [this.options.sessionResource.createdAtField]: new Date().toISOString(),
+            });
+        });
+    }
+    saveTurnResponse(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const turnUpdates = {
+                [this.options.turnResource.responseField]: input.responseText,
+            };
+            if (this.options.turnResource.debugField) {
+                turnUpdates[this.options.turnResource.debugField] = input.debugHistory;
+            }
+            yield this.getAdminforth()
+                .resource(this.options.turnResource.resourceId)
+                .update(input.turnId, turnUpdates);
+        });
+    }
+    getResumeState(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const latestTurn = yield this.getLatestTurn(sessionId);
+            if (!latestTurn) {
+                throw new Error(`No agent turn found for session "${sessionId}".`);
+            }
+            const response = latestTurn[this.options.turnResource.responseField];
+            return {
+                turnId: latestTurn[this.options.turnResource.idField],
+                initialResponse: response === "not_finished" ? "" : String(response),
+            };
+        });
+    }
 }

package/dist/{agent/tools/AgentToolProvider.d.ts → tools/agentToolProvider.d.ts}

@@ -1,5 +1,5 @@
 import type { IAdminForth } from "adminforth";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
+import type { ApiBasedTool } from "./apiBasedTools.js";
 export declare class AgentToolProvider {
     private readonly getAdminforth;
     private readonly getInternalAgentResourceIds;

package/dist/{agent/tools/AgentToolProvider.js → tools/agentToolProvider.js}

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { prepareApiBasedTools } from "../../apiBasedTools.js";
+import { prepareApiBasedTools } from "./apiBasedTools.js";
 import { createAgentTools } from "./index.js";
 export class AgentToolProvider {
     constructor(getAdminforth, getInternalAgentResourceIds) {