@codemation/core-nodes 0.8.1 → 0.10.0

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<{

package/src/nodes/codemationDocumentScannerNode.ts

@@ -0,0 +1,131 @@
+import { defineNode } from "@codemation/core";
+import { z } from "zod";
+import { managedHmacFetchFactory } from "../chatModels/ManagedHmacSignerFactory.types";
+
+const ANALYZER_TYPES = ["document", "invoice", "image", "auto"] as const;
+export type DocScannerAnalyzerType = (typeof ANALYZER_TYPES)[number];
+
+/** Per-field value/confidence shape as returned by apps/doc-scanner. */
+export type DocScannerField = Readonly<{
+  value: unknown;
+  confidence: number | null;
+}>;
+
+/** Output shape of CodemationDocumentScanner — identical to the service wire response. */
+export type DocScannerOutput = Readonly<{
+  markdown: string;
+  fields: Readonly<Record<string, DocScannerField>>;
+}>;
+
+export type CodemationDocumentScannerConfig = Readonly<{
+  /** Key on `item.binary` that holds the document. Default: "data". */
+  binaryField?: string;
+  /** Analyzer type. Default: "auto" (routes on mime type on the service side). */
+  analyzerType?: DocScannerAnalyzerType;
+  /** MIME type override. Falls back to attachment.mimeType. */
+  contentType?: string;
+  /** Include per-field confidence scores (0–1). Default: false.
+   *  Enabling this roughly doubles contextualization tokens for document analyzers.
+   *  Image and auto-to-image requests silently ignore this flag (confidence stays null). */
+  includeConfidence?: boolean;
+  /** Max bytes checked before any read. Default: 50 MiB (same cap as OCR nodes, LD10). */
+  maxBytes?: number;
+}>;
+
+export const codemationDocumentScannerNode = defineNode({
+  key: "codemation.document-scanner",
+  title: "Codemation Document Scanner",
+  description:
+    "Analyzes a binary attachment (document or image) via the managed Codemation document-scanning service " +
+    "and returns markdown text plus structured fields. No Azure credential required — auth uses the workspace " +
+    "pairing secret. Enable includeConfidence to get per-field confidence scores (0–1).",
+  icon: "lucide:scan-text",
+  input: {
+    binaryField: "data",
+    analyzerType: "auto" as DocScannerAnalyzerType,
+    contentType: undefined as string | undefined,
+    includeConfidence: false,
+    maxBytes: undefined as number | undefined,
+  },
+  configSchema: z.object({
+    binaryField: z.string().optional(),
+    analyzerType: z.enum(ANALYZER_TYPES).optional(),
+    contentType: z.string().optional(),
+    includeConfidence: z.boolean().optional(),
+    maxBytes: z.number().int().positive().optional(),
+  }),
+  // keepBinaries is omitted (false) — the output replaces the item payload.
+  // To carry the source binary forward, set keepBinaries: true at the call site
+  // or use a downstream step that reads item.binary.
+  inspectorSummary({ config }) {
+    const cfg = config as unknown as CodemationDocumentScannerConfig;
+    const rows: Array<{ label: string; value: string }> = [
+      { label: "Analyzer type", value: cfg.analyzerType ?? "auto" },
+    ];
+    const binaryField = cfg.binaryField ?? "data";
+    if (binaryField !== "data") rows.push({ label: "Binary field", value: binaryField });
+    if (cfg.includeConfidence) rows.push({ label: "Confidence", value: "enabled" });
+    if (cfg.contentType) rows.push({ label: "Content type", value: cfg.contentType });
+    return rows;
+  },
+  async execute({ item, ctx }, { config: rawConfig }) {
+    const config = rawConfig as unknown as CodemationDocumentScannerConfig;
+
+    // eslint-disable-next-line no-restricted-properties -- DOC_SCANNER_GATEWAY_URL is injected by the control-plane provisioner into the workspace process env; reading it at execute time is the justified boundary.
+    const gatewayUrl = process.env["DOC_SCANNER_GATEWAY_URL"];
+    if (!gatewayUrl) {
+      throw new Error(
+        "Codemation Document Scanner not available in this environment (DOC_SCANNER_GATEWAY_URL is not set).",
+      );
+    }
+
+    // Workspace pairing identity — injected by the CP provisioner (mirrors
+    // CodemationChatModelFactory). Passed to the signer; the HMAC binds THIS
+    // workspace (LD4) and does not sign the file body (LD11).
+    // eslint-disable-next-line no-restricted-properties -- WORKSPACE_ID is injected by the provisioner; read at execute time.
+    const workspaceId = process.env["WORKSPACE_ID"];
+    // eslint-disable-next-line no-restricted-properties -- WORKSPACE_PAIRING_SECRET is injected by the provisioner; read at execute time.
+    const pairingSecret = process.env["WORKSPACE_PAIRING_SECRET"];
+    if (!workspaceId || !pairingSecret) {
+      throw new Error("Codemation Document Scanner not available (workspace pairing is not configured).");
+    }
+
+    const binaryField = config.binaryField ?? "data";
+    const attachment = item.binary?.[binaryField];
+    if (!attachment) {
+      throw new Error(`Codemation Document Scanner: no binary attachment at key "${binaryField}".`);
+    }
+
+    const body = await ctx.binary.getBytes(attachment, config.maxBytes);
+    const contentType = config.contentType ?? attachment.mimeType ?? "application/octet-stream";
+    const analyzerType = config.analyzerType ?? "auto";
+    const includeConfidence = config.includeConfidence ?? false;
+
+    const confidenceSuffix = includeConfidence ? "&confidence=true" : "";
+    const url = `${gatewayUrl}/analyze?type=${encodeURIComponent(analyzerType)}${confidenceSuffix}`;
+
+    // signBody: false (LD11): the HMAC binds the workspace, not the file body.
+    // The signer forwards the bytes untouched and signs an empty-body hash, so
+    // we never re-read or normalise the binary payload.
+    const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret, { signBody: false });
+
+    const response = await hmacFetch(url, {
+      method: "POST",
+      body: body.buffer as ArrayBuffer,
+      headers: {
+        "Content-Type": contentType,
+        "Content-Length": String(body.byteLength),
+        "X-Codemation-Caller": "workflow-node",
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "(unreadable)");
+      throw new Error(
+        `Codemation Document Scanner: service responded ${response.status} ${response.statusText} — ${text}`,
+      );
+    }
+
+    return (await response.json()) as DocScannerOutput;
+  },
+});