@adminforth/agent 1.51.1 → 1.52.0

package/agent/middleware/apiBasedTools.ts

@@ -1,4 +1,5 @@
 import { ToolMessage } from "@langchain/core/messages";
+import { isGraphInterrupt } from "@langchain/langgraph";
 import { createMiddleware } from "langchain";
 import { logger, type AdminUser, type IAdminForth } from "adminforth";
 import {
@@ -13,6 +14,7 @@ import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "../tools/index.js";
 import { createApiTool } from "../tools/apiTool.js";
 import type { AgentEventEmitter } from "../../agentEvents.js";
 import type { SequenceDebugCollector } from "./sequenceDebug.js";
+import { isAbortError } from "../../errors.js";
 
 function getEnabledApiToolNames(messages: unknown[]) {
   const enabledToolNames = new Set<string>();
@@ -82,8 +84,14 @@ export function createApiBasedToolsMiddleware(
     async wrapToolCall(request, handler) {
       const startedAt = Date.now();
       const toolInput = JSON.stringify(request.toolCall.args ?? {});
-      const { adminUser, emit, sequenceDebugSink, userTimeZone } = request.runtime.context as {
+      if (!request.toolCall.id) {
+        throw new Error(`Tool call "${request.toolCall.name}" has no id.`);
+      }
+
+      const toolCallId = request.toolCall.id;
+      const { adminUser, abortSignal, emit, sequenceDebugSink, userTimeZone } = request.runtime.context as {
         adminUser: AdminUser;
+        abortSignal?: AbortSignal;
         emit?: AgentEventEmitter;
         sequenceDebugSink: SequenceDebugCollector;
         userTimeZone: string;
@@ -113,7 +121,7 @@ export function createApiBasedToolsMiddleware(
       }
       const toolCallTracker = createToolCallTracker({
         emit: emitToolCall,
-        toolCallId: request.toolCall.id,
+        toolCallId,
         toolName: request.toolCall.name,
         toolInfo,
         input: toolArgs,
@@ -125,39 +133,37 @@ export function createApiBasedToolsMiddleware(
       );
 
       try {
-        let result;
-
-        if (request.tool) {
-          result = await handler(request);
-        } else {
-          const enabledApiToolNames = getEnabledApiToolNames(request.state.messages);
 
-          if (enabledApiToolNames.has(request.toolCall.name)) {
-            result = await handler({
+        const result = getEnabledApiToolNames(request.state.messages).has(request.toolCall.name)
+          ? await handler({
               ...request,
               tool: dynamicTools[request.toolCall.name],
-            });
-          } else {
-            result = new ToolMessage({
-              content: `Tool "${request.toolCall.name}" is not loaded. Call fetch_tool_schema first.`,
-              tool_call_id: request.toolCall.id ?? "",
-              name: request.toolCall.name,
-              status: "error",
-            });
-          }
-        }
+            })
+          : await handler(request);
 
         toolCallTracker.finishSuccess(result);
         return result;
       } catch (error) {
-        const errorDetails =
-          error instanceof Error ? error.stack ?? error.message : String(error);
+        if (
+          isGraphInterrupt(error)
+          || abortSignal?.aborted
+          || isAbortError(error)
+        ) {
+          throw error;
+        }
+
+        const message = error instanceof Error ? error.message : String(error);
 
         logger.error(
-          `Tool "${request.toolCall.name}" failed after ${Date.now() - startedAt}ms with input: ${toolInput}\n${errorDetails}`,
+          `Error calling tool "${request.toolCall.name}": ${error instanceof Error ? error.stack ?? error.message : String(error)}`,
         );
-        toolCallTracker.finishError(error);
-        throw error;
+        toolCallTracker.finishError(`Error: ${message}`);
+        return new ToolMessage({
+          name: request.toolCall.name,
+          tool_call_id: toolCallId,
+          status: "error",
+          content: `Error: ${message}`,
+        })
       } finally {
         logger.info(
           `Tool "${request.toolCall.name}" finished in ${Date.now() - startedAt}ms`,

package/agent/runtime/AgentRuntime.ts

@@ -1,5 +1,5 @@
 import type { IAdminForth } from "adminforth";
-import { createAgent, summarizationMiddleware } from "langchain";
+import { createAgent, summarizationMiddleware, humanInTheLoopMiddleware } from "langchain";
 import type { BaseCheckpointSaver } from "@langchain/langgraph";
 import { createApiBasedToolsMiddleware } from "../middleware/apiBasedTools.js";
 import { createSequenceDebugMiddleware } from "../middleware/sequenceDebug.js";
@@ -7,6 +7,22 @@ import { createAgentLlmMetricsLogger } from "../simpleAgent.js";
 import type { AgentToolProvider } from "../tools/AgentToolProvider.js";
 import type { AgentRuntimeRunInput } from "../turn/turnTypes.js";
 import { contextSchema, toLangchainAgentContext } from "./AgentContext.js";
+import type { ApiBasedTool } from "../../apiBasedTools.js";
+
+function createHumanInTheLoopInterrupts(
+  apiBasedTools: Record<string, ApiBasedTool>,
+): Record<string, { allowedDecisions: ("approve" | "reject" | "edit")[] }> {
+  return Object.fromEntries(
+    Object.entries(apiBasedTools)
+      .filter(([, apiBasedTool]) => apiBasedTool.agent?.isDangerous === true)
+      .map(([toolName]) => [
+        toolName,
+        {
+          allowedDecisions: ["approve", "reject"],
+        },
+      ]),
+  );
+}
 
 export type AgentRuntimeOptions = {
   name: string;
@@ -29,8 +45,13 @@ export class AgentRuntime {
     const sequenceDebugMiddleware = createSequenceDebugMiddleware(
       input.observability.sequenceDebugSink,
     );
+    const hitlMiddleware = humanInTheLoopMiddleware({
+      interruptOn: createHumanInTheLoopInterrupts(apiBasedTools),
+      descriptionPrefix: "Tool execution pending approval",
+    });
     const middleware = [
       apiBasedToolsMiddleware,
+      hitlMiddleware,
       ...(input.models.modelMiddleware ?? []),
       sequenceDebugMiddleware,
       summarizationMiddleware({
@@ -49,8 +70,8 @@ export class AgentRuntime {
       middleware,
     });
 
-    return agent.stream({ messages: input.messages } as any, {
-      streamMode: "messages",
+    return agent.stream(input.input as any, {
+      streamMode: ["messages", "updates"],
       recursionLimit: 100,
       callbacks: [createAgentLlmMetricsLogger()],
       signal: input.context.abortSignal,

package/agent/systemPrompt.ts

@@ -25,11 +25,8 @@ export const DEFAULT_AGENT_SYSTEM_PROMPT = [
   "Do not add extra explanations or suggestions unless the user asks.",
   "Adapt to the user's tone and style of speaking, mirroring their vibe and wording.",
   "if the user speaks casually, you should respond casually too",
-  "Never mutate data without user confirmation for a clearly described mutation plan.",
-  "One confirmation may cover one mutation or one explicitly described batch/sequence of related mutations.",
-  "If the confirmed plan has multiple steps, you may execute the whole confirmed plan without asking again between those steps.",
-  "If the plan changes, expands, or you want to do anything beyond the confirmed plan, ask for confirmation again.",
-  "Do not reuse an old confirmation for a new mutation plan.",
+  "Before calling a dangerous tool, briefly describe the exact action, target, and important changes in chat.",
+  "Do not ask the user for textual confirmation; dangerous tools are approved by the runtime approval UI.",
 ].join(" ");
 
 export function appendCustomSystemPrompt(
@@ -124,7 +121,7 @@ export async function buildAgentSystemPrompt(
     "If the user wants to fetch records, load fetch_data first. If the user wants analytics or charts, load analyze_data first.",
     "Only call fetch_tool_schema for tool names that are explicitly mentioned in a fetched skill and are not already available as base tools.",
     "If a fetched skill lists a non-base tool you need, call fetch_tool_schema for it immediately instead of telling the user the tool is unavailable.",
-    "For example: for record creation load mutate_data, read its tool list, call fetch_tool_schema for create_record, and then use create_record after confirmation.",
+    "For example: for record creation load mutate_data, read its tool list, call fetch_tool_schema for create_record, describe the planned record, and then use create_record.",
     "When fetch_tool_schema succeeds, that tool becomes available on the next step.",
     "All admin links must be root-relative and start with '/'.",
     "Build record links as '/resource/{resourceId}/show/{primary key}'. Never use bare 'resource/{resourceId}/show/{primary key}' without the leading slash.",

package/agent/turn/TurnLifecycleService.ts

@@ -1,4 +1,5 @@
 import type { AgentSessionStore } from "../../sessionStore.js";
+import type { PluginOptions } from "../../types.js";
 import type { BaseAgentTurnInput } from "./turnTypes.js";
 import { TurnPersistenceService } from "./TurnPersistenceService.js";
 
@@ -6,6 +7,7 @@ export class TurnLifecycleService {
   constructor(
     private readonly sessionStore: AgentSessionStore,
     private readonly persistence: TurnPersistenceService,
+    private readonly options: PluginOptions,
   ) {}
 
   async start(input: BaseAgentTurnInput) {
@@ -19,6 +21,22 @@ export class TurnLifecycleService {
     };
   }
 
+  async resume(input: BaseAgentTurnInput) {
+    const latestTurn = await this.sessionStore.getLatestTurn(input.sessionId);
+
+    if (!latestTurn) {
+      throw new Error(`No agent turn found for session "${input.sessionId}".`);
+    }
+
+    return {
+      turnId: latestTurn[this.options.turnResource.idField],
+      previousUserMessages: await this.sessionStore.getPreviousUserMessages(input.sessionId),
+      initialResponse: latestTurn[this.options.turnResource.responseField] === "not_finished"
+        ? ""
+        : String(latestTurn[this.options.turnResource.responseField]),
+    };
+  }
+
   async finish(input: {
     turnId: string;
     responseText: string;

package/agent/turn/TurnStreamConsumer.ts

@@ -3,19 +3,27 @@ import { VegaLiteStreamBuffer } from "./VegaLiteStreamBuffer.js";
 
 export class TurnStreamConsumer {
   async consume(input: {
-    stream: AsyncIterable<[any, any]>;
+    stream: AsyncIterable<["messages", [any, any]] | ["updates", Record<string, any>]>;
     abortSignal?: AbortSignal;
     emit?: AgentEventEmitter;
+    onInterrupt?: (interrupt: unknown) => void | Promise<void>;
   }) {
     let fullResponse = "";
     const textBuffer = new VegaLiteStreamBuffer();
 
-    for await (const rawChunk of input.stream) {
+    for await (const [mode, chunk] of input.stream) {
       if (input.abortSignal?.aborted) {
         throw new DOMException("This operation was aborted", "AbortError");
       }
 
-      const [token, metadata] = rawChunk;
+      if (mode === "updates") {
+        if ("__interrupt__" in chunk) {
+          await input.onInterrupt?.(chunk.__interrupt__);
+        }
+        continue;
+      }
+
+      const [token, metadata] = chunk;
       const nodeName =
         typeof metadata?.langgraph_node === "string"
           ? metadata.langgraph_node

package/agent/turn/turnTypes.ts

@@ -1,5 +1,6 @@
 import type { AdminUser, AudioAdapter } from "adminforth";
 import type { Messages } from "@langchain/langgraph";
+import type { Command } from "@langchain/langgraph";
 import type { AgentChatModel, AgentMiddleware } from "../simpleAgent.js";
 import type { SequenceDebugCollector } from "../middleware/sequenceDebug.js";
 import type { PreviousUserMessage } from "../languageDetect.js";
@@ -20,6 +21,7 @@ export type BaseAgentTurnInput = {
 
 export type TextAgentTurnInput = BaseAgentTurnInput & {
   emit: AgentEventEmitter;
+  approvalDecision?: "approve" | "reject";
   failureLogMessage?: string;
   abortLogMessage?: string;
 };
@@ -60,6 +62,11 @@ export type PreparedAgentTurn = {
   modeName?: string | null;
   context: AgentTurnContext;
   observability: AgentTurnObservability;
+  resume?: {
+    decision: "approve" | "reject";
+    interrupts?: { id: string; count: number }[];
+  };
+  initialResponse?: string;
 };
 
 export type AgentTurnModels = {
@@ -70,13 +77,14 @@ export type AgentTurnModels = {
 
 export type AgentRuntimeRunInput = {
   models: AgentTurnModels;
-  messages: Messages;
+  input: { messages: Messages } | Command;
   context: AgentTurnContext;
   observability: AgentTurnObservability;
 };
 
 export type RunAndPersistAgentResponseInput = BaseAgentTurnInput & {
   emit?: AgentEventEmitter;
+  approvalDecision?: "approve" | "reject";
   failureLogMessage: string;
   abortLogMessage: string;
 };

package/agentEvents.ts

@@ -22,6 +22,11 @@ export type AgentEvent =
       phase: "start" | "end";
       label: string;
     }
+  | {
+      type: "interrupt";
+      sessionId: string;
+      interrupt: unknown;
+    }
   | {
       type: "open-page";
       targetPath: string;

package/agentTurnService.ts

@@ -1,5 +1,6 @@
 import { logger } from "adminforth";
 import { randomUUID } from "crypto";
+import { Command } from "@langchain/langgraph";
 import { AgentModelFactory } from "./agent/models/AgentModelFactory.js";
 import { AgentModeResolver } from "./agent/models/AgentModeResolver.js";
 import { createSequenceDebugCollector } from "./agent/middleware/sequenceDebug.js";
@@ -25,7 +26,94 @@ export type {
   RunAndPersistAgentResponseResult,
 } from "./agent/turn/turnTypes.js";
 
+function getApprovalDecision(input: BaseAgentTurnInput) {
+  return "approvalDecision" in input
+    && (input.approvalDecision === "approve" || input.approvalDecision === "reject")
+    ? input.approvalDecision
+    : undefined;
+}
+
+function getInterruptItems(interrupt: unknown): unknown[] {
+  return Array.isArray(interrupt) ? interrupt : [interrupt];
+}
+
+function getHitlInterrupts(interrupt: unknown): { id: string; count: number }[] {
+  return getInterruptItems(interrupt).flatMap((item) => {
+    const value = item && typeof item === "object" && "value" in item
+      ? (item as { value: unknown }).value
+      : item;
+    const actionRequests = value && typeof value === "object"
+      ? (value as { actionRequests?: unknown }).actionRequests
+      : undefined;
+    const interruptId = item && typeof item === "object"
+      ? (item as { id?: unknown }).id
+      : undefined;
+
+    return typeof interruptId === "string" && Array.isArray(actionRequests)
+      ? [{ id: interruptId, count: actionRequests.length }]
+      : [];
+  });
+}
+
+function buildHitlDecision(decision: "approve" | "reject", prompt?: string) {
+  if (decision === "approve") {
+    return { type: "approve" as const };
+  }
+
+  return {
+    type: "reject" as const,
+    message: prompt
+      ? `User rejected the pending tool execution and sent a new instruction instead: ${prompt}`
+      : "User rejected executing this tool",
+  };
+}
+
+function buildHitlResumeValue(input: {
+  decision: "approve" | "reject";
+  count: number;
+  prompt?: string;
+}) {
+  return {
+    decisions: Array.from({ length: input.count }, () => (
+      buildHitlDecision(input.decision, input.prompt)
+    )),
+  };
+}
+
+function buildLangGraphResume(input: {
+  decision: "approve" | "reject";
+  interrupts?: { id: string; count: number }[];
+  prompt?: string;
+}) {
+  const interrupts = input.interrupts ?? [];
+
+  if (interrupts.length === 0) {
+    throw new Error("No pending approval interrupt found for resume.");
+  }
+
+  if (interrupts.length === 1) {
+    return buildHitlResumeValue({
+      decision: input.decision,
+      count: interrupts[0].count,
+      prompt: input.prompt,
+    });
+  }
+
+  return Object.fromEntries(
+    interrupts.map((interrupt) => [
+      interrupt.id,
+      buildHitlResumeValue({
+        decision: input.decision,
+        count: interrupt.count,
+        prompt: input.prompt,
+      }),
+    ]),
+  );
+}
+
 export class AgentTurnService {
+  private readonly pendingInterrupts = new Map<string, { id: string; count: number }[]>();
+
   constructor(
     private readonly lifecycle: TurnLifecycleService,
     private readonly contextBuilder: TurnContextBuilder,
@@ -38,23 +126,40 @@ export class AgentTurnService {
 
   private async prepareTurn(input: BaseAgentTurnInput): Promise<PreparedAgentTurn> {
     const sequenceDebugCollector = createSequenceDebugCollector();
-    const { turnId, previousUserMessages } = await this.lifecycle.start(input);
+    const approvalDecision = getApprovalDecision(input);
+    const shouldResume = Boolean(approvalDecision);
+    const pendingInterrupts = this.pendingInterrupts.get(input.sessionId);
+    if (shouldResume && (!pendingInterrupts || pendingInterrupts.length === 0)) {
+      throw new Error(`No pending approval interrupt found for session "${input.sessionId}".`);
+    }
+    const lifecycleTurn = shouldResume
+      ? await this.lifecycle.resume(input)
+      : await this.lifecycle.start(input);
     const context = await this.contextBuilder.build({
       base: input,
-      turnId,
+      turnId: lifecycleTurn.turnId,
     });
 
     return {
       prompt: input.prompt,
       sessionId: input.sessionId,
-      turnId,
-      previousUserMessages,
+      turnId: lifecycleTurn.turnId,
+      previousUserMessages: lifecycleTurn.previousUserMessages,
       modeName: input.modeName,
       context,
       observability: {
         emit: undefined,
         sequenceDebugSink: sequenceDebugCollector,
       },
+      resume: shouldResume
+        ? {
+            decision: approvalDecision!,
+            interrupts: pendingInterrupts,
+          }
+        : undefined,
+      initialResponse: shouldResume && "initialResponse" in lifecycleTurn
+        ? (lifecycleTurn as { initialResponse?: string }).initialResponse
+        : undefined,
     };
   }
 
@@ -73,16 +178,56 @@ export class AgentTurnService {
     ]);
     const stream = await this.runtime.stream({
       models,
-      messages,
+      input: input.resume
+        ? new Command({
+            resume: buildLangGraphResume({
+              decision: input.resume.decision,
+              interrupts: input.resume.interrupts,
+              prompt: input.prompt,
+            }),
+          })
+        : { messages },
       context: input.context,
       observability: input.observability,
     });
 
-    return this.streamConsumer.consume({
-      stream: stream as AsyncIterable<[any, any]>,
-      abortSignal: input.context.abortSignal,
-      emit: input.observability.emit,
-    });
+    let interrupted = false;
+    try {
+      return await this.streamConsumer.consume({
+        stream: stream as AsyncIterable<["messages", [any, any]] | ["updates", Record<string, any>]>,
+        abortSignal: input.context.abortSignal,
+        emit: input.observability.emit,
+        onInterrupt: async (interrupt) => {
+          interrupted = true;
+          const interrupts = getHitlInterrupts(interrupt);
+          const pendingInterrupts = this.pendingInterrupts.get(input.sessionId) ?? [];
+          const mergedInterrupts = new Map(
+            pendingInterrupts.map((pendingInterrupt) => [
+              pendingInterrupt.id,
+              pendingInterrupt.count,
+            ]),
+          );
+
+          for (const pendingInterrupt of interrupts) {
+            mergedInterrupts.set(pendingInterrupt.id, pendingInterrupt.count);
+          }
+
+          this.pendingInterrupts.set(
+            input.sessionId,
+            [...mergedInterrupts.entries()].map(([id, count]) => ({ id, count })),
+          );
+          await input.observability.emit?.({
+            type: "interrupt",
+            sessionId: input.sessionId,
+            interrupt,
+          });
+        },
+      });
+    } finally {
+      if (!interrupted) {
+        this.pendingInterrupts.delete(input.sessionId);
+      }
+    }
   }
 
   async runAndPersistAgentResponse(
@@ -91,13 +236,13 @@ export class AgentTurnService {
     const preparedTurn = await this.prepareTurn(input);
     preparedTurn.observability.emit = input.emit;
 
-    let fullResponse = "";
+    let fullResponse = preparedTurn.initialResponse ?? "";
     let aborted = false;
     let failed = false;
 
     try {
       const agentResponse = await this.runAgentTurn(preparedTurn);
-      fullResponse = agentResponse.text;
+      fullResponse += agentResponse.text;
     } catch (error) {
       if (input.abortSignal?.aborted || isAbortError(error)) {
         aborted = true;
@@ -138,6 +283,7 @@ export class AgentTurnService {
       currentPage: input.currentPage,
       chatSurface: input.chatSurface,
       adminPublicOrigin: input.adminPublicOrigin,
+      approvalDecision: input.approvalDecision,
       abortSignal: input.abortSignal,
       adminUser: input.adminUser,
       emit: input.emit,

package/apiBasedTools.ts

@@ -39,10 +39,15 @@ type GetResourceDataToolResponse = {
 type DateTimeColumnType = AdminForthDataTypes.DATETIME | AdminForthDataTypes.TIME;
 type RegisteredApiToolSchema = IRegisteredApiSchema & {
   handler: (input: unknown) => void | Promise<unknown>;
+  agent?: AgentToolMeta;
 };
 
 const DEFAULT_USER_TIME_ZONE = 'UTC';
 
+type AgentToolMeta = {
+  isDangerous?: boolean;
+};
+
 function hasRegisteredApiToolHandler(schema: IRegisteredApiSchema): schema is RegisteredApiToolSchema {
   return typeof (schema as { handler?: unknown }).handler === 'function';
 }
@@ -175,6 +180,7 @@ export type ApiBasedToolCallParams = {
 export type ApiBasedTool = {
   description?: string;
   input_schema?: unknown;
+  agent?: AgentToolMeta;
   call: (params?: ApiBasedToolCallParams) => Promise<string>;
 };
 
@@ -615,6 +621,7 @@ export function prepareApiBasedTools(
     apiBasedTools[toolName] = {
       description: schema.description,
       input_schema: schema.request_schema,
+      agent: schema.agent,
       call: async ({ adminUser, adminuser, abortSignal, inputs, userTimeZone, acceptLanguage } = {}) => {
         if (isHiddenResourceCall(hiddenResourceIdSet, inputs)) {
           return YAML.stringify({

package/build.log

@@ -36,6 +36,7 @@ custom/conversation_area/ReasoningRenderer.vue
 custom/conversation_area/SystemMessageRenderer.vue
 custom/conversation_area/TextRenderer.vue
 custom/conversation_area/ThreeDotsAnimation.vue
+custom/conversation_area/ToolApprovalRenderer.vue
 custom/conversation_area/ToolRenderer.vue
 custom/conversation_area/ToolsGroup.vue
 custom/incremark_code_renderers/
@@ -62,5 +63,5 @@ custom/speech_recognition_frontend/voiceActivityDetection.ts
 custom/speech_recognition_frontend/types/
 custom/speech_recognition_frontend/types/voice-activity-detection.d.ts
 
-sent 1,670,885 bytes  received 921 bytes  3,343,612.00 bytes/sec
-total size is 1,666,790  speedup is 1.00
+sent 1,682,590 bytes  received 940 bytes  3,367,060.00 bytes/sec
+total size is 1,678,362  speedup is 1.00

package/custom/ChatFooter.vue

@@ -20,7 +20,8 @@
           'min-h-12 px-4 pt-4 rounded-xl w-full resize-none overflow-hidden text-lightInputText dark:text-darkInputText rounded-md bg-transparent text-sm bg-gray-50 dark:bg-gray-700 dark:border-gray-600 focus:outline-none',
           { '!text-base': coreStore.isIos }
         ]"
-        :placeholder="agentStore.userMessagePlaceholder"
+        :placeholder="agentStore.hasPendingToolApproval ? 'Approve or reject the pending action to continue' : agentStore.userMessagePlaceholder"
+        :disabled="agentStore.isMessageInputBlocked"
         @keydown.enter.exact.prevent="sendMessage"
       />
       <div
@@ -70,7 +71,7 @@
           v-if="!agentStore.isResponseInProgress"
           class="absolute right-4 bottom-2 !p-0 h-9 w-9 transition-opacity duration-200"                    
           @click="sendMessage" 
-          :disabled="!agentStore.trimmedUserMessage || agentStore.isResponseInProgress"
+          :disabled="!agentStore.trimmedUserMessage || agentStore.isMessageInputBlocked"
         >
           <IconArrowUpOutline 
             class="w-8 h-8 p-1