@adminforth/agent 2.8.0 → 2.8.2

package/dist/application/ports.d.ts

@@ -57,9 +57,10 @@ export interface LlmPort {
     /**
      * Rebuild the pending human-in-the-loop interrupts for a session from persisted
      * checkpoint state (used when the in-process cache is empty — after a restart or
-     * on another instance). Returns already-normalized descriptors; the LangGraph
-     * interrupt shape never leaves the llm layer. Throws on a checkpoint/runtime
-     * failure (the caller must not treat that as "no pending interrupt").
+     * on another instance). Returns already-normalized descriptors, each carrying the
+     * tool calls it is waiting on; the LangGraph interrupt shape never leaves the llm
+     * layer. Throws on a checkpoint/runtime failure (the caller must not treat that as
+     * "no pending interrupt").
      */
     getPendingInterrupts(input: {
         completionAdapter: AgentModeCompletionAdapter;

package/dist/application/runTurnUseCase.d.ts

@@ -70,6 +70,15 @@ export declare class RunTurnUseCase {
      * MemorySaver the in-process cache is authoritative (single process, cannot be stale).
      */
     private resolvePendingInterrupts;
+    /** Describe pending tool calls in plain language an admin (not a developer) can act on. */
+    private describeApprovals;
+    /**
+     * Describe what a session is still waiting for approval on, so a client that (re)loads
+     * the conversation can rebuild the approval prompt — it lives only in the browser, so a
+     * page reload would otherwise leave the user with no way to answer it. Empty when
+     * nothing is pending.
+     */
+    getPendingApprovals(sessionId: string, modeName?: string | null): Promise<string[]>;
     private requiresSessionOwnership;
     /** Verify the session exists and belongs to the requesting admin user. */
     assertSessionOwnership(sessionId: string, adminUser: BaseAgentTurnInput["adminUser"]): Promise<void>;

package/dist/application/runTurnUseCase.js

@@ -122,6 +122,29 @@ export class RunTurnUseCase {
             return (_a = this.pendingInterrupts.get(sessionId)) !== null && _a !== void 0 ? _a : [];
         });
     }
+    /** Describe pending tool calls in plain language an admin (not a developer) can act on. */
+    describeApprovals(interrupts) {
+        const adminforth = this.deps.getAdminforth();
+        return interrupts
+            .flatMap((interrupt) => interrupt.requests)
+            .map((request) => formatApprovalRequest(adminforth, request));
+    }
+    /**
+     * Describe what a session is still waiting for approval on, so a client that (re)loads
+     * the conversation can rebuild the approval prompt — it lives only in the browser, so a
+     * page reload would otherwise leave the user with no way to answer it. Empty when
+     * nothing is pending.
+     */
+    getPendingApprovals(sessionId, modeName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Loading a conversation must not fail because the checkpoint store is unhappy
+            // (already logged by resolvePendingInterrupts). Without the prompt the user simply
+            // falls back to the implicit reject in `prepareTurn`.
+            const interrupts = yield this.resolvePendingInterrupts(sessionId, this.resolveMode(modeName))
+                .catch(() => []);
+            return this.describeApprovals(interrupts);
+        });
+    }
     requiresSessionOwnership(input) {
         return !input.chatSurface;
     }
@@ -194,6 +217,7 @@ export class RunTurnUseCase {
                 mode,
                 context: this.buildContext(input, editTurnId),
                 observability: { emit: input.emit, sequenceDebugSink },
+                freshPrompt: true,
                 branchFromCheckpointId,
             };
         });
