@adminforth/agent 2.7.4 → 2.8.0

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

@@ -3,7 +3,7 @@ import type { AgentSessionStore } from "../persistence/sessionStore.js";
 import type { SteerBuffer } from "../domain/steerBuffer.js";
 import type { PluginOptions } from "../types.js";
 import type { LlmPort } from "./ports.js";
-import type { DebugSink, HandleTurnInput, HandleEditTurnInput, PendingInterrupt, RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult } from "../domain/turnTypes.js";
+import type { BaseAgentTurnInput, DebugSink, HandleTurnInput, HandleEditTurnInput, PendingInterrupt, RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult } from "../domain/turnTypes.js";
 /**
  * Build the provider-agnostic resume payload for a human-in-the-loop turn.
  * Exported for unit testing; the LLM port wraps it into a LangGraph Command.
@@ -72,7 +72,7 @@ export declare class RunTurnUseCase {
     private resolvePendingInterrupts;
     private requiresSessionOwnership;
     /** Verify the session exists and belongs to the requesting admin user. */
-    private assertSessionOwnership;
+    assertSessionOwnership(sessionId: string, adminUser: BaseAgentTurnInput["adminUser"]): Promise<void>;
     /**
      * Prepare an edit/branch turn: resolve the fork checkpoint from the previous turn,
      * truncate the conversation after the edited turn, and reuse the edited turn's id

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")
@@ -272,7 +273,7 @@ export class RunTurnUseCase {
     buildMessages(prepared) {
         return [{ role: "user", content: prepared.prompt }];
     }
-    handleInterrupt(prepared, interrupt, descriptors) {
+    handleInterrupt(prepared, interrupt, descriptors, requests) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             if (!this.deps.hasPersistentCheckpointer) {
@@ -283,16 +284,19 @@ export class RunTurnUseCase {
                 }
                 this.pendingInterrupts.set(prepared.sessionId, [...merged.entries()].map(([id, count]) => ({ id, count })));
             }
+            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)),
             }));
         });
     }
     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
                 ? {
@@ -318,16 +322,16 @@ export class RunTurnUseCase {
             let interrupted = false;
             try {
                 try {
-                    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) {
+                    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) {
                         _c = stream_1_1.value;
-                        _d = false;
+                        _e = 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);
+                            yield this.handleInterrupt(prepared, chunk.interrupt, chunk.descriptors, (_d = chunk.requests) !== null && _d !== void 0 ? _d : []);
                             continue;
                         }
                         if (chunk.kind === "reasoning") {
@@ -345,7 +349,7 @@ export class RunTurnUseCase {
                 catch (e_1_1) { e_1 = { error: e_1_1 }; }
                 finally {
                     try {
-                        if (!_d && !_a && (_b = stream_1.return)) yield _b.call(stream_1);
+                        if (!_e && !_a && (_b = stream_1.return)) yield _b.call(stream_1);
                     }
                     finally { if (e_1) throw e_1.error; }
                 }

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/useAgentStore.ts

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

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/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;
@@ -97,4 +98,6 @@ 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

@@ -154,10 +154,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             handleTurn: this.runTurnUseCase.handleTurn.bind(this.runTurnUseCase),
             handleEditTurn: this.runTurnUseCase.handleEditTurn.bind(this.runTurnUseCase),
             handleSpeechTurn: this.speechTurnService.handle.bind(this.speechTurnService),
-            steer: ({ sessionId, message }) => {
+            steer: (_a) => __awaiter(this, [_a], void 0, function* ({ sessionId, message, adminUser }) {
+                yield this.runTurnUseCase.assertSessionOwnership(sessionId, adminUser);
                 const { id } = this.steerBuffer.add(sessionId, message);
                 return { id, queued: this.steerBuffer.size(sessionId) };
-            },
+            }),
             runAndPersistAgentResponse: this.runTurnUseCase.runAndPersistAgentResponse.bind(this.runTurnUseCase),
             getSessionTurns: this.sessionStore.getSessionTurns.bind(this.sessionStore),
             createNewTurn: this.sessionStore.createNewTurn.bind(this.sessionStore),

package/dist/llm/streamAdapter.d.ts

@@ -1,9 +1,16 @@
+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.
  */
 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

@@ -44,6 +44,31 @@ export function normalizeInterrupts(interrupt) {
             : [];
     });
 }
+/**
+ * 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;
@@ -62,7 +87,12 @@ 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),
+                    requests: extractApprovalRequests(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

@@ -15,10 +15,11 @@ export type AgentEndpointsContext = {
     steer(input: {
         sessionId: string;
         message: string;
-    }): {
+        adminUser: any;
+    }): Promise<{
         id: string;
         queued: number;
-    };
+    }>;
     runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput): Promise<RunAndPersistAgentResponseResult>;
     getSessionTurns(sessionId: string): Promise<SessionTurn[]>;
     createNewTurn(sessionId: string, prompt: string, response?: string): Promise<string>;

package/dist/transport/http/coreEndpoints.js

@@ -167,14 +167,15 @@ export function setupCoreEndpoints(ctx, server) {
         method: 'POST',
         path: `/agent/steer`,
         request_schema: agentSteerBodySchema,
-        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body }) {
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser }) {
             const data = body;
             // Fire-and-forget: the steer is buffered and folded into the running turn by the
             // beforeModel steer middleware, which signals `data-steer-applied` on that turn's
             // SSE stream once consumed. This endpoint only confirms it was received/queued.
-            const { id, queued } = ctx.steer({
+            const { id, queued } = yield ctx.steer({
                 sessionId: data.sessionId,
                 message: data.message,
+                adminUser: adminUser
             });
             return { ok: true, id, queued };
         })

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.4",
+  "version": "2.8.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",