@codemation/core-nodes 0.8.1 → 0.10.0

package/dist/metadata.json

@@ -1,10 +1,22 @@
 {
   "schemaVersion": 1,
   "packageName": "@codemation/core-nodes",
-  "packageVersion": "0.8.1",
+  "packageVersion": "0.10.0",
   "description": "",
   "kind": "nodes",
   "nodes": [
+    {
+      "name": "Codemation Document Scanner",
+      "kind": "node",
+      "description": "",
+      "inputPorts": [
+        "main"
+      ],
+      "outputPorts": [
+        "main"
+      ],
+      "sourcePath": "src/nodes/codemationDocumentScannerNode.ts"
+    },
     {
       "name": "Collection: Delete",
       "kind": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
     "@ai-sdk/provider": "^3.0.8",
     "ai": "^6.0.168",
     "croner": "^10.0.1",
-    "@codemation/core": "0.11.1"
+    "@codemation/core": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.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/chatModels/CodemationChatModelFactory.ts

@@ -1,10 +1,10 @@
-import { createHmac, createHash, randomBytes } from "node:crypto";
 import type { ChatLanguageModel, ChatModelFactory, NodeExecutionContext } from "@codemation/core";
 import { chatModel } from "@codemation/core";
 
 import { createOpenAI } from "@ai-sdk/openai";
 
 import type { CodemationChatModelConfig } from "./CodemationChatModelConfig";
+import { managedHmacFetchFactory } from "./ManagedHmacSignerFactory.types";
 
 @chatModel({ packageName: "@codemation/core-nodes" })
 export class CodemationChatModelFactory implements ChatModelFactory<CodemationChatModelConfig> {
@@ -26,7 +26,7 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
       throw new Error("Codemation managed AI not available in this environment (workspace pairing is not configured).");
     }
 
-    const hmacFetch = this.buildHmacSignedFetch(workspaceId, pairingSecret);
+    const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret);
     // apiKey is required by the AI SDK but unused — authentication is handled by the HMAC-signed fetch wrapper.
     const provider = createOpenAI({ baseURL: `${gatewayUrl}/v1`, apiKey: "codemation-managed", fetch: hmacFetch });
     const languageModel = provider.chat(args.config.model);
@@ -41,63 +41,4 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
       },
     });
   }
-
-  /**
-   * Creates an HMAC-signed fetch wrapper for use with AI SDK's createOpenAI.
-   * Each call signs the request body with the workspace pairing secret so the
-   * LLM broker can authenticate the workspace without a user-managed API key.
-   *
-   * Mirrors HmacRequestSigner from @codemation/host/pairing without importing
-   * that package (which would create a circular dependency since @codemation/host
-   * depends on @codemation/core-nodes).
-   */
-  private buildHmacSignedFetch(workspaceId: string, pairingSecret: string): typeof fetch {
-    return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
-      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-      const method = init?.method ?? "POST";
-
-      // Normalise body to a string for signing. Chat completions are always JSON strings
-      // but the fetch spec allows other BodyInit types — handle those defensively.
-      let bodyString = "";
-      if (init?.body !== undefined && init.body !== null) {
-        if (typeof init.body === "string") {
-          bodyString = init.body;
-        } else {
-          bodyString = await new Response(init.body).text();
-        }
-      }
-
-      const authHeader = this.buildHmacAuthHeader(workspaceId, pairingSecret, method, url, bodyString);
-
-      const headers = new Headers(init?.headers as Record<string, string> | undefined);
-      headers.set("Authorization", authHeader);
-
-      // Use the same (possibly normalised) body string that was signed.
-      const effectiveBody = bodyString || init?.body;
-      return fetch(input, { ...init, body: effectiveBody, headers });
-    };
-  }
-
-  /**
-   * Produces a Codemation-Hmac v1 Authorization header value.
-   * The algorithm must match HmacVerifier.computeSignature() in the control-plane.
-   */
-  private buildHmacAuthHeader(
-    workspaceId: string,
-    pairingSecret: string,
-    method: string,
-    url: string,
-    body: string,
-  ): string {
-    const ts = Math.floor(Date.now() / 1000);
-    const nonce = randomBytes(16).toString("base64");
-    const parsed = new URL(url);
-    const path = (parsed.pathname + parsed.search).toLowerCase();
-    const bodyHash = createHash("sha256").update(body, "utf8").digest("hex");
-    const baseString = [method.toUpperCase(), path, ts, nonce, bodyHash].join("\n");
-    // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is a fixed 32-byte value, never large
-    const secretBytes = Buffer.from(pairingSecret, "base64");
-    const sig = createHmac("sha256", secretBytes).update(baseString, "utf8").digest("base64");
-    return `Codemation-Hmac v=1,workspaceId=${workspaceId},ts=${ts},nonce=${nonce},sig=${sig}`;
-  }
 }

package/src/chatModels/ManagedHmacSignerFactory.types.ts

