@codemation/core 0.13.2 → 0.15.0

package/src/authoring/defineHumanApprovalNode.types.ts

@@ -15,69 +15,27 @@ import { SuspensionRequest } from "../contracts/runtimeTypes";
 import { defineNode } from "./defineNode.types";
 import type { DefinedNode } from "./defineNode.types";
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-/**
- * Decision shape merged into `item.json` after a HITL approval task resolves.
- *
- * - `"approved"` / `"rejected"` — from a human decision (uses `approvedPredicate`).
- * - `"timed-out"` — timeout fired with `onTimeout: "halt"`.
- * - `"auto-accepted"` — timeout fired with `onTimeout: "auto-accept"`.
- */
 export interface HumanApprovalDecisionResult {
   readonly status: "approved" | "rejected" | "timed-out" | "auto-accepted";
-  /** Identity of the person who decided; absent for automated outcomes. */
   readonly actor?: HumanTaskActor;
-  /** ISO 8601 timestamp of the decision. */
   readonly decidedAt?: Date;
-  /** Optional free-text note from the reviewer. */
   readonly note?: string;
-  /**
-   * Full raw decision payload (only present for `"approved"` / `"rejected"`).
-   * Shape is determined by the channel's `decisionSchema`.
-   */
   readonly payload?: Record<string, unknown>;
 }
 
-/**
- * Output item shape emitted by a `defineHumanApprovalNode`-based node.
- * Original `item.json` fields are preserved and `decision` is merged in.
- * If the input `item.json` already contained a `decision` key it is **overwritten**.
- */
 export type HumanApprovalOutputJson<TInputJson extends Record<string, unknown>> = TInputJson & {
   readonly decision: HumanApprovalDecisionResult;
 };
 
-/**
- * Extends {@link DefinedNode} with the `humanApprovalToolBehavior` metadata marker.
- * Story 10 reads this field when attaching the node as an agent tool.
- */
 export interface DefinedHumanApprovalNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
   TInputJson extends Record<string, unknown>,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 > extends DefinedNode<TKey, TConfig, TInputJson, HumanApprovalOutputJson<TInputJson>, TBindings> {
-  /**
-   * Behavior hint consumed by the agent runtime (story 10) when this node is attached as a tool.
-   * `"return"` (default) — return the rejection to the agent as a tool result.
-   * `"halt"` — halt the agent run on rejection.
-   *
-   * Standalone DSL usage ignores this field.
-   */
   readonly humanApprovalToolBehavior: { onRejected: "return" | "halt" };
 }
 
-// ---------------------------------------------------------------------------
-// isHumanApprovalNode predicate
-// ---------------------------------------------------------------------------
-
-/**
- * Returns `true` when `node` was created by {@link defineHumanApprovalNode}.
- * Uses the `humanApprovalToolBehavior` typed field as the discriminant.
- */
 export function isHumanApprovalNode(
   node: unknown,
 ): node is DefinedHumanApprovalNode<string, Record<string, unknown>, Record<string, unknown>, undefined> {
@@ -89,57 +47,6 @@ export function isHumanApprovalNode(
   );
 }
 
-// ---------------------------------------------------------------------------
-// defineHumanApprovalNode
-// ---------------------------------------------------------------------------
-
-/**
- * Authoring helper that compiles a HITL approval channel down to a regular
- * {@link defineNode}-backed node with `SuspensionRequest` semantics.
- *
- * **Fast-forward decision semantics:**
- * - On the first `execute` call (no `ctx.resumeContext`): throws a `SuspensionRequest`
- *   that calls the author's `deliver`. The engine persists the suspension and continues.
- * - On resume (`ctx.resumeContext` set): calls `onDecision`/`onTimeout` as appropriate,
- *   merges a `decision` key into `item.json`, and returns an item with the original
- *   `binary` map passed by reference (no copy).
- *
- * **Output shape per item:**
- * ```ts
- * // Input:  { json: { invoiceId: 42 }, binary?: {...} }
- * // Output: { json: { invoiceId: 42, decision: { status: "approved", actor, decidedAt } }, binary: <unchanged> }
- * ```
- * If `item.json` already has a `decision` key it is **overwritten**. Namespace as
- * needed if your schema reserves that key for another purpose.
- *
- * **Predicate persistence:**
- * The `approvedPredicate` function is NOT serialized to the suspension record (except
- * as an audit-only string via `toString()`). On resume, the workflow definition is
- * reloaded from code at process start and the predicate closure is rebuilt naturally.
- * If a deploy ships a changed predicate between suspend and resume, the *new* predicate
- * runs — document this in your runbook when the predicate carries business logic that
- * may change across deploys.
- *
- * @example
- * ```ts
- * export const slackApprovalNode = defineHumanApprovalNode({
- *   key: "my-plugin.slackApproval",
- *   title: "Slack Approval",
- *   channel: "slack",
- *   configSchema: z.object({ channel: z.string(), message: z.string() }),
- *   decisionSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
- *
- *   async deliver({ task, config, item }, ctx) {
- *     const ts = await postSlackMessage(config.channel, `Approve? <${task.resumeUrl}>`);
- *     return { channel: config.channel, ts };
- *   },
- *
- *   async onDecision({ decision, actor, delivery }, ctx) {
- *     await updateSlackMessage(delivery.channel, delivery.ts, decision.approved ? "✅" : "❌");
- *   },
- * });
- * ```
- */
 export function defineHumanApprovalNode<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -159,16 +66,8 @@ export function defineHumanApprovalNode<
   decisionSchema: ZodType<TDecision>;
   credentials?: TBindings;
 
