@codemation/core-nodes 0.8.0 → 0.9.0

package/dist/metadata.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "packageName": "@codemation/core-nodes",
-  "packageVersion": "0.8.0",
+  "packageVersion": "0.9.0",
   "description": "",
   "kind": "nodes",
   "nodes": [
@@ -15,7 +15,7 @@
       "outputPorts": [
         "main"
       ],
-      "sourcePath": "src\\nodes\\collections\\collectionDeleteNode.types.ts"
+      "sourcePath": "src/nodes/collections/collectionDeleteNode.types.ts"
     },
     {
       "name": "Collection: Find One",
@@ -27,7 +27,7 @@
       "outputPorts": [
         "main"
       ],
-      "sourcePath": "src\\nodes\\collections\\collectionFindOneNode.types.ts"
+      "sourcePath": "src/nodes/collections/collectionFindOneNode.types.ts"
     },
     {
       "name": "Collection: Get",
@@ -39,7 +39,7 @@
       "outputPorts": [
         "main"
       ],
-      "sourcePath": "src\\nodes\\collections\\collectionGetNode.types.ts"
+      "sourcePath": "src/nodes/collections/collectionGetNode.types.ts"
     },
     {
       "name": "Collection: Insert",
@@ -51,7 +51,7 @@
       "outputPorts": [
         "main"
       ],
-      "sourcePath": "src\\nodes\\collections\\collectionInsertNode.types.ts"
+      "sourcePath": "src/nodes/collections/collectionInsertNode.types.ts"
     },
     {
       "name": "Collection: List",
@@ -63,7 +63,7 @@
       "outputPorts": [
         "main"
       ],
-      "sourcePath": "src\\nodes\\collections\\collectionListNode.types.ts"
+      "sourcePath": "src/nodes/collections/collectionListNode.types.ts"
     },
     {
       "name": "Collection: Update",
@@ -75,7 +75,7 @@
       "outputPorts": [
         "main"
       ],
-      "sourcePath": "src\\nodes\\collections\\collectionUpdateNode.types.ts"
+      "sourcePath": "src/nodes/collections/collectionUpdateNode.types.ts"
     }
   ],
   "credentials": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,11 @@
     "@ai-sdk/provider": "^3.0.8",
     "ai": "^6.0.168",
     "croner": "^10.0.1",
-    "lucide-react": "^0.577.0",
-    "@codemation/core": "0.11.0"
+    "@codemation/core": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",
+    "lucide-react": "^0.577.0",
     "eslint": "^10.0.3",
     "reflect-metadata": "^0.2.2",
     "tsdown": "^0.15.5",

package/src/chatModels/CodemationChatModelConfig.ts

@@ -43,5 +43,5 @@ export class CodemationChatModelConfig implements ChatModelConfig {
     this.presentation = presentationIn ?? { icon: "lucide:bot", label: name };
   }
 
-  // No getCredentialRequirements() — authentication is implicit via workspace pairing secret (D2).
+  // No getCredentialRequirements() — authentication is implicit via workspace pairing secret.
 }

package/src/index.ts

@@ -43,3 +43,4 @@ export * from "./nodes/ConnectionCredentialNodeConfig";
 export * from "./nodes/ConnectionCredentialNodeConfigFactory";
 export * from "./nodes/ConnectionCredentialExecutionContextFactory";
 export * from "./nodes/collections";
+export * from "./nodes/InboxApprovalNode.types";

package/src/nodes/AIAgentNode.ts

@@ -46,7 +46,7 @@ import { Output, generateText, jsonSchema } from "ai";
 type AnyGenerateTextResult = GenerateTextResult<ToolSet, any>;
 import { z } from "zod";
 
-import type { AgentMcpIntegration, AgentMcpToolMap } from "@codemation/core";
+import type { AgentMcpIntegration, AgentMcpToolMap, ResumeContext } from "@codemation/core";
 import type { AIAgent } from "./AIAgentConfig";
 import { AIAgentExecutionHelpersFactory } from "./AIAgentExecutionHelpersFactory";
 import { AgentToolExecutionCoordinator } from "./AgentToolExecutionCoordinator";
