@adminforth/agent 2.7.5 → 2.8.1

package/README.md

@@ -19,6 +19,10 @@ API-based tools, streams its answers token-by-token, and keeps persistent chat s
   by Markdown *skills* you can extend.
 - **Human-in-the-loop approvals** — tools you mark as dangerous pause for explicit
   approve/reject from the user before running.
+- **Mid-turn steering** — send another instruction while the agent is still working; it is
+  folded into the *running* turn before its next model call instead of waiting in line.
+- **Message editing & branching** — edit an earlier message to fork the conversation from
+  that turn's checkpoint: later turns are dropped and the answer is regenerated.
 - **Multiple modes** — expose several models (e.g. *Fast*, *Balanced*, *Smart Thinking*)
   and let users switch between them.
 - **Persistent sessions** — conversations are stored in your database; an optional
@@ -36,6 +40,124 @@ list of your resources and available skills), streams the model's output back ov
 persists the prompt/response to your turn resource. Tools are executed through AdminForth's
 API endpoints; conversation memory is kept per session (`thread_id = sessionId`).
 
+## Architecture
+
+The plugin is layered so that the provider-specific parts (LangChain/LangGraph, the
+completion adapter, the checkpointer) sit behind ports and never leak into the turn logic:
+
+| Layer | Directory | Depends on |
+| --- | --- | --- |
+| Domain — prompt building, event vocabulary, buffers | [domain/](domain/) | adminforth types only |
+| Application — the turn use case + ports | [application/](application/) | domain |
+| LLM runtime — LangChain/LangGraph behind `LlmPort` | [llm/](llm/) | application, domain, tools |
+| Tools & skills — API tools, progressive disclosure | [tools/](tools/) | AdminForth API layer |
+| Persistence — sessions, turns, checkpoints | [persistence/](persistence/) | AdminForth resources |
+| Transport — HTTP endpoints, SSE, external surfaces | [transport/](transport/) | application |
+| Frontend — Vue 3 + Pinia chat surface | [custom/](custom/) | HTTP + SSE contract |
+
+```mermaid
+flowchart TB
+    UI["Admin UI - custom/<br/>Vue 3 + Pinia chat surface"]
+    TR["transport/<br/>HTTP endpoints, SSE, external surfaces"]
+    APP["application/<br/>RunTurnUseCase + LlmPort"]
+    DOM["domain/<br/>prompt building, steer buffer,<br/>events, language detection"]
+    LLMS["llm/<br/>LangGraph agent, middleware chain, models"]
+    TLS["tools/<br/>API tools + skills,<br/>progressive disclosure"]
+    PRS["persistence/<br/>sessions, turns, checkpoints"]
+
+    AF[("AdminForth core<br/>resources, API layer, auth")]
+    MODEL(["Completion adapter<br/>OpenAI / Anthropic / Gemini"])
+    ADPT(["Audio and chat surface adapters<br/>STT / TTS, Telegram"])
+
+    UI <-->|"POST + SSE"| TR
+    TR <--> ADPT
+    TR --> APP
+    TR -->|"session CRUD"| PRS
+    APP --> DOM
+    APP --> PRS
+    APP -->|"LlmPort"| LLMS
+    LLMS --> MODEL
+    LLMS --> TLS
+    LLMS -->|"checkpointer"| PRS
+    TLS --> AF
+    PRS --> AF
+```
+
+Every arrow into `AdminForth core` goes through its ordinary resource/API layer, so your
+access rules, hooks and validation apply to the agent exactly as they do to a human admin.
+
+### One turn, end to end
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as User
+    participant UI as Chat UI (useAgentChat)
+    participant EP as POST /agent/response
+    participant UC as RunTurnUseCase
+    participant DB as sessions and turns
+    participant LLM as LangGraphLlm + AgentRuntime
+    participant M as Model (completion adapter)
+    participant T as API tool (AdminForth API layer)
+
+    U->>UI: type a message
+    UI->>EP: message, sessionId, mode, timeZone, currentPage
+    EP->>UC: handleTurn
+    UC->>DB: assert session ownership
+    UC->>DB: create turn, response = not_finished
+    UC-->>UI: data-turn-persisted with turnId
+    UC->>M: detect user language (small side call)
+    UC->>LLM: streamTurn with system prompt, messages, context
+
+    loop agent loop, recursionLimit 100
+        LLM->>LLM: steer middleware drains SteerBuffer
+        LLM->>M: model call with currently enabled tools
+        M-->>LLM: reasoning and text deltas
+        LLM-->>UI: reasoning-delta and text-delta frames
+        M-->>LLM: tool call
+        alt tool has agent.isDangerous
+            LLM-->>UI: data-interrupt, generation pauses
+            U->>UI: approve or reject
+            UI->>EP: POST /agent/approval
+            EP->>UC: resume the interrupted graph
+        else safe tool
+            LLM->>T: execute through the API layer
+            T-->>LLM: YAML result plus durationMs
+            LLM-->>UI: data-tool-call start and end
+        end
+    end
+
+    LLM-->>UC: stream ends
+    UC->>LLM: getLatestCheckpointId, the fork point for edits
+    UC->>DB: save response, debug trace, checkpointId
+    UC-->>UI: data-response then finish
+```
+
+Two side channels run on top of that flow:
+
+- **Steering** — `POST /agent/steer` buffers a message in the in-process `SteerBuffer`;
+  the `beforeModel` steer middleware folds it in as a user message before the next model
+  call and emits `data-steer-applied` on the turn's already-open stream.
+- **Editing / branching** — `POST /agent/edit` forks from the previous turn's stored
+  checkpoint id, truncates the later turns, and regenerates. Requires both
+  `checkpointResource` and `turnResource.checkpointIdField`.
+
+### Progressive tool & skill disclosure
+
+```mermaid
+flowchart LR
+    A["Turn starts"] --> B["Exposed tools:<br/>get_resource, get_user_location,<br/>navigate_user, fetch_skill, fetch_tool_schema"]
+    B --> C{"Needs more than<br/>reading schema?"}
+    C -- no --> D["Answer with the base tools"]
+    C -- yes --> E["fetch_skill returns the SKILL.md<br/>for the matching skill"]
+    E --> F["fetch_tool_schema loads one<br/>API tool schema by name"]
+    F --> G["ApiBasedToolsMiddleware sees the<br/>status 200 tool message and adds that<br/>tool to the next model call"]
+    G --> H{"agent.isDangerous?"}
+    H -- yes --> I["humanInTheLoopMiddleware interrupt,<br/>approve or reject in the UI"]
+    H -- no --> J["Execute through the AdminForth API layer"]
+    I -- approved --> J
+```
+
 ## Requirements
 
 - An AdminForth app (`adminforth >= 3.8.2`, declared as a peer dependency).
@@ -78,7 +200,6 @@ const sessionsResource: AdminForthResourceInput = {
   columns: [
     { name: 'id', primaryKey: true, type: AdminForthDataTypes.STRING, fillOnCreate: () => randomUUID() },
     { name: 'title', type: AdminForthDataTypes.STRING },
-    { name: 'turns', type: AdminForthDataTypes.INTEGER },
     { name: 'asker_id', type: AdminForthDataTypes.STRING },
     { name: 'created_at', type: AdminForthDataTypes.DATETIME, fillOnCreate: () => new Date().toISOString() },
   ],
@@ -106,6 +227,9 @@ const turnsResource: AdminForthResourceInput = {
     { name: 'created_at', type: AdminForthDataTypes.DATETIME, fillOnCreate: () => new Date().toISOString() },
     { name: 'prompt', type: AdminForthDataTypes.TEXT },
     { name: 'response', type: AdminForthDataTypes.TEXT },
+    // Optional: map via turnResource.checkpointIdField. Stores each turn's tip
+    // checkpoint id — required for message editing / branching.
+    { name: 'checkpoint_id', type: AdminForthDataTypes.STRING },
     // Optional: add a `debug` TEXT column and map it via turnResource.debugField
     // to store per-turn debug traces.
   ],
@@ -180,7 +304,6 @@ export const globalPlugins = [
       resourceId: 'sessions',
       idField: 'id',
       titleField: 'title',
-      turnsField: 'turns',
       askerIdField: 'asker_id',
       createdAtField: 'created_at',
     },
@@ -191,6 +314,8 @@ export const globalPlugins = [
       createdAtField: 'created_at',
       promptField: 'prompt',
       responseField: 'response',
+      // Enables message editing / branching (together with checkpointResource below).
+      checkpointIdField: 'checkpoint_id',
     },
 
     // Optional but recommended in production:
@@ -254,12 +379,21 @@ That's it — a chat panel now appears in the admin UI.
 
 ### `sessionResource` fields
 
-`resourceId`, `idField`, `titleField`, `turnsField`, `askerIdField`, `createdAtField`.
+`resourceId`, `idField`, `titleField`, `askerIdField`, `createdAtField`.
+
+> `turnsField` is **deprecated** and ignored — session turns are looked up through
+> `turnResource.sessionIdField`. It still type-checks for backward compatibility and will be
+> removed in a future major version.
 
 ### `turnResource` fields
 
 `resourceId`, `idField`, `sessionIdField`, `createdAtField`, `promptField`, `responseField`,
-and optional `debugField` (when set, per-turn debug traces are written to it).
+plus two optional ones:
+
+| Field | Effect |
+| --- | --- |
+| `debugField` | Per-turn debug traces are written to this column. |
+| `checkpointIdField` | Each successful turn's tip checkpoint id is stored, which is what **message editing / branching** forks from. Editing needs this *and* `checkpointResource`; without both, the chat UI hides the edit action and `POST /agent/edit` rejects the request. |
 
 > **Reasoning effort** is set on the completion adapter (e.g.
 > `extraRequestBodyParameters: { reasoning: { effort } }`), not on the plugin.
@@ -273,7 +407,8 @@ permissions and validation are enforced.
 
 To keep the model focused, tools are disclosed progressively:
 
-- `get_resource` is always available (to inspect resource structure).
+- Always available: `get_resource` (inspect resource structure), `get_user_location`,
+  `navigate_user`, and the two discovery tools `fetch_skill` / `fetch_tool_schema`.
 - The agent reads a **skill** (a `SKILL.md` file) to learn which tools a task needs, then
   loads those tool schemas on demand.
 
@@ -287,7 +422,11 @@ directories are also discovered.
 Tools whose definition marks them dangerous (`agent.isDangerous === true`) trigger an
 approval interrupt: generation pauses and the UI shows an approve/reject prompt. The client
 resolves it via `POST /agent/approval`, and the run resumes (or, on reject, the model is
-told the action was declined). Approval state is currently held per process instance.
+told the action was declined).
+
+Where the pending approval lives depends on your setup: with `checkpointResource` configured
+the LangGraph checkpoint is authoritative, so a resume survives a restart and works across
+instances; with the in-memory fallback the state is held per process instance.
 
 ## Voice
 
@@ -311,7 +450,9 @@ All routes are registered under your AdminForth API base path.
 | Method & path | Purpose |
 | --- | --- |
 | `POST /agent/response` | Send a message; streams the answer over SSE. |
+| `POST /agent/edit` | Edit a previous message: forks from its turn's checkpoint, truncates later turns, regenerates. |
 | `POST /agent/approval` | Approve/reject a pending human-in-the-loop tool call. |
+| `POST /agent/steer` | Buffer a mid-turn instruction; folded into the running turn before the next model call. |
 | `POST /agent/speech-response` | Multipart audio upload; streams transcript + answer (+ audio). |
 | `POST /agent/get-placeholder-messages` | Placeholder prompts for the chat textarea. |
 | `POST /agent/get-sessions` | List chat sessions. |
@@ -319,23 +460,27 @@ All routes are registered under your AdminForth API base path.
 | `POST /agent/create-session` | Create a new session. |
 | `POST /agent/delete-session` | Delete a session and its turns. |
 | `POST /agent/add-system-message-to-turns` | Append a system message turn. |
+| `POST /agent/append-steer-to-turn` | Persist a steer into the running turn's stored prompt. |
 | `POST /agent/surface/<name>/webhook` | Inbound webhook for an external chat surface. |
 
-The `/agent/response` and `/agent/approval` streams use the Vercel AI UI message stream
-format (`x-vercel-ai-ui-message-stream: v1`); the frontend consumes them directly.
+The `/agent/response`, `/agent/edit` and `/agent/approval` streams use the Vercel AI UI
+message stream format (`x-vercel-ai-ui-message-stream: v1`); the frontend consumes them
+directly. `/agent/speech-response` uses the plugin's own bare event names instead.
 
 ## Contributing / tests
 
 This package is developed inside the [AdminForth monorepo](https://github.com/devforth/adminforth).
-Unit and characterization tests for the plugin live in `tests/jest_tests/`
-(`adminforth_agent_*.test.ts`) and run with:
+The plugin carries its own self-contained Jest suite in [tests/](tests/) — run it from the
+plugin root:
 
 ```bash