@@ -0,0 +1,88 @@
+import { createHmac, createHash, randomBytes } from "node:crypto";
+
+export interface ManagedHmacSignerOptions {
+  /**
+   * When true (the default), the signer hashes the request body and includes
+   * the hash in the HMAC base string. Use for small JSON payloads (LLM chat).
+   *
+   * When false (doc-scanner / LD11 mode), the signer computes the signature
+   * over sha256("") regardless of the actual body bytes, and forwards those
+   * bytes to the upstream fetch untouched. The HMAC binds the workspace
+   * identity, not the file content — enabling streaming without buffering.
+   */
+  signBody?: boolean;
+  /** Override wall-clock seconds for deterministic testing. */
+  now?: () => number;
+  /** Override nonce generation for deterministic testing. */
+  nonce?: () => string;
+}
+
+/**
+ * Creates an HMAC-signing fetch wrapper that authenticates requests to
+ * Codemation managed services (LLM broker, doc-scanner) with the
+ * Codemation-Hmac v=1 scheme.
+ *
+ * Mirrors HmacRequestSigner from @codemation/host/pairing without importing
+ * that package (which would create a circular dependency since @codemation/host
+ * depends on @codemation/core-nodes).
+ *
+ * @param workspaceId   - Workspace identifier injected by the CP provisioner.
+ * @param pairingSecret - Base64-encoded 32-byte HMAC key injected by the provisioner.
+ * @param options       - Optional behaviour flags and test seams.
+ */
+export function managedHmacFetchFactory(
+  workspaceId: string,
+  pairingSecret: string,
+  options?: ManagedHmacSignerOptions,
+): typeof fetch {
+  // LLM chat (the existing caller) signs its small JSON body → signBody defaults true.
+  // The doc-scanner node passes signBody:false (LD11): the HMAC binds the WORKSPACE,
+  // not the file, so we never read/normalise the (possibly large, binary) body —
+  // it is forwarded untouched and the signature covers an empty body hash.
+  const signBody = options?.signBody ?? true;
+
+  return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const method = init?.method ?? "POST";
+
+    let bodyForSigning = "";
+    if (signBody && init?.body !== undefined && init.body !== null) {
+      bodyForSigning = typeof init.body === "string" ? init.body : await new Response(init.body).text();
+    }
+
+    const authHeader = buildHmacAuthHeader(workspaceId, pairingSecret, method, url, bodyForSigning, options);
+
+    const headers = new Headers(init?.headers as Record<string, string> | undefined);
+    headers.set("Authorization", authHeader);
+
+    // When signing the body, forward the (possibly normalised) string.
+    // When not signing (signBody:false), forward the ORIGINAL body untouched
+    // so binary/streamed payloads are never buffered or re-encoded.
+    const outgoingBody = signBody ? bodyForSigning || init?.body : init?.body;
+    return fetch(input, { ...init, body: outgoingBody, headers });
+  };
+}
+
+/**
+ * Produces a Codemation-Hmac v=1 Authorization header value.
+ * Algorithm must match HmacVerifier.computeSignature() in the control-plane.
+ */
+function buildHmacAuthHeader(
+  workspaceId: string,
+  pairingSecret: string,
+  method: string,
+  url: string,
+  body: string,
+  overrides?: Pick<ManagedHmacSignerOptions, "now" | "nonce">,
+): string {
+  const ts = overrides?.now ? overrides.now() : Math.floor(Date.now() / 1000);
+  const nonce = overrides?.nonce ? overrides.nonce() : randomBytes(16).toString("base64");
+  const parsed = new URL(url);
+  const path = (parsed.pathname + parsed.search).toLowerCase();
+  const bodyHash = createHash("sha256").update(body, "utf8").digest("hex");
+  const baseString = [method.toUpperCase(), path, ts, nonce, bodyHash].join("\n");
+  // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is a fixed 32-byte value, never large
+  const secretBytes = Buffer.from(pairingSecret, "base64");
+  const sig = createHmac("sha256", secretBytes).update(baseString, "utf8").digest("base64");
+  return `Codemation-Hmac v=1,workspaceId=${workspaceId},ts=${ts},nonce=${nonce},sig=${sig}`;
+}

package/src/index.ts

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

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]),
       };
     }
@@ -715,10 +867,20 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
     try {
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
-      const outputSchema =
-        structuredOptions?.strict && !this.isZodSchema(schema)
-          ? Output.object({ schema: jsonSchema(schema as Parameters<typeof jsonSchema>[0]) as never })
-          : Output.object({ schema: schema as ZodSchemaAny });
+      // Always feed the AI SDK a plain JSON Schema, never a raw Zod schema. A consumer
+      // workflow's outputSchema is created with the consumer's tsx-loaded Zod — a different
+      // runtime copy than the framework's Zod — so handing that object to `Output.object`
+      // throws "schema is not a function". Convert via the schema's own instance method
+      // (dual-zod safe; see AIAgentExecutionHelpersFactory) before wrapping with jsonSchema().
+      const schemaRecord = this.isZodSchema(schema)
+        ? this.executionHelpers.createJsonSchemaRecord(schema, {
+            schemaName: structuredOptions?.schemaName ?? "structured_output",
+            requireObjectRoot: true,
+          })
+        : schema;
+      const outputSchema = Output.object({
+        schema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]) as never,
+      });
       const result = await generateText({
         model: model.languageModel as LanguageModel,
         messages: [...messages],

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],