@@ -65,6 +65,10 @@ import {
   type PlannedToolCall,
   type ResolvedTool,
 } from "./aiAgentSupport.types";
+import type { AgentLoopCheckpoint } from "./AgentLoopCheckpoint.types";
+
+const HITL_SOLO_CONSTRAINT_SENTENCE =
+  "This tool requires human approval and may take time. Call it alone — do not invoke other tools in the same turn. Your turn will be paused until a decision is made.";
 
 type ResolvedGuardrails = Required<Pick<AgentGuardrailConfig, "maxTurns" | "onTurnLimitReached">> &
   Pick<AgentGuardrailConfig, "modelInvocationOptions">;
@@ -130,12 +134,120 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   }
 
   async execute(args: RunnableNodeExecuteArgs<AIAgent<any, any>>): Promise<unknown> {
-    const prepared = await this.getOrPrepareExecution(args.ctx);
+    const { ctx } = args;
+
+    // HITL resume branch (story 10): the engine re-activates us after a human decision.
+    if (ctx.resumeContext) {
+      return this.executeResumed(args, ctx.resumeContext);
+    }
+
+    const prepared = await this.getOrPrepareExecution(ctx);
     const itemWithMappedJson = { ...args.item, json: args.input };
     const resultItem = await this.runAgentForItem(prepared, itemWithMappedJson, args.itemIndex, args.items);
     return resultItem.json;
   }
 