-cd tests/jest_tests
 pnpm install
 pnpm test
 ```
 
+A couple of integration-level agent tests (`adminforth_agent_*.test.ts`) still live in the
+monorepo's `tests/jest_tests/` and run from that directory.
+
 ## About AdminForth
 
 AdminForth is an open-source, agent-first admin framework for building robust admin panels

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

@@ -18,6 +18,7 @@ import { logger, Filters } from "adminforth";
 import { randomUUID } from "crypto";
 import { VegaLiteStreamBuffer } from "../domain/vegaLiteStreamBuffer.js";
 import { getErrorMessage, isAbortError } from "../shared/errors.js";
+import { formatApprovalRequest } from "../tools/approvalFormatter.js";
 function getApprovalDecision(input) {
     return "approvalDecision" in input
         && (input.approvalDecision === "approve" || input.approvalDecision === "reject")
@@ -121,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;
     }
@@ -193,6 +217,7 @@ export class RunTurnUseCase {
                 mode,
                 context: this.buildContext(input, editTurnId),
                 observability: { emit: input.emit, sequenceDebugSink },
+                freshPrompt: true,
                 branchFromCheckpointId,
             };
         });
@@ -212,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,
@@ -238,9 +274,8 @@ export class RunTurnUseCase {
                     emit: input.emit,
                     sequenceDebugSink,
                 },
-                resume: shouldResume
-                    ? { decision: approvalDecision, interrupts: resumeInterrupts }
-                    : undefined,
+                freshPrompt: !shouldResume,
+                resume,
                 initialResponse,
             };
         });
@@ -248,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
@@ -277,16 +312,17 @@ export class RunTurnUseCase {
             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()]);
             }
             yield ((_c = (_b = prepared.observability).emit) === null || _c === void 0 ? void 0 : _c.call(_b, {
                 type: "interrupt",
                 sessionId: prepared.sessionId,
                 interrupt,
+                approvals: this.describeApprovals(descriptors),
             }));
         });
     }

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

@@ -14,7 +14,7 @@ type CreateAgentChatManagerOptions = {
   lastMessage: Ref<string>;
   activeModeName: Ref<string | null>;
   onOpenPage: (targetPath: string) => void;
-  onToolApprovalRequest: (sessionId: string, interrupt: unknown) => void;
+  onToolApprovalRequest: (sessionId: string, interrupt: unknown, approvals?: unknown) => void;
 };
 
 export function createAgentChatManager({
@@ -119,7 +119,7 @@ export function createAgentChatManager({
     }
 
     if (dataPart?.type === 'data-interrupt' && typeof dataPart.data?.sessionId === 'string') {
-      onToolApprovalRequest(dataPart.data.sessionId, dataPart.data.interrupt);
+      onToolApprovalRequest(dataPart.data.sessionId, dataPart.data.interrupt, dataPart.data.approvals);
       return;
     }
 
@@ -165,7 +165,7 @@ export function createAgentChatManager({
     }
 
     if (dataPart?.type === 'data-interrupt' && typeof dataPart.data?.sessionId === 'string') {
-      onToolApprovalRequest(dataPart.data.sessionId, dataPart.data.interrupt);
+      onToolApprovalRequest(dataPart.data.sessionId, dataPart.data.interrupt, dataPart.data.approvals);
       return;
     }
 

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,13 +123,13 @@ export const useAgentStore = defineStore('agent', () => {
     });
   }
 
-  function addToolApprovalMessage(sessionId: string, interrupt: unknown) {
+  function addToolApprovalPart(sessionId: string, messages: string[]) {
     const approvalPart = {
       type: 'data-tool-approval' as const,
       data: {
         sessionId,
         status: 'pending' as const,
-        messages: getToolApprovalMessages(interrupt),
+        messages,
       },
     };
     const lastChatMessage = currentChat.value?.lastMessage;
@@ -146,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) => {
@@ -167,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';
       }
@@ -231,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

@@ -7,25 +7,10 @@
       <div class="min-w-0 flex-1">
         <h3 class="text-sm font-semibold leading-5">{{ $t('Approval required') }}</h3>
         <p class="mt-1 text-sm leading-5 text-lightListTableText dark:text-darkListTableText">
-          {{ $t('Review the agent message before continuing.') }}
+          {{ $t('Review what the agent is about to do before continuing.') }}
         </p>
-        <button
-          v-if="data.messages?.length"
-          type="button"
-          class="mt-3 inline-flex items-center gap-2 text-sm font-medium text-lightListTableHeadingText transition hover:opacity-80 dark:text-darkListTableHeadingText"
-          @click="isExpanded = !isExpanded"
-        >
-          <IconChevronDownOutline
-            class="h-4 w-4 transition-transform"
-            :class="isExpanded ? 'rotate-180' : ''"
-          />
-          {{ isExpanded ? $t('Hide details') : $t('Show details') }}
-          <span class="rounded-full bg-lightListTableText/10 px-2 py-0.5 text-xs text-lightListTableHeadingText dark:bg-darkListTableText/10 dark:text-darkListTableHeadingText">
-            {{ data.messages.length }}
-          </span>
-        </button>
         <ul
-          v-if="isExpanded && data.messages?.length"
+          v-if="data.messages?.length"
           class="mt-3 space-y-1 text-sm leading-5 text-lightListTableHeadingText dark:text-darkListTableHeadingText"
         >
           <li
@@ -34,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>{{ message }}</span>
+            <span class="min-w-0 break-words">{{ message }}</span>
           </li>
         </ul>
         <div class="mt-4 flex flex-wrap gap-2">
@@ -58,15 +43,11 @@
           </template>
           <span
             v-else
-            class="inline-flex h-8 items-center gap-2 rounded-md border px-2.5 text-sm font-medium"
-            :class="data.status === 'processing'
-              ? 'border-lightListTableText/20 bg-lightListTableText/10 text-lightListTableHeadingText dark:border-darkListTableText/20 dark:bg-darkListTableText/10 dark:text-darkListTableHeadingText'
-              : data.status === 'approved'
-              ? 'border-lightListTableText/20 bg-lightListTableText/10 text-lightListTableHeadingText dark:border-darkListTableText/20 dark:bg-darkListTableText/10 dark:text-darkListTableHeadingText'
-              : 'border-lightListTableText/20 bg-lightListTableText/10 text-lightListTableHeadingText dark:border-darkListTableText/20 dark:bg-darkListTableText/10 dark:text-darkListTableHeadingText'"
+            class="inline-flex h-8 items-center gap-2 rounded-md border border-lightListTableText/20 bg-lightListTableText/10 px-2.5 text-sm font-medium text-lightListTableHeadingText dark:border-darkListTableText/20 dark:bg-darkListTableText/10 dark:text-darkListTableHeadingText"
           >
-            <IconCheckOutline v-if="data.status === 'approved'" class="h-4 w-4" />
-            <IconCloseOutline v-else-if="data.status === 'rejected'" class="h-4 w-4" />
+            <Spinner v-if="data.status === 'processing'" class="h-4 w-4" />
+            <IconCheckOutline v-else-if="data.status === 'approved'" class="h-4 w-4" />
+            <IconCloseOutline v-else class="h-4 w-4" />
             {{ data.status === 'processing' ? $t('Processing') : data.status === 'approved' ? $t('Approved') : $t('Rejected') }}
           </span>
         </div>
@@ -84,15 +65,14 @@
 <script setup lang="ts">
 import type { IPartData } from '../types';
 import { useAgentStore } from '../composables/useAgentStore';
-import { ref } from 'vue';
-import { IconCheckOutline, IconChevronDownOutline, IconCloseOutline, IconExclamationCircleOutline } from '@iconify-prerendered/vue-flowbite';
+import { Spinner } from '@/afcl';
+import { IconCheckOutline, IconCloseOutline, IconExclamationCircleOutline } from '@iconify-prerendered/vue-flowbite';
 
 const props = defineProps<{
   data: IPartData;
 }>();
 
 const agentStore = useAgentStore();
-const isExpanded = ref(false);
 
 function submit(decision: 'approve' | 'reject') {
   if (!props.data.sessionId || props.data.status !== 'pending') {

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/agentEvents.d.ts

@@ -19,6 +19,8 @@ export type AgentEvent = {
     type: "interrupt";
     sessionId: string;
     interrupt: unknown;
+    /** One plain-language line per pending tool call, for the approval card. */
+    approvals: string[];
 } | {
     type: "steer-applied";
     count: number;

package/dist/domain/turnTypes.d.ts

@@ -2,6 +2,7 @@ import type { AdminUser, AudioAdapter } from "adminforth";
 import type { DetectedLanguage } from "./languageDetect.js";
 import type { CurrentPageContext } from "../tools/getUserLocation.js";
 import type { AgentEventEmitter } from "./agentEvents.js";
+import type { ApprovalRequest } from "../tools/approvalFormatter.js";
 /**
  * Minimal sink the application layer uses to persist per-turn debug traces. The
  * concrete implementation (the sequence-debug collector) lives in the llm layer;
@@ -15,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;

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,7 +1,8 @@
 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[];
 type RawStreamEntry = ["messages", [any, any]] | ["updates", Record<string, any>];

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,7 +54,11 @@ 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),
+                }]
             : [];
     });
 }
@@ -62,7 +80,11 @@ export function parseRawStreamChunk(entry) {
     if (mode === "updates") {
         if (chunk && typeof chunk === "object" && "__interrupt__" in chunk) {
             const interrupt = chunk.__interrupt__;
-            return [{ kind: "interrupt", interrupt, descriptors: normalizeInterrupts(interrupt) }];
+            return [{
+                    kind: "interrupt",
+                    interrupt,
+                    descriptors: normalizeInterrupts(interrupt),
+                }];
         }
         return [];
     }

package/dist/tools/approvalFormatter.d.ts

@@ -0,0 +1,12 @@
+import type { IAdminForth } from "adminforth";
+/** One tool call awaiting approval, normalized out of the provider interrupt payload. */
+export type ApprovalRequest = {
+    toolName: string;
+    args: Record<string, unknown>;
+};
+/**
+ * Describe a tool call awaiting approval in a sentence an admin (not a developer) can
+ * act on — resource and column labels instead of ids, values instead of raw JSON.
+ * Falls back to a key/value dump for tool calls it does not recognize.
+ */
+export declare function formatApprovalRequest(adminforth: IAdminForth, request: ApprovalRequest): string;

package/dist/tools/approvalFormatter.js

@@ -0,0 +1,104 @@
+/** Argument keys that address the call itself rather than the data being changed. */
+const NON_FIELD_KEYS = new Set(["resourceId", "recordId", "primaryKey", "requiredColumnsToSkip", "meta", "extra"]);
+const MAX_VALUE_LENGTH = 80;
+const MAX_FIELDS = 12;
+function truncate(text, limit = MAX_VALUE_LENGTH) {
+    return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+function findResource(adminforth, resourceId) {
+    var _a, _b;
+    return typeof resourceId === "string"
+        ? ((_b = (_a = adminforth.config) === null || _a === void 0 ? void 0 : _a.resources) !== null && _b !== void 0 ? _b : []).find((resource) => resource.resourceId === resourceId)
+        : undefined;
+}
+function resourceLabel(resource, args) {
+    var _a;
+    return (_a = resource === null || resource === void 0 ? void 0 : resource.label) !== null && _a !== void 0 ? _a : (typeof args.resourceId === "string" ? args.resourceId : "resource");
+}
+/** `first_name` / `firstName` -> `First name`, for keys the resource does not declare. */
+function humanize(name) {
+    const spaced = name.replace(/[_-]+/g, " ").replace(/([a-z\d])([A-Z])/g, "$1 $2").trim();
+    return spaced ? `${spaced[0].toUpperCase()}${spaced.slice(1).toLowerCase()}` : name;
+}
+function formatValue(value, column) {
+    var _a;
+    if (value === undefined || value === null || value === "") {
+        return "empty";
+    }
+    if ((column === null || column === void 0 ? void 0 : column.masked) || (column === null || column === void 0 ? void 0 : column.backendOnly)) {
+        return "••••••";
+    }
+    if (typeof value === "boolean") {
+        return value ? "Yes" : "No";
+    }
+    const enumLabel = Array.isArray(column === null || column === void 0 ? void 0 : column.enum)
+        ? (_a = column.enum.find((item) => item.value === value)) === null || _a === void 0 ? void 0 : _a.label
+        : undefined;
+    if (enumLabel) {
+        return truncate(String(enumLabel));
+    }
+    if (Array.isArray(value)) {
+        return truncate(value.map((item) => formatValue(item)).join(", "));
+    }
+    if (typeof value === "object") {
+        return truncate(JSON.stringify(value));
+    }
+    return truncate(String(value));
+}
+/** `Brand: Tesla, Price: 45000` — the record payload in the resource's own wording. */
+function formatRecord(record, resource) {
+    var _a;
+    if (record === null || typeof record !== "object" || Array.isArray(record)) {
+        return "";
+    }
+    const columnsByName = new Map(((_a = resource === null || resource === void 0 ? void 0 : resource.columns) !== null && _a !== void 0 ? _a : []).map((column) => [column.name, column]));
+    const entries = Object.entries(record)
+        .filter(([key]) => !NON_FIELD_KEYS.has(key));
+    const shown = entries.slice(0, MAX_FIELDS).map(([name, value]) => {
+        const column = columnsByName.get(name);
+        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(", ");
+}
+function actionLabel(resource, actionId) {
+    var _a, _b;
+    if (typeof actionId !== "string" || !actionId) {
+        return "action";
+    }
+    const action = ((_b = (_a = resource === null || resource === void 0 ? void 0 : resource.options) === null || _a === void 0 ? void 0 : _a.actions) !== null && _b !== void 0 ? _b : []).find((candidate) => candidate.id === actionId);
+    return `"${(action === null || action === void 0 ? void 0 : action.name) || humanize(actionId)}"`;
+}
+/**
+ * Describe a tool call awaiting approval in a sentence an admin (not a developer) can
+ * act on — resource and column labels instead of ids, values instead of raw JSON.
+ * Falls back to a key/value dump for tool calls it does not recognize.
+ */
+export function formatApprovalRequest(adminforth, request) {
+    const { args, toolName } = request;
+    const resource = findResource(adminforth, args.resourceId);
+    const label = resourceLabel(resource, args);
+    switch (toolName) {
+        case "create_record": {
+            const fields = formatRecord(args.record, resource);
+            return `Create a new record in ${label}${fields ? ` — ${fields}` : ""}`;
+        }
+        case "update_record": {
+            const fields = formatRecord(args.record, resource);
+            return `Update record with id:${formatValue(args.recordId)} in ${label}${fields ? ` — set ${fields}` : ""}`;
+        }
+        case "delete_record":
+            return `Delete record with id:${formatValue(args.primaryKey)} from ${label} — this cannot be undone`;
+        case "start_custom_action":
+            return `Run ${actionLabel(resource, args.actionId)} on record ${formatValue(args.recordId)} in ${label}`;
+        case "start_custom_bulk_action":
+        case "start_bulk_action": {
+            const count = Array.isArray(args.recordIds) ? args.recordIds.length : 0;
+            return `Run ${actionLabel(resource, args.actionId)} on ${count} record(s) in ${label}`;
+        }
+        default: {
+            const fields = formatRecord(args, resource);
+            return `${humanize(toolName)}${fields ? ` — ${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/dist/transport/sse/sseWriter.js

@@ -88,13 +88,14 @@ function createAgentEventStream(res, options = {}) {
                 },
             });
         },
-        interrupt(sessionId, interrupt) {
+        interrupt(sessionId, interrupt, approvals) {
             stream.endActiveBlock();
             stream.send({
                 type: isAiUiMessageStream ? "data-interrupt" : "interrupt",
                 data: {
                     sessionId,
                     interrupt,
+                    approvals,
                 },
             });
         },
@@ -238,7 +239,7 @@ export function createSseEventEmitter(res, options = {}) {
                 stream.rendering(event.phase, event.label);
                 break;
             case "interrupt":
-                stream.interrupt(event.sessionId, event.interrupt);
+                stream.interrupt(event.sessionId, event.interrupt, event.approvals);
                 break;
             case "steer-applied":
                 stream.steerApplied(event.count, event.ids);

package/package.json

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