@@ -213,20 +237,31 @@ export class RunTurnUseCase {
             let turnId;
             let previousUserMessages = [];
             let initialResponse;
-            let resumeInterrupts;
+            let resume;
             if (shouldResume) {
-                resumeInterrupts = yield this.resolvePendingInterrupts(input.sessionId, mode);
+                const resumeInterrupts = yield this.resolvePendingInterrupts(input.sessionId, mode);
                 if (resumeInterrupts.length === 0) {
                     throw new Error(`No pending approval interrupt found for session "${input.sessionId}".`);
                 }
                 const resumeState = yield this.deps.sessions.getResumeState(input.sessionId);
                 turnId = resumeState.turnId;
                 initialResponse = resumeState.initialResponse;
+                resume = { decision: approvalDecision, interrupts: resumeInterrupts };
             }
             else {
+                // A pending approval leaves the provider thread with a tool call that has no
+                // result, so a plain new message would be rejected wholesale ("No tool output
+                // found for function call ..."). Sending one means the user moved on, so the
+                // pending call is rejected as part of this turn and the prompt rides along in
+                // the rejection. Reached whenever the approval UI is gone — after a page
+                // reload, from a second tab, or from a chat surface.
+                const pending = yield this.resolvePendingInterrupts(input.sessionId, mode);
                 previousUserMessages = yield this.deps.sessions.getPreviousUserMessages(input.sessionId);
                 turnId = yield this.deps.sessions.createNewTurn(input.sessionId, input.prompt);
                 yield this.deps.sessions.touchSession(input.sessionId);
+                if (pending.length > 0) {
+                    resume = { decision: "reject", interrupts: pending };
+                }
             }
             return {
                 prompt: input.prompt,
@@ -239,9 +274,8 @@ export class RunTurnUseCase {
                     emit: input.emit,
                     sequenceDebugSink,
                 },
-                resume: shouldResume
-                    ? { decision: approvalDecision, interrupts: resumeInterrupts }
-                    : undefined,
+                freshPrompt: !shouldResume,
+                resume,
                 initialResponse,
             };
         });