-  /**
-   * Custom predicate that decides whether a decision counts as "approved".
-   * When omitted, the helper checks if `decisionSchema` is a Zod object with an
-   * `approved: boolean` field; if so it uses `decision.approved === true`.
-   * If neither holds, `defineHumanApprovalNode` throws at **definition time** (not runtime).
-   */
   approvedPredicate?: (decision: TDecision) => boolean;
-  /** Default suspension timeout. Defaults to `"24h"`. */
   defaultTimeout?: Duration;
-  /** What to do when the task times out. Defaults to `"halt"`. */
   defaultOnTimeout?: "halt" | "auto-accept";
 
   inspectorSummary?: (config: TConfig) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
@@ -204,16 +103,11 @@ export function defineHumanApprovalNode<
     ctx: ExecutionContext,
   ) => Promise<void>;
 }): DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings> {
-  // Resolve the approved predicate at definition time so we throw early when
-  // the schema is ambiguous.
   const resolvedPredicate = resolveApprovedPredicate(opts.decisionSchema, opts.approvedPredicate);
 
   const timeout = opts.defaultTimeout ?? "24h";
   const onTimeout = opts.defaultOnTimeout ?? "halt";
 
-  // TOutputJson is `unknown` here because `execute` returns an Item-shaped object
-  // that the engine's NodeOutputNormalizer converts to the proper output. The public
-  // interface's DefinedHumanApprovalNode carries the correct output type for DSL use.
   const inner = defineNode<TKey, TConfig, TInputJson, unknown, TBindings>({
     key: opts.key,
     title: opts.title,
@@ -226,7 +120,6 @@ export function defineHumanApprovalNode<
 
     async execute(args, { config, execution: ctx }) {
       if (!ctx.resumeContext) {
-        // First pass — suspend.
         const subject = buildSubject(opts.title, args.item, ctx);
         throw new SuspensionRequest({
           decisionSchema: opts.decisionSchema,
@@ -236,7 +129,6 @@ export function defineHumanApprovalNode<
           metadata: {
             channel: opts.channel,
             nodeKey: opts.key,
-            // Stored for audit only; never re-evaluated. See JSDoc on defineHumanApprovalNode.
             approvedPredicateSource: opts.approvedPredicate?.toString() ?? null,
           },
           deliver: (handle: HumanTaskHandle) =>
@@ -252,7 +144,6 @@ export function defineHumanApprovalNode<
         });
       }
 
-      // Resume pass.
       return await handleResume(
         args.item,
         ctx.resumeContext,
@@ -270,10 +161,6 @@ export function defineHumanApprovalNode<
   }) as unknown as DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings>;
 }
 
-// ---------------------------------------------------------------------------
-// Internal helpers (module-private)
-// ---------------------------------------------------------------------------
-
 function resolveApprovedPredicate<TDecision extends Record<string, unknown>>(
   schema: ZodType<TDecision>,
   predicate: ((d: TDecision) => boolean) | undefined,
@@ -281,7 +168,6 @@ function resolveApprovedPredicate<TDecision extends Record<string, unknown>>(
   if (predicate) {
     return predicate;
   }
-  // Zod 4: ZodObject exposes `.shape` directly as an object (not a function).
   const shape = (schema as unknown as ZodObject<Record<string, ZodType>>).shape;
   if (shape && typeof shape === "object" && "approved" in shape) {
     return (d) => (d as { approved?: unknown }).approved === true;
@@ -310,7 +196,6 @@ function mergeDecision(
 ): { json: Record<string, unknown>; binary: Item["binary"]; meta: Item["meta"] } {
   return {
     json: { ...(item.json as Record<string, unknown>), decision },
-    // binary is passed by reference — no copy. See defineHumanApprovalNode JSDoc.
     binary: item.binary,
     meta: item.meta,
   };
@@ -355,7 +240,6 @@ async function handleResume<TDecision extends Record<string, unknown>, TDelivery
     return mergeDecision(item, { status, decidedAt: dec.at });
   }
 
-  // dec.kind === "decided"
   const parsed = decisionSchema.parse(dec.value);
   await onDecision?.(
     {

package/src/authoring/defineNode.types.ts

@@ -12,6 +12,7 @@ import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.ty
 import type { ZodType } from "zod";
 import { z } from "zod";
 import { DefinedNodeRegistry } from "./DefinedNodeRegistry";
+import type { NodeBaseOptions } from "./nodeBaseOptions.types";
 
 type MaybePromise<TValue> = TValue | Promise<TValue>;
 
@@ -56,10 +57,6 @@ export interface DefinedNodeRunContext<
   readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>;
 }
 
-/**
- * Arguments for {@link defineNode} `execute` (engine `ctx` matches {@link RunnableNode.execute};
- * the second callback parameter adds {@link DefinedNodeRunContext} for credential accessors).
- */
 export type DefineNodeExecuteArgs<TConfig extends CredentialJsonRecord, TInputJson> = Readonly<{
   input: TInputJson;
   item: Item;
@@ -87,14 +84,11 @@ export interface DefinedNode<
   create<TConfigItemJson = TInputJson>(
     config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
     name?: string,
-    id?: string,
+    idOrOptions?: string | NodeBaseOptions,
   ): RunnableNodeConfig<TInputJson, TOutputJson>;
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
-/**
- * Plugin / DSL-friendly node: per-item `execute` with optional {@link RunnableNodeConfig.inputSchema}.
- */
 export interface DefineNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -105,27 +99,12 @@ export interface DefineNodeOptions<
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  /**
-   * Canvas icon for this node (same contract as `NodeConfigBase.icon` on runnable configs).
-   * The Next host resolves Lucide (`lucide:…`), built-in SVGs (`builtin:…`), Simple Icons (`si:…`), and image URLs (`https:`, `data:`, `/…`).
-   */
   readonly icon?: string;
-  /** Default values / form hints for **static** node configuration (credentials, retry, IDs), not per-item payload. */
   readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
-  /**
-   * Validates **`input`** (engine also accepts `inputSchema` on the node class).
-   */
   readonly inputSchema?: ZodType<TInputJson>;
-  /** Preserve inbound `item.binary` when `execute` returns plain JSON or item-shaped results without `binary`. */
   readonly keepBinaries?: boolean;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — see
-   * {@link import("../contracts/workflowTypes").NodeConfigBase.inspectorSummary}.
-   *
-   * Receives the static config; returns 2–6 short label/value pairs (or `undefined` to skip).
-   */
   readonly inspectorSummary?: (
     args: Readonly<{ config: TConfig }>,
   ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
@@ -135,9 +114,6 @@ export interface DefineNodeOptions<
   ): MaybePromise<TOutputJson>;
 }
 
-/**
- * Batch-oriented defined node: `run` receives all item JSON once (last item in activation); emits one output per input row.
- */
 export interface DefineBatchNodeOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -271,12 +247,17 @@ export function defineNode<
     readonly icon = options.icon;
     readonly inputSchema = options.inputSchema;
     readonly keepBinaries = options.keepBinaries ?? false;
+    readonly id?: string;
+    readonly description?: string;
 
     constructor(
       public readonly name: string,
       config: DefinedNodeConfigInput<TConfig, unknown>,
-      public readonly id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
+      const resolved = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+      this.id = resolved?.id;
+      this.description = resolved?.description;
       this.config = config as unknown as TConfig;
     }
 
@@ -299,9 +280,9 @@ export function defineNode<
     create<TConfigItemJson = TInputJson>(
       config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
       name = options.title,
-      id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
-      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, id);
+      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, idOrOptions);
     },
     register(context) {
       context.registerNode(DefinedNodeRuntime);
@@ -358,12 +339,17 @@ export function defineBatchNode<
     readonly kind = "node" as const;
     readonly type: TypeToken<unknown> = DefinedNodeRuntime;
     readonly icon = options.icon;
+    readonly id?: string;
+    readonly description?: string;
 
     constructor(
       public readonly name: string,
       config: DefinedNodeConfigInput<TConfig, unknown>,
-      public readonly id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
+      const resolved = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+      this.id = resolved?.id;
+      this.description = resolved?.description;
       this.config = config as unknown as TConfig;
     }
 
@@ -386,9 +372,9 @@ export function defineBatchNode<
     create<TConfigItemJson = TInputJson>(
       config: DefinedNodeConfigInput<TConfig, TConfigItemJson>,
       name = options.title,
-      id?: string,
+      idOrOptions?: string | NodeBaseOptions,
     ) {
-      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, id);
+      return new DefinedRunnableNodeConfig(name, config as DefinedNodeConfigInput<TConfig, unknown>, idOrOptions);
     },
     register(context) {
       context.registerNode(DefinedNodeRuntime);