+  /**
+   * Resume path: re-enters the agent loop after a HITL suspension.
+   * Reconstructs the conversation from the checkpoint, injects the human decision
+   * as a tool_result, and continues the loop from where it suspended.
+   */
+  private async executeResumed(
+    args: RunnableNodeExecuteArgs<AIAgent<any, any>>,
+    resumeContext: ResumeContext,
+  ): Promise<unknown> {
+    const { ctx } = args;
+    const taskMetadata = resumeContext.task.metadata ?? {};
+    const checkpoint = taskMetadata["agentCheckpoint"] as AgentLoopCheckpoint | undefined;
+    const onRejected = (taskMetadata["onRejected"] as "halt" | "return" | undefined) ?? "return";
+
+    if (!checkpoint) {
+      // Not an agent-HITL resume (e.g., a direct HITL node, not wrapped in agent). Fall through.
+      const prepared = await this.getOrPrepareExecution(ctx);
+      const itemWithMappedJson = { ...args.item, json: args.input };
+      const resultItem = await this.runAgentForItem(prepared, itemWithMappedJson, args.itemIndex, args.items);
+      return resultItem.json;
+    }
+
+    // If rejected with halt policy, the engine has already halted; return gracefully.
+    if (resumeContext.decision.kind === "decided" && resumeContext.decision.value === null && onRejected === "halt") {
+      return undefined;
+    }
+
+    const decision = this.normalizeDecision(resumeContext);
+
+    if (decision.status === "rejected" && onRejected === "halt") {
+      // Engine halts the run. Return nothing — the run is dead.
+      return undefined;
+    }
+
+    const prepared = await this.getOrPrepareExecution(ctx);
+    const item = args.item;
+    const itemInputsByPort = AgentItemPortMap.fromItem(item);
+    const itemScopedTools = this.createItemScopedTools(prepared.resolvedTools, ctx, item, args.itemIndex, args.items);
+
+    // Reconstruct conversation: checkpoint.conversation already includes the assistant message
+    // with the pending tool_use. Append the tool_result for the decision.
+    const toolResultEntry: ExecutedToolCall = {
+      toolName: checkpoint.pendingToolCallId,
+      toolCallId: checkpoint.pendingToolCallId,
+      result: decision,
+      serialized: JSON.stringify(decision),
+    };
+    const conversation: ModelMessage[] = [
+      ...checkpoint.conversation,
+      AgentMessageFactory.createToolResultsMessage([toolResultEntry]),
+    ];
+
+    const loopResult = await this.runTurnLoopUntilFinalAnswer({
+      prepared,
+      itemInputsByPort,
+      itemScopedTools,
+      conversation,
+      resumedTurnCount: checkpoint.turnCount,
+      resumedToolCallCount: checkpoint.toolCallCount,
+    });
+    await ctx.telemetry.recordMetric({ name: CodemationTelemetryMetricNames.agentTurns, value: loopResult.turnCount });
+    await ctx.telemetry.recordMetric({
+      name: CodemationTelemetryMetricNames.agentToolCalls,
+      value: loopResult.toolCallCount,
+    });
+    const outputJson = await this.resolveFinalOutputJson(
+      prepared,
+      itemInputsByPort,
+      conversation,
+      loopResult.finalText,
+      itemScopedTools.length > 0,
+    );
+    return this.buildOutputItem(item, outputJson).json;
+  }
+
+  /**
+   * Normalizes a {@link ResumeContext} decision into a flat JSON-serializable shape
+   * suitable for injection as a tool_result content.
+   */
+  private normalizeDecision(resumeContext: ResumeContext): Record<string, unknown> {
+    const { decision } = resumeContext;
+    if (decision.kind === "decided") {
+      const value = decision.value as Record<string, unknown> | null | undefined;
+      // Convention: the decision schema for an approval tool has { approved: boolean, note?: string }.
+      // The status is "approved" when approved === true, otherwise "rejected".
+      const isApproved =
+        typeof value === "object" && value !== null && "approved" in value ? Boolean(value["approved"]) : true;
+      return {
+        status: isApproved ? "approved" : "rejected",
+        value: decision.value,
+        actor: decision.actor,
+        decidedAt: decision.decidedAt.toISOString(),
+      };
+    }
+    if (decision.kind === "timed_out") {
+      return { status: "timed_out", at: decision.at.toISOString() };
+    }
+    // auto_accepted
+    return { status: "auto_accepted", at: decision.at.toISOString() };
+  }
+
   private async getOrPrepareExecution(ctx: NodeExecutionContext<AIAgent<any, any>>): Promise<PreparedAgentExecution> {
     let pending = this.preparedByExecutionContext.get(ctx);
     if (!pending) {
@@ -272,12 +384,16 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     itemInputsByPort: NodeInputsByPort;
     itemScopedTools: ReadonlyArray<ItemScopedToolBinding>;
     conversation: ModelMessage[];
+    /** When resuming from HITL suspension, the turn count at the point of suspension. */
+    resumedTurnCount?: number;
+    /** When resuming from HITL suspension, the tool-call count at the point of suspension. */
+    resumedToolCallCount?: number;
   }): Promise<Readonly<{ finalText: string; turnCount: number; toolCallCount: number }>> {
     const { prepared, itemInputsByPort, itemScopedTools, conversation } = args;
     const { ctx, guardrails, toolLoadingStrategy } = prepared;
 
     let finalText = "";
-    let toolCallCount = 0;
+    let toolCallCount = args.resumedToolCallCount ?? 0;
     let turnCount = 0;
     const repairAttemptsByToolName = new Map<string, number>();
     /** Tool IDs surfaced by find_tools across all prior turns in this item run. */
@@ -335,11 +451,20 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         const plannedToolCalls = this.planToolCalls(itemScopedTools, coordinatorCalls, ctx.nodeId);
         toolCallCount += plannedToolCalls.length;
         await this.markQueuedTools(plannedToolCalls, ctx);
+        // Snapshot conversation with the assistant message appended — this is the checkpoint
+        // conversation the agent coordinator stores if a HITL tool suspends the run.
+        const assistantMsg =
+          result.assistantMessage ?? AgentMessageFactory.createAssistantWithToolCalls(result.text, result.toolCalls);
+        const conversationWithAssistant: ModelMessage[] = [...conversation, assistantMsg];
         const executed = await this.toolExecutionCoordinator.execute({
           plannedToolCalls,
           ctx,
           agentName: this.getAgentDisplayName(ctx),
           repairAttemptsByToolName,
+          conversationSnapshot: conversationWithAssistant,
+          turnCount,
+          toolCallCount,
+          modelId: this.resolveChatModelName(ctx.config.chatModel),
         });
         coordinatorExecutedCalls.push(...executed);
       }