@@ -249,7 +283,7 @@ export class RunTurnUseCase {
     resolveUserLanguage(prepared) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
-            if (prepared.resume) {
+            if (!prepared.freshPrompt) {
                 return (_a = this.lastDetectedLanguage.get(prepared.sessionId)) !== null && _a !== void 0 ? _a : null;
             }
             const detected = yield this.deps.llm
@@ -273,30 +307,28 @@ export class RunTurnUseCase {
     buildMessages(prepared) {
         return [{ role: "user", content: prepared.prompt }];
     }
-    handleInterrupt(prepared, interrupt, descriptors, requests) {
+    handleInterrupt(prepared, interrupt, descriptors) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             if (!this.deps.hasPersistentCheckpointer) {
                 const existing = (_a = this.pendingInterrupts.get(prepared.sessionId)) !== null && _a !== void 0 ? _a : [];
-                const merged = new Map(existing.map((item) => [item.id, item.count]));
+                const merged = new Map(existing.map((item) => [item.id, item]));
                 for (const item of descriptors) {
-                    merged.set(item.id, item.count);
+                    merged.set(item.id, item);
                 }
-                this.pendingInterrupts.set(prepared.sessionId, [...merged.entries()].map(([id, count]) => ({ id, count })));
+                this.pendingInterrupts.set(prepared.sessionId, [...merged.values()]);
             }
-            const adminforth = this.deps.getAdminforth();
             yield ((_c = (_b = prepared.observability).emit) === null || _c === void 0 ? void 0 : _c.call(_b, {
                 type: "interrupt",
                 sessionId: prepared.sessionId,
                 interrupt,
-                approvals: requests.map((request) => formatApprovalRequest(adminforth, request)),
+                approvals: this.describeApprovals(descriptors),
             }));
         });
     }
     runAgentTurn(prepared) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, e_1, _b, _c;
-            var _d;
             const userLanguage = yield this.resolveUserLanguage(prepared);
             const streamInput = prepared.resume
                 ? {
@@ -322,16 +354,16 @@ export class RunTurnUseCase {
             let interrupted = false;
             try {
                 try {
-                    for (var _e = true, stream_1 = __asyncValues(stream), stream_1_1; stream_1_1 = yield stream_1.next(), _a = stream_1_1.done, !_a; _e = true) {
+                    for (var _d = true, stream_1 = __asyncValues(stream), stream_1_1; stream_1_1 = yield stream_1.next(), _a = stream_1_1.done, !_a; _d = true) {
                         _c = stream_1_1.value;
-                        _e = false;
+                        _d = false;
                         const chunk = _c;
                         if (abortSignal === null || abortSignal === void 0 ? void 0 : abortSignal.aborted) {
                             throw new DOMException("This operation was aborted", "AbortError");
                         }
                         if (chunk.kind === "interrupt") {
                             interrupted = true;
-                            yield this.handleInterrupt(prepared, chunk.interrupt, chunk.descriptors, (_d = chunk.requests) !== null && _d !== void 0 ? _d : []);
+                            yield this.handleInterrupt(prepared, chunk.interrupt, chunk.descriptors);
                             continue;
                         }
                         if (chunk.kind === "reasoning") {
@@ -349,7 +381,7 @@ export class RunTurnUseCase {
                 catch (e_1_1) { e_1 = { error: e_1_1 }; }
                 finally {
                     try {
-                        if (!_e && !_a && (_b = stream_1.return)) yield _b.call(stream_1);
+                        if (!_d && !_a && (_b = stream_1.return)) yield _b.call(stream_1);
                     }
                     finally { if (e_1) throw e_1.error; }
                 }

package/dist/custom/composables/agentStore/useAgentSessions.ts

@@ -23,6 +23,7 @@ type CreateAgentSessionManagerOptions = {
   blockCloseOfChat: Ref<boolean>;
   adminforth: AdminforthLike;
   setCurrentChat: (sessionId: string) => void;
+  restorePendingToolApproval: (sessionId: string, messages: string[]) => void;
 };
 
 export function createAgentSessionManager({
@@ -39,6 +40,7 @@ export function createAgentSessionManager({
   blockCloseOfChat,
   adminforth,
   setCurrentChat,
+  restorePendingToolApproval,
 }: CreateAgentSessionManagerOptions) {
   function sortSessionsListByTimestamp(sessionsListToSort: ISessionsListItem[]) {
     return [...sessionsListToSort].sort((a: ISessionsListItem, b: ISessionsListItem) => b.timestamp.localeCompare(a.timestamp));
@@ -113,6 +115,12 @@ export function createAgentSessionManager({
       // The session fetch can bail out (deleted/expired session), leaving no stored
       // messages — keep `messages` an array so consumers can iterate it safely.
       currentChat.value.messages = (currentSession.value?.messages ?? []).flatMap(mapStoredMessage);
+      // Only the turns are stored; an approval the agent is still waiting on is replayed
+      // from the backend so the user can answer it after a reload instead of being stuck.
+      const pendingApprovals = currentSession.value?.pendingApprovals ?? [];
+      if (pendingApprovals.length) {
+        restorePendingToolApproval(sessionId, pendingApprovals);
+      }
     }
   }
 

package/dist/custom/composables/useAgentStore.ts

@@ -123,18 +123,13 @@ export const useAgentStore = defineStore('agent', () => {
     });
   }
 
-  function addToolApprovalMessage(sessionId: string, interrupt: unknown, approvals?: unknown) {
-    // The backend describes each pending tool call in plain language; its raw
-    // descriptions are only the fallback when it could not.
-    const formatted = Array.isArray(approvals)
-      ? approvals.filter((line): line is string => typeof line === 'string' && Boolean(line))
-      : [];
+  function addToolApprovalPart(sessionId: string, messages: string[]) {
     const approvalPart = {
       type: 'data-tool-approval' as const,
       data: {
         sessionId,
         status: 'pending' as const,
-        messages: formatted.length ? formatted : getToolApprovalMessages(interrupt),
+        messages,
       },
     };
     const lastChatMessage = currentChat.value?.lastMessage;
@@ -151,6 +146,16 @@ export const useAgentStore = defineStore('agent', () => {
     });
   }
 
+  function addToolApprovalMessage(sessionId: string, interrupt: unknown, approvals?: unknown) {
+    // The backend describes each pending tool call in plain language; its raw
+    // descriptions are only the fallback when it could not.
+    const formatted = Array.isArray(approvals)
+      ? approvals.filter((line): line is string => typeof line === 'string' && Boolean(line))
+      : [];
+
+    addToolApprovalPart(sessionId, formatted.length ? formatted : getToolApprovalMessages(interrupt));
+  }
+
   async function submitToolApproval(sessionId: string, decision: 'approve' | 'reject') {
     const message = (currentChat.value?.messages ?? [])
       .findLast(candidate => candidate.role === 'assistant' && (candidate.parts ?? []).some((part: any) => {
@@ -172,6 +177,9 @@ export const useAgentStore = defineStore('agent', () => {
     try {
       await submitToolApprovalResponse(sessionId, decision);
 
+      if (currentSession.value?.sessionId === sessionId) {
+        currentSession.value.pendingApprovals = [];
+      }
       if (approvalPart?.data) {
         approvalPart.data.status = decision === 'approve' ? 'approved' : 'rejected';
       }
@@ -236,6 +244,7 @@ export const useAgentStore = defineStore('agent', () => {
     blockCloseOfChat,
     adminforth,
     setCurrentChat,
+    restorePendingToolApproval: addToolApprovalPart,
   });
 
   // "Turn active" = a request is in flight (submitted or streaming) or paused for HITL

package/dist/custom/conversation_area/ToolApprovalRenderer.vue

@@ -19,7 +19,7 @@
             class="flex gap-2"
           >
             <span class="mt-2 h-1.5 w-1.5 shrink-0 rounded-full bg-lightListTableHeadingText dark:bg-darkListTableHeadingText" />
-            <span class="min-w-0 break-words">{{ message }}</span>
+            <span class="min-w-0 whitespace-pre-line break-words">{{ message }}</span>
           </li>
         </ul>
         <div class="mt-4 flex flex-wrap gap-2">

package/dist/custom/types.ts

@@ -47,6 +47,8 @@ export interface IAgentSession {
   title: string;
   timestamp: string;
   messages: IMessage[];
+  /** Tool calls this session is still waiting for the user to approve, in plain language. */
+  pendingApprovals?: string[];
 }
 
 export interface ISessionsListItem {

package/dist/domain/turnTypes.d.ts

@@ -16,7 +16,10 @@ export type DebugSink = {
 /** A pending human-in-the-loop approval, normalized (provider-agnostic). */
 export type PendingInterrupt = {
     id: string;
+    /** Number of decisions the provider expects on resume (one per pending tool call). */
     count: number;
+    /** The pending tool calls, normalized so they can be described to the user. */
+    requests: ApprovalRequest[];
 };
 export type BaseAgentTurnInput = {
     prompt: string;
@@ -98,6 +101,4 @@ export type AgentStreamChunk = {
     kind: "interrupt";
     interrupt: unknown;
     descriptors: PendingInterrupt[];
-    /** The pending tool calls, normalized so they can be described to the user. */
-    requests: ApprovalRequest[];
 };

package/dist/index.js

@@ -161,6 +161,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             }),
             runAndPersistAgentResponse: this.runTurnUseCase.runAndPersistAgentResponse.bind(this.runTurnUseCase),
             getSessionTurns: this.sessionStore.getSessionTurns.bind(this.sessionStore),
+            getPendingApprovals: (sessionId) => this.runTurnUseCase.getPendingApprovals(sessionId),
             createNewTurn: this.sessionStore.createNewTurn.bind(this.sessionStore),
             createSystemTurn: this.sessionStore.createSystemTurn.bind(this.sessionStore),
             appendSteerToCurrentTurn: this.sessionStore.appendSteerToCurrentTurn.bind(this.sessionStore),

package/dist/llm/streamAdapter.d.ts

@@ -1,16 +1,10 @@
-import type { ApprovalRequest } from "../tools/approvalFormatter.js";
 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.
+ * Normalize raw LangGraph interrupt object(s) into provider-agnostic descriptors, each
+ * carrying the tool calls it is waiting on. Kept in the llm layer so the LangGraph
+ * interrupt shape never reaches the app.
  */
 export declare function normalizeInterrupts(interrupt: unknown): PendingInterrupt[];
-/**
- * Pull the tool calls out of the raw interrupt so the application layer can describe
- * them to the user. Like {@link normalizeInterrupts}, this keeps the LangGraph shape
- * from leaking past the llm layer.
- */
-export declare function extractApprovalRequests(interrupt: unknown): ApprovalRequest[];
 type RawStreamEntry = ["messages", [any, any]] | ["updates", Record<string, any>];
 /**
  * Convert one raw LangGraph stream entry into zero or more normalized chunks.

package/dist/llm/streamAdapter.js

@@ -25,8 +25,22 @@ 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.
+ * Pull the tool calls out of one interrupt's action requests so they can be described
+ * to the user. Drops entries the provider did not name.
+ */
+function toApprovalRequests(actionRequests) {
+    return actionRequests.flatMap((actionRequest) => {
+        var _a, _b;
+        const toolName = (_a = actionRequest === null || actionRequest === void 0 ? void 0 : actionRequest.name) !== null && _a !== void 0 ? _a : actionRequest === null || actionRequest === void 0 ? void 0 : actionRequest.action;
+        return typeof toolName === "string" && toolName
+            ? [{ toolName, args: ((_b = actionRequest === null || actionRequest === void 0 ? void 0 : actionRequest.args) !== null && _b !== void 0 ? _b : {}) }]
+            : [];
+    });
+}
+/**
+ * Normalize raw LangGraph interrupt object(s) into provider-agnostic descriptors, each
+ * carrying the tool calls it is waiting on. Kept in the llm layer so the LangGraph
+ * interrupt shape never reaches the app.
  */
 export function normalizeInterrupts(interrupt) {
     return getInterruptItems(interrupt).flatMap((item) => {
@@ -40,35 +54,14 @@ export function normalizeInterrupts(interrupt) {
             ? item.id
             : undefined;
         return typeof interruptId === "string" && Array.isArray(actionRequests)
-            ? [{ id: interruptId, count: actionRequests.length }]
+            ? [{
+                    id: interruptId,
+                    count: actionRequests.length,
+                    requests: toApprovalRequests(actionRequests),
+                }]
             : [];
     });
 }
-/**
- * Pull the tool calls out of the raw interrupt so the application layer can describe
- * them to the user. Like {@link normalizeInterrupts}, this keeps the LangGraph shape
- * from leaking past the llm layer.
- */
-export function extractApprovalRequests(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;
-        if (!Array.isArray(actionRequests)) {
-            return [];
-        }
-        return actionRequests.flatMap((actionRequest) => {
-            var _a, _b;
-            const toolName = (_a = actionRequest === null || actionRequest === void 0 ? void 0 : actionRequest.name) !== null && _a !== void 0 ? _a : actionRequest === null || actionRequest === void 0 ? void 0 : actionRequest.action;
-            return typeof toolName === "string" && toolName
-                ? [{ toolName, args: ((_b = actionRequest === null || actionRequest === void 0 ? void 0 : actionRequest.args) !== null && _b !== void 0 ? _b : {}) }]
-                : [];
-        });
-    });
-}
 function extractBlocks(token) {
     if (Array.isArray(token === null || token === void 0 ? void 0 : token.contentBlocks)) {
         return token.contentBlocks;
@@ -91,7 +84,6 @@ export function parseRawStreamChunk(entry) {
                     kind: "interrupt",
                     interrupt,
                     descriptors: normalizeInterrupts(interrupt),
-                    requests: extractApprovalRequests(interrupt),
                 }];
         }
         return [];

package/dist/tools/approvalFormatter.js

@@ -59,7 +59,9 @@ function formatRecord(record, resource) {
         return `${(column === null || column === void 0 ? void 0 : column.label) || humanize(name)}: ${formatValue(value, column)}`;
     });
     const hidden = entries.length - shown.length;
-    return hidden > 0 ? `${shown.join(", ")} and ${hidden} more` : shown.join(", ");
+    const lines = hidden > 0 ? [...shown, `and ${hidden} more`] : shown;
+    // One field per line: a wide record is unreadable as a single run-on sentence.
+    return lines.join(",\n");
 }
 function actionLabel(resource, actionId) {
     var _a, _b;
@@ -81,11 +83,11 @@ export function formatApprovalRequest(adminforth, request) {
     switch (toolName) {
         case "create_record": {
             const fields = formatRecord(args.record, resource);
-            return `Create a new record in ${label}${fields ? ` — ${fields}` : ""}`;
+            return `Create a new record in ${label}${fields ? `:\n${fields}` : ""}`;
         }
         case "update_record": {
             const fields = formatRecord(args.record, resource);
-            return `Update record with id:${formatValue(args.recordId)} in ${label}${fields ? ` — set ${fields}` : ""}`;
+            return `Update record with id:${formatValue(args.recordId)} in ${label}${fields ? `, set:\n${fields}` : ""}`;
         }
         case "delete_record":
             return `Delete record with id:${formatValue(args.primaryKey)} from ${label} — this cannot be undone`;
@@ -98,7 +100,7 @@ export function formatApprovalRequest(adminforth, request) {
         }
         default: {
             const fields = formatRecord(args, resource);
-            return `${humanize(toolName)}${fields ? ` — ${fields}` : ""}`;
+            return `${humanize(toolName)}${fields ? `:\n${fields}` : ""}`;
         }
     }
 }

package/dist/transport/http/context.d.ts

@@ -22,11 +22,12 @@ export type AgentEndpointsContext = {
     }>;
     runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput): Promise<RunAndPersistAgentResponseResult>;
     getSessionTurns(sessionId: string): Promise<SessionTurn[]>;
+    getPendingApprovals(sessionId: string): Promise<string[]>;
     createNewTurn(sessionId: string, prompt: string, response?: string): Promise<string>;
     createSystemTurn(sessionId: string, systemMessage: string): Promise<string>;
     appendSteerToCurrentTurn(sessionId: string, steerText: string): Promise<void>;
     handleChatSurfaceMessage(adapter: ChatSurfaceAdapter, incoming: ChatSurfaceIncomingMessage, sink: ChatSurfaceEventSink, request: IAdminForthEndpointHandlerInput): Promise<void>;
 };
 export type CoreEndpointsContext = Pick<AgentEndpointsContext, "options" | "handleTurn" | "handleEditTurn" | "handleSpeechTurn" | "steer">;
-export type SessionEndpointsContext = Pick<AgentEndpointsContext, "adminforth" | "options" | "getSessionTurns" | "createNewTurn" | "createSystemTurn" | "appendSteerToCurrentTurn">;
+export type SessionEndpointsContext = Pick<AgentEndpointsContext, "adminforth" | "options" | "getSessionTurns" | "getPendingApprovals" | "createNewTurn" | "createSystemTurn" | "appendSteerToCurrentTurn">;
 export type ChatSurfaceEndpointsContext = Pick<AgentEndpointsContext, "adminforth" | "options" | "handleChatSurfaceMessage">;

package/dist/transport/http/sessionEndpoints.js

@@ -69,12 +69,18 @@ export function setupSessionEndpoints(ctx, server) {
                     error: 'Unauthorized'
                 };
             }
-            const turns = yield ctx.getSessionTurns(sessionId);
+            const [turns, pendingApprovals] = yield Promise.all([
+                ctx.getSessionTurns(sessionId),
+                // The approval prompt lives only in the browser, so a reload has to rebuild it
+                // from the agent's persisted state — otherwise the user cannot answer it.
+                ctx.getPendingApprovals(sessionId),
+            ]);
             return {
                 session: {
                     sessionId,
                     title: session[ctx.options.sessionResource.titleField],
                     timestamp: session[ctx.options.sessionResource.createdAtField],
+                    pendingApprovals,
                     messages: turns.flatMap(turn => {
                         const messages = [];
                         if (turn.prompt === AGENT_SYSTEM_TURN_PROMPT) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/agent",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",