@@ -448,7 +573,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         connectionNodeId: ConnectionNodeIdFactory.toolConnectionNodeId(ctx.nodeId, entry.config.name),
         getCredentialRequirements: () => entry.config.getCredentialRequirements?.() ?? [],
       });
-      return {
+      const hitlBehavior = this.resolveHumanApprovalBehavior(entry.config);
+      const binding: ItemScopedToolBinding = {
         config: entry.config,
         inputSchema: entry.runtime.inputSchema,
         execute: async (input, hooks): Promise<unknown> => {
@@ -463,10 +589,24 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
             hooks,
           });
         },
-      } satisfies ItemScopedToolBinding;
+        ...(hitlBehavior !== undefined ? { humanApproval: hitlBehavior } : {}),
+      };
+      return binding;
     });
   }
 
+  /**
+   * Detects whether a tool config is backed by a `defineHumanApprovalNode` marker
+   * and returns the HITL behavior config, or `undefined` when not a HITL tool.
+   */
+  private resolveHumanApprovalBehavior(config: ToolConfig): Readonly<{ onRejected: "halt" | "return" }> | undefined {
+    if (!this.isNodeBackedToolConfig(config)) return undefined;
+    const nodeConfig = config.node as unknown as { humanApprovalToolBehavior?: { onRejected?: "halt" | "return" } };
+    const marker = nodeConfig.humanApprovalToolBehavior;
+    if (marker === undefined) return undefined;
+    return { onRejected: marker.onRejected ?? "return" };
+  }
+
   /**
    * Invoke a text turn using the merged tool set from item-scoped tools (coordinator-managed)
    * and strategy tools (find_tools + discovered MCP tools).
@@ -505,6 +645,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   /**
    * Builds a ToolSet from resolved tools for strategy initialization.
    * The strategy uses this for its "always-included" node-backed tool descriptions.
+   * HITL tools (detected via the `humanApprovalToolBehavior` field set by `defineHumanApprovalNode`) get the solo-constraint sentence
+   * appended to their description.
    */
   private buildToolSetFromResolved(resolvedTools: ReadonlyArray<ResolvedTool>): ToolSet {
     if (resolvedTools.length === 0) return {};
@@ -514,8 +656,11 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         schemaName: entry.config.name,
         requireObjectRoot: true,
       });
+      const baseDescription = entry.config.description ?? entry.runtime.defaultDescription;
+      const isHitl = this.resolveHumanApprovalBehavior(entry.config) !== undefined;
+      const description = isHitl ? `${baseDescription} ${HITL_SOLO_CONSTRAINT_SENTENCE}` : baseDescription;
       toolSet[entry.config.name] = {
-        description: entry.config.description ?? entry.runtime.defaultDescription,
+        description,
         inputSchema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]),
       };
     }
@@ -544,8 +689,15 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         schemaName: entry.config.name,
         requireObjectRoot: true,
       });
+      const baseDescription = entry.config.description;
+      const description =
+        entry.humanApproval !== undefined && baseDescription !== undefined
+          ? `${baseDescription} ${HITL_SOLO_CONSTRAINT_SENTENCE}`
+          : entry.humanApproval !== undefined
+            ? HITL_SOLO_CONSTRAINT_SENTENCE
+            : baseDescription;
       toolSet[entry.config.name] = {
-        description: entry.config.description,
+        description,
         inputSchema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]),
       };
     }

package/src/nodes/AgentLoopCheckpoint.types.ts

@@ -0,0 +1,23 @@
+import type { ModelMessage } from "ai";
+
+/**
+ * Snapshot of the agent loop state at the moment of HITL suspension.
+ * Serialized as JSON and stored on `SuspensionRequest.request.metadata.agentCheckpoint`
+ * so the resumed node can reconstruct and continue the conversation.
+ *
+ * Defined here (story 10) and consumed in `AIAgentNode` resume branch.
+ */
+export type AgentLoopCheckpoint = Readonly<{
+  /** Full conversation history up to and including the assistant message that emitted tool_use. */
+  conversation: ModelMessage[];
+  /** Turn count at the point of suspension (1-based, matches loop counter in runTurnLoopUntilFinalAnswer). */
+  turnCount: number;
+  /** Total tool-call count accumulated before suspension. */
+  toolCallCount: number;
+  /** The tool_use id that triggered suspension; matched against the tool_result on resume. */
+  pendingToolCallId: string;
+  /** Display name of the agent (for logging / telemetry continuity). */
+  agentName: string;
+  /** Model identifier carried for migration-safety redundancy. */
+  modelId: string;
+}>;

package/src/nodes/AgentToolExecutionCoordinator.ts

@@ -1,5 +1,6 @@
 import type { JsonValue, NodeExecutionContext } from "@codemation/core";
-import { CodemationTelemetryAttributeNames, inject, injectable } from "@codemation/core";
+import { CodemationTelemetryAttributeNames, SuspensionRequest, inject, injectable } from "@codemation/core";
+import type { ModelMessage } from "ai";
 
 import type { AIAgent } from "./AIAgentConfig";
 import { AgentOutputFactory } from "./AgentOutputFactory";
@@ -9,6 +10,7 @@ import { AgentToolRepairExhaustedError } from "./AgentToolRepairExhaustedError";
 import { AgentToolRepairPolicy } from "./AgentToolRepairPolicy";
 import type { AgentToolRepairDecision, AgentToolValidationIssue } from "./AgentToolRepair.types";
 import type { ExecutedToolCall, PlannedToolCall } from "./aiAgentSupport.types";
+import type { AgentLoopCheckpoint } from "./AgentLoopCheckpoint.types";
 
 @injectable()
 export class AgentToolExecutionCoordinator {
@@ -25,8 +27,38 @@ export class AgentToolExecutionCoordinator {
       ctx: NodeExecutionContext<AIAgent<any, any>>;
       agentName: string;
       repairAttemptsByToolName: Map<string, number>;
+      /** Conversation including the assistant message that emitted these tool_use blocks. Stored in checkpoint on HITL suspension. */
+      conversationSnapshot?: ReadonlyArray<ModelMessage>;
+      /** Turn count at the moment of this coordinator invocation. */
+      turnCount?: number;
+      /** Cumulative tool-call count up to and including this batch. */
+      toolCallCount?: number;
+      /** Model id for checkpoint migration safety. */
+      modelId?: string;
     }>,
   ): Promise<ReadonlyArray<ExecutedToolCall>> {
+    // Solo enforcement: if any HITL tool appears alongside other tools, return error results
+    // for all calls so the model self-corrects on the next turn.
+    const hitlCalls = args.plannedToolCalls.filter((c) => c.binding.humanApproval !== undefined);
+    if (hitlCalls.length > 0 && args.plannedToolCalls.length > 1) {
+      return args.plannedToolCalls.map((c) => ({
+        toolName: c.binding.config.name,
+        toolCallId: c.toolCall.id ?? c.binding.config.name,
+        result: {
+          error:
+            c.binding.humanApproval !== undefined
+              ? `HITL tool '${c.binding.config.name}' cannot be called alongside other tools in the same turn; call it alone.`
+              : `deferred: a HITL tool in the same turn blocked execution. Retry this tool alone in the next turn.`,
+        },
+        serialized: JSON.stringify({
+          error:
+            c.binding.humanApproval !== undefined
+              ? `HITL tool '${c.binding.config.name}' cannot be called alongside other tools in the same turn; call it alone.`
+              : `deferred: a HITL tool in the same turn blocked execution. Retry this tool alone in the next turn.`,
+        }),
+      }));
+    }
+
     const results = await Promise.allSettled(
       args.plannedToolCalls.map(
         async (plannedToolCall) => await this.executePlannedToolCall({ ...args, plannedToolCall }),
@@ -35,7 +67,10 @@ export class AgentToolExecutionCoordinator {
 
     const rejected = results.find((result) => result.status === "rejected");
     if (rejected?.status === "rejected") {
-      throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
+      const reason = rejected.reason;
+      // Preserve SuspensionRequest (not an Error subclass) before falling back to Error wrapping.
+      if (reason instanceof SuspensionRequest) throw reason;
+      throw reason instanceof Error ? reason : new Error(String(reason));
     }
 
     return results
@@ -49,6 +84,10 @@ export class AgentToolExecutionCoordinator {
       ctx: NodeExecutionContext<AIAgent<any, any>>;
       agentName: string;
       repairAttemptsByToolName: Map<string, number>;
+      conversationSnapshot?: ReadonlyArray<ModelMessage>;
+      turnCount?: number;
+      toolCallCount?: number;
+      modelId?: string;
     }>,
   ): Promise<ExecutedToolCall> {
     const { plannedToolCall, ctx } = args;
@@ -134,6 +173,32 @@ export class AgentToolExecutionCoordinator {
         result,
       } satisfies ExecutedToolCall;
     } catch (error) {
+      // D1: Suspension catch — intercept before error classifier, augment with agent checkpoint.
+      if (error instanceof SuspensionRequest) {
+        const pendingToolCallId = plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name;
+        const checkpoint: AgentLoopCheckpoint = {
+          conversation: args.conversationSnapshot ? [...args.conversationSnapshot] : [],
+          turnCount: args.turnCount ?? 0,
+          toolCallCount: args.toolCallCount ?? 0,
+          pendingToolCallId,
+          agentName: args.agentName,
+          modelId: args.modelId ?? "",
+        };
+        const agentReasoning = this.extractLastAssistantText(args.conversationSnapshot ?? []);
+        const augmented = new SuspensionRequest({
+          ...error.request,
+          metadata: {
+            ...error.request.metadata,
+            agentCheckpoint: checkpoint as unknown as JsonValue,
+            pendingToolCallId: pendingToolCallId as JsonValue,
+            agentReasoning: agentReasoning as JsonValue,
+            onRejected: (plannedToolCall.binding.humanApproval?.onRejected ?? "return") as JsonValue,
+          },
+        });
+        await span.end({ status: "error", statusMessage: "suspended", endedAt: new Date() });
+        throw augmented;
+      }
+
       const classification = this.errorClassifier.classify({
         error,
         toolName: plannedToolCall.binding.config.name,
@@ -362,6 +427,30 @@ export class AgentToolExecutionCoordinator {
     return candidate.details;
   }
 
+  /**
+   * Extracts the text content from the last assistant message in the conversation snapshot.
+   * Used to populate `agentReasoning` in the HITL suspension metadata.
+   */
+  private extractLastAssistantText(conversation: ReadonlyArray<ModelMessage>): string {
+    for (let i = conversation.length - 1; i >= 0; i--) {
+      const msg = conversation[i];
+      if (msg?.role !== "assistant") continue;
+      const content = msg.content;
+      if (typeof content === "string") return content;
+      if (Array.isArray(content)) {
+        const textParts = content
+          .filter(
+            (part): part is { type: "text"; text: string } =>
+              typeof part === "object" && (part as { type?: unknown }).type === "text",
+          )
+          .map((part) => part.text);
+        if (textParts.length > 0) return textParts.join("");
+      }
+      break;
+    }
+    return "";
+  }
+
   private serializeIssue(issue: AgentToolValidationIssue): JsonValue {
     const result: Record<string, JsonValue> = {
       path: [...issue.path],

package/src/nodes/InboxApprovalNode.types.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { defineHumanApprovalNode } from "@codemation/core";
+import type { Item, JsonValue } from "@codemation/core";
+import { InboxChannelResolverToken } from "@codemation/core";
+
+/**
+ * A subject field (title / body) for an inbox approval. Either a static string
+ * or a contextual callback that builds the string from the item using ordinary
+ * JavaScript template literals — e.g. `({ item }) => `Approve ${item.json.vendor}``.
+ * Code-first: no template DSL, just functions.
+ */
+type InboxSubjectField = string | ((args: { item: Item }) => string);
+
+function resolveSubjectField(field: InboxSubjectField, item: Item): string {
+  return typeof field === "function" ? field({ item }) : field;
+}
+
+/**
+ * Auto-detecting inbox approval node.
+ *
+ * Uses `ctx.resolve(InboxChannelResolverToken)` to pick the right inbox channel
+ * at runtime:
+ * - In managed mode (PairingConfig present): routes to the control-plane inbox.
+ * - Otherwise: routes to the local inbox.
+ *
+ * Authors use this node directly; no extra wiring needed per deployment mode.
+ */
+export const inboxApproval = defineHumanApprovalNode({
+  key: "inbox.approval",
+  title: "Inbox Approval",
+  description: "Suspend and wait for a human reviewer to approve or reject.",
+  icon: "lucide:inbox",
+  channel: "inbox",
+
+  configSchema: z.object({
+    title: z.custom<InboxSubjectField>((v) => typeof v === "string" || typeof v === "function"),
+    body: z.custom<InboxSubjectField>((v) => typeof v === "string" || typeof v === "function"),
+    priority: z.enum(["low", "normal", "high"]).default("normal"),
+    timeout: z.string().default("24h"),
+    onTimeout: z.enum(["halt", "auto-accept"]).default("halt"),
+  }),
+  decisionSchema: z.object({
+    approved: z.boolean(),
+    note: z.string().optional(),
+  }),
+  defaultTimeout: "24h",
+  defaultOnTimeout: "halt",
+
+  async deliver({ task, config, item }, ctx) {
+    const resolver = ctx.resolve(InboxChannelResolverToken);
+    if (!resolver) {
+      throw new Error("inboxApproval: no InboxChannelResolver registered. Ensure the host DI container is wired.");
+    }
+    const { channel, workspaceId } = resolver.resolve();
+    const subject = {
+      title: resolveSubjectField(config.title, item),
+      summary: resolveSubjectField(config.body, item),
+      attributes: { workflowId: ctx.workflowId, item: item.json as JsonValue },
+    };
+    const delivery = await channel.deliver({
+      task,
+      subject,
+      priority: config.priority,
+      item,
+      workspaceId,
+    });
+    ctx.telemetry.addSpanEvent({
+      name: "hitl.task.delivered",
+      attributes: { taskId: task.taskId, channel: channel.kind },
+    });
+    return delivery;
+  },
+
+  async onDecision({ decision, actor, delivery }, ctx) {
+    const resolver = ctx.resolve(InboxChannelResolverToken);
+    if (!resolver) return;
+    const { channel } = resolver.resolve();
+    await channel.updateOnDecision?.({ delivery, decision, actor });
+  },
+
+  async onTimeout({ delivery, policy }, ctx) {
+    const resolver = ctx.resolve(InboxChannelResolverToken);
+    if (!resolver) return;
+    const { channel } = resolver.resolve();
+    await channel.updateOnTimeout?.({ delivery, policy });
+  },
+});

package/src/nodes/aiAgentSupport.types.ts

@@ -32,11 +32,16 @@ export type ResolvedTool = Readonly<{
  * span and the planned tool-call's `invocationId`. Node-backed sub-agent tools use these hooks
  * via {@link ChildExecutionScopeFactory} to re-root their runtime ctx under the tool-call boundary
  * (fresh activationId, telemetry parented at the tool-call span, `parentInvocationId` set).
+ *
+ * `humanApproval` is present only when the tool was created via `defineHumanApprovalNode`
+ * (via its marker) — detected during `resolveTools` in `AIAgentNode`.
  */
 export type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
   inputSchema: ZodSchemaAny;
   execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
+  /** Present when this binding is backed by a HITL-approval node (story 10). */
+  humanApproval?: Readonly<{ onRejected: "halt" | "return" }>;
 }>;
 
 export type ItemScopedToolCallHooks = Readonly<{