@codemation/node-example 0.0.38 → 0.0.40

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @codemation/node-example
 
+## 0.0.40
+
+### Patch Changes
+
+- Updated dependencies [[`3044474`](https://github.com/MadeRelevant/codemation/commit/3044474495525490735510ff74500b53761284b6)]:
+  - @codemation/core@0.12.0
+
+## 0.0.39
+
+### Patch Changes
+
+- Updated dependencies [[`e0933eb`](https://github.com/MadeRelevant/codemation/commit/e0933ebc51806a9593f94758860c591b8346a7a5)]:
+  - @codemation/core@0.11.1
+
 ## 0.0.38
 
 ### Patch Changes

package/LICENSE

@@ -1 +1,37 @@
-../../LICENSE
+Codemation Pre-Stable License
+
+Copyright (c) Made Relevant B.V. All rights reserved.
+
+1. Definitions
+
+   "Software" means the Codemation source code, documentation, and artifacts in this repository and any published npm packages in the Codemation monorepo.
+
+   "Stable Version" means the first published release of the package `@codemation/core` on the public npm registry with version 1.0.0 or higher.
+
+2. Permitted use (before Stable Version)
+
+   Until a Stable Version exists, you may use, copy, modify, and distribute the Software only for non-commercial purposes, including personal learning, research, evaluation, and internal use within your organization that does not charge third parties for access to the Software or a product or service whose primary value is the Software.
+
+3. Restrictions (before Stable Version)
+
+   Until a Stable Version exists, you must not:
+
+   a) Sell, rent, lease, or sublicense the Software or a derivative work for a fee;
+
+   b) Offer the Software or a derivative work as part of a paid product or service (including hosting, support, or consulting) where the Software is a material part of the offering;
+
+   c) Use the Software or a derivative work primarily to generate revenue or commercial advantage for you or others.
+
+   These restrictions apply to all versions published before a Stable Version, even if a later Stable Version is released under different terms.
+
+4. After Stable Version
+
+   The maintainers may publish a Stable Version under different license terms. If they do, those terms apply only to that Stable Version and subsequent releases they designate; they do not automatically apply to earlier pre-stable versions.
+
+5. No warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+6. Third-party components
+
+   The Software may include third-party components under their own licenses. Those licenses govern those components.

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { ReadableStream } from "node:stream/web";
 import { ZodType } from "zod";
 import { InjectionToken as TypeToken } from "tsyringe";
+import { ReadableStream } from "node:stream/web";
 
 //#region ../core/src/contracts/baseTypes.d.ts
 /**
@@ -13,6 +13,137 @@ type NodeId = string;
 type OutputPortKey = string;
 type InputPortKey = string;
 //#endregion
+//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
+type CostTrackingComponent = "chat" | "ocr" | "rag";
+interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/telemetryTypes.d.ts
+type TelemetryAttributePrimitive = string | number | boolean | null;
+interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+  /**
+   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
+   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
+   *
+   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
+   * span instead of the orchestrator's node-level span.
+   */
+  asNodeTelemetry(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+/**
+ * In-process retry policy for runnable nodes. Serialized configs use the same
+ * `kind` discriminator (`JSON.stringify` / persisted workflows).
+ *
+ * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ */
+type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
+interface NoneRetryPolicySpec {
+  readonly kind: "none";
+}
+interface FixedRetryPolicySpec {
+  readonly kind: "fixed";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+}
+interface ExponentialRetryPolicySpec {
+  readonly kind: "exponential";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly multiplier: number;
+  readonly maxDelayMs?: number;
+  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
+  readonly jitter?: boolean;
+}
+//#endregion
 //#region ../core/src/contracts/credentialTypes.d.ts
 type CredentialTypeId = string;
 type CredentialRequirement = Readonly<{
@@ -24,6 +155,71 @@ type CredentialRequirement = Readonly<{
   helpUrl?: string;
 }>;
 //#endregion
+//#region ../core/src/contracts/collectionTypes.d.ts
+/**
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
+ */
+interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Insert a new row. id, created_at, and updated_at are auto-populated.
+   */
+  insert(row: TRow): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Get a single row by id.
+   */
+  get(id: string): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * Find a single row matching the provided filter.
+   */
+  findOne(filter: Partial<TRow>): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * List rows with optional pagination and filtering.
+   */
+  list(opts?: {
+    limit?: number;
+    offset?: number;
+    where?: Partial<TRow>;
+  }): Promise<{
+    rows: ReadonlyArray<TRow & {
+      id: string;
+      created_at: Date;
+      updated_at: Date;
+    }>;
+    total: number;
+  }>;
+  /**
+   * Update a row by id with partial data.
+   */
+  update(id: string, patch: Partial<TRow>): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Delete a row by id. Hard delete only (no soft delete).
+   */
+  delete(id: string): Promise<{
+    deleted: boolean;
+  }>;
+}
+/**
+ * Runtime collections context: keyed by collection name.
+ */
+type CollectionsContext = Readonly<Record<string, CollectionStore>>;
+//#endregion
 //#region ../core/src/contracts/runTypes.d.ts
 /**
  * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
@@ -42,7 +238,7 @@ interface RunTestContext {
   readonly testCaseLabel?: string;
 }
 type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped" | "hitl-approved" | "hitl-rejected" | "hitl-timeout" | "hitl-auto-accepted" | "hitl-cancelled";
 interface NodeExecutionError {
   message: string;
   name?: string;
@@ -71,34 +267,6 @@ type ConnectionInvocationAppendArgs = Readonly<{
   parentInvocationId?: ConnectionInvocationId;
 }>;
 //#endregion
-//#region ../core/src/contracts/retryPolicySpec.types.d.ts
-/**
- * In-process retry policy for runnable nodes. Serialized configs use the same
- * `kind` discriminator (`JSON.stringify` / persisted workflows).
- *
- * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
- */
-type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
-interface NoneRetryPolicySpec {
-  readonly kind: "none";
-}
-interface FixedRetryPolicySpec {
-  readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly delayMs: number;
-}
-interface ExponentialRetryPolicySpec {
-  readonly kind: "exponential";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly initialDelayMs: number;
-  readonly multiplier: number;
-  readonly maxDelayMs?: number;
-  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
-  readonly jitter?: boolean;
-}
-//#endregion
 //#region ../core/src/contracts/workflowTypes.d.ts
 type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
   __codemationNodeJson?: TJson;
@@ -260,175 +428,53 @@ interface NodeErrorHandler {
 }
 type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#endregion
-//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
-type CostTrackingComponent = "chat" | "ocr" | "rag";
-interface CostTrackingUsageRecord {
-  readonly component: CostTrackingComponent;
-  readonly provider: string;
-  readonly operation: string;
-  readonly pricingKey: string;
-  readonly usageUnit: string;
-  readonly quantity: number;
-  readonly modelName?: string;
-  readonly attributes?: TelemetryAttributes;
-}
-interface CostTrackingPriceQuote {
-  readonly currency: string;
-  readonly currencyScale: number;
-  readonly estimatedAmountMinor: number;
-  readonly estimateKind: "catalog";
-}
-interface CostTrackingTelemetry {
-  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
-  forScope(scope: TelemetryScope): CostTrackingTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/telemetryTypes.d.ts
-type TelemetryAttributePrimitive = string | number | boolean | null;
-interface TelemetryAttributes {
-  readonly [key: string]: TelemetryAttributePrimitive | undefined;
-}
-interface TelemetryMetricRecord {
-  readonly name: string;
-  readonly value: number;
-  readonly unit?: string;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetrySpanEventRecord {
-  readonly name: string;
-  readonly occurredAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryArtifactAttachment {
-  readonly kind: string;
-  readonly contentType: string;
-  readonly previewText?: string;
-  readonly previewJson?: JsonValue;
-  readonly payloadText?: string;
-  readonly payloadJson?: JsonValue;
-  readonly bytes?: number;
-  readonly truncated?: boolean;
-  readonly expiresAt?: Date;
-}
-interface TelemetryArtifactReference {
-  readonly artifactId: string;
-  readonly traceId?: string;
-  readonly spanId?: string;
-}
-interface TelemetrySpanEnd {
-  readonly status?: "ok" | "error";
-  readonly statusMessage?: string;
-  readonly endedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryChildSpanStart {
-  readonly name: string;
-  readonly kind?: "internal" | "client";
-  readonly startedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryScope {
-  readonly traceId?: string;
-  readonly spanId?: string;
-  readonly costTracking?: CostTrackingTelemetry;
-  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
-  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
-  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
-}
-interface TelemetrySpanScope extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  end(args?: TelemetrySpanEnd): Promise<void> | void;
+//#region ../core/src/contracts/runtimeTypes.d.ts
+/** Opaque unique identifier for a single HumanTask instance. */
+type HumanTaskId = string;
+/**
+ * Minimal handle handed to the `deliver` callback so it can route to the correct
+ * inbox channel.
+ */
+interface HumanTaskHandle {
+  readonly taskId: HumanTaskId;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly expiresAt: Date;
+  /** TODO: real signed URL; placeholder empty string for now. */
+  readonly resumeUrl: string;
   /**
-   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
-   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
-   *
-   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
-   * span instead of the orchestrator's node-level span.
+   * Arbitrary JSON metadata copied from `SuspensionRequest.request.metadata` at suspension time.
+   * Used by the agent runtime to round-trip the `agentCheckpoint` back to the
+   * resumed node via `ctx.resumeContext.task.metadata`.
    */
-  asNodeTelemetry(args: Readonly<{
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }>): NodeExecutionTelemetry;
+  readonly metadata?: Readonly<Record<string, JsonValue>>;
 }
-interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
-  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+/** Identity of the person who made a decision on the task. */
+interface HumanTaskActor {
+  readonly actorId: string;
+  readonly displayName?: string;
 }
-interface ExecutionTelemetry extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  forNode(args: Readonly<{
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }>): NodeExecutionTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/collectionTypes.d.ts
 /**
- * Represents a typed store for a single collection.
- * All rows include auto-managed id, created_at, and updated_at fields.
+ * Resume context injected into `NodeExecutionContext` when the engine re-activates
+ * a previously suspended node. `defineHumanApprovalNode` wraps this with parsed
+ * `TDecision`; at the engine layer `decision.value` is `unknown`.
  */
-interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Insert a new row. id, created_at, and updated_at are auto-populated.
-   */
-  insert(row: TRow): Promise<TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }>;
-  /**
-   * Get a single row by id.
-   */
-  get(id: string): Promise<(TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }) | null>;
-  /**
-   * Find a single row matching the provided filter.
-   */
-  findOne(filter: Partial<TRow>): Promise<(TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }) | null>;
-  /**
-   * List rows with optional pagination and filtering.
-   */
-  list(opts?: {
-    limit?: number;
-    offset?: number;
-    where?: Partial<TRow>;
-  }): Promise<{
-    rows: ReadonlyArray<TRow & {
-      id: string;
-      created_at: Date;
-      updated_at: Date;
-    }>;
-    total: number;
-  }>;
-  /**
-   * Update a row by id with partial data.
-   */
-  update(id: string, patch: Partial<TRow>): Promise<TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }>;
-  /**
-   * Delete a row by id. Hard delete only (no soft delete).
-   */
-  delete(id: string): Promise<{
-    deleted: boolean;
+interface ResumeContext {
+  readonly decision: Readonly<{
+    kind: "decided";
+    value: unknown;
+    actor: HumanTaskActor;
+    decidedAt: Date;
+  }> | Readonly<{
+    kind: "timed_out";
+    at: Date;
+  }> | Readonly<{
+    kind: "auto_accepted";
+    at: Date;
   }>;
+  readonly delivery: JsonValue;
+  readonly task: HumanTaskHandle;
 }
-/**
- * Runtime collections context: keyed by collection name.
- */
-type CollectionsContext = Readonly<Record<string, CollectionStore>>;
-//#endregion
-//#region ../core/src/contracts/runtimeTypes.d.ts
 interface NodeExecutionStatePublisher {
   markQueued(args: {
     nodeId: NodeId;
@@ -517,6 +563,14 @@ interface ExecutionContext {
    * Collections registered in the codemation config, keyed by collection name.
    */
   readonly collections?: CollectionsContext;
+  /**
+   * Resolve a DI token from the host container.
+   * Allows nodes to reach host-side services (e.g. `InboxChannelResolverToken`)
+   * without importing host code. Wired by `DefaultExecutionContextFactory`; throws
+   * a clear error when no resolver is configured (e.g. in unit tests that don't
+   * set up the full container).
+   */
+  resolve<T>(token: TypeToken<T>): T;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
   nodeId: NodeId;
@@ -524,6 +578,11 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   config: TConfig;
   telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
+  /**
+   * Present when this node activation is a HITL resume.
+   * The node checks `ctx.resumeContext !== undefined` and takes the resume branch.
+   */
+  resumeContext?: ResumeContext;
 }
 /**
  * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { ReadableStream } from "node:stream/web";
 import { ZodType } from "zod";
 import { InjectionToken as TypeToken } from "tsyringe";
+import { ReadableStream } from "node:stream/web";
 
 //#region ../core/src/contracts/baseTypes.d.ts
 /**
@@ -13,6 +13,137 @@ type NodeId = string;
 type OutputPortKey = string;
 type InputPortKey = string;
 //#endregion
+//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
+type CostTrackingComponent = "chat" | "ocr" | "rag";
+interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/telemetryTypes.d.ts
+type TelemetryAttributePrimitive = string | number | boolean | null;
+interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+  /**
+   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
+   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
+   *
+   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
+   * span instead of the orchestrator's node-level span.
+   */
+  asNodeTelemetry(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+/**
+ * In-process retry policy for runnable nodes. Serialized configs use the same
+ * `kind` discriminator (`JSON.stringify` / persisted workflows).
+ *
+ * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ */
+type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
+interface NoneRetryPolicySpec {
+  readonly kind: "none";
+}
+interface FixedRetryPolicySpec {
+  readonly kind: "fixed";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly delayMs: number;
+}
+interface ExponentialRetryPolicySpec {
+  readonly kind: "exponential";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly multiplier: number;
+  readonly maxDelayMs?: number;
+  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
+  readonly jitter?: boolean;
+}
+//#endregion
 //#region ../core/src/contracts/credentialTypes.d.ts
 type CredentialTypeId = string;
 type CredentialRequirement = Readonly<{
@@ -24,6 +155,71 @@ type CredentialRequirement = Readonly<{
   helpUrl?: string;
 }>;
 //#endregion
+//#region ../core/src/contracts/collectionTypes.d.ts
+/**
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
+ */
+interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Insert a new row. id, created_at, and updated_at are auto-populated.
+   */
+  insert(row: TRow): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Get a single row by id.
+   */
+  get(id: string): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * Find a single row matching the provided filter.
+   */
+  findOne(filter: Partial<TRow>): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * List rows with optional pagination and filtering.
+   */
+  list(opts?: {
+    limit?: number;
+    offset?: number;
+    where?: Partial<TRow>;
+  }): Promise<{
+    rows: ReadonlyArray<TRow & {
+      id: string;
+      created_at: Date;
+      updated_at: Date;
+    }>;
+    total: number;
+  }>;
+  /**
+   * Update a row by id with partial data.
+   */
+  update(id: string, patch: Partial<TRow>): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Delete a row by id. Hard delete only (no soft delete).
+   */
+  delete(id: string): Promise<{
+    deleted: boolean;
+  }>;
+}
+/**
+ * Runtime collections context: keyed by collection name.
+ */
+type CollectionsContext = Readonly<Record<string, CollectionStore>>;
+//#endregion
 //#region ../core/src/contracts/runTypes.d.ts
 /**
  * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
@@ -42,7 +238,7 @@ interface RunTestContext {
   readonly testCaseLabel?: string;
 }
 type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped" | "hitl-approved" | "hitl-rejected" | "hitl-timeout" | "hitl-auto-accepted" | "hitl-cancelled";
 interface NodeExecutionError {
   message: string;
   name?: string;
@@ -71,34 +267,6 @@ type ConnectionInvocationAppendArgs = Readonly<{
   parentInvocationId?: ConnectionInvocationId;
 }>;
 //#endregion
-//#region ../core/src/contracts/retryPolicySpec.types.d.ts
-/**
- * In-process retry policy for runnable nodes. Serialized configs use the same
- * `kind` discriminator (`JSON.stringify` / persisted workflows).
- *
- * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
- */
-type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
-interface NoneRetryPolicySpec {
-  readonly kind: "none";
-}
-interface FixedRetryPolicySpec {
-  readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly delayMs: number;
-}
-interface ExponentialRetryPolicySpec {
-  readonly kind: "exponential";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly initialDelayMs: number;
-  readonly multiplier: number;
-  readonly maxDelayMs?: number;
-  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
-  readonly jitter?: boolean;
-}
-//#endregion
 //#region ../core/src/contracts/workflowTypes.d.ts
 type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
   __codemationNodeJson?: TJson;
@@ -260,175 +428,53 @@ interface NodeErrorHandler {
 }
 type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#endregion
-//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
-type CostTrackingComponent = "chat" | "ocr" | "rag";
-interface CostTrackingUsageRecord {
-  readonly component: CostTrackingComponent;
-  readonly provider: string;
-  readonly operation: string;
-  readonly pricingKey: string;
-  readonly usageUnit: string;
-  readonly quantity: number;
-  readonly modelName?: string;
-  readonly attributes?: TelemetryAttributes;
-}
-interface CostTrackingPriceQuote {
-  readonly currency: string;
-  readonly currencyScale: number;
-  readonly estimatedAmountMinor: number;
-  readonly estimateKind: "catalog";
-}
-interface CostTrackingTelemetry {
-  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
-  forScope(scope: TelemetryScope): CostTrackingTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/telemetryTypes.d.ts
-type TelemetryAttributePrimitive = string | number | boolean | null;
-interface TelemetryAttributes {
-  readonly [key: string]: TelemetryAttributePrimitive | undefined;
-}
-interface TelemetryMetricRecord {
-  readonly name: string;
-  readonly value: number;
-  readonly unit?: string;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetrySpanEventRecord {
-  readonly name: string;
-  readonly occurredAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryArtifactAttachment {
-  readonly kind: string;
-  readonly contentType: string;
-  readonly previewText?: string;
-  readonly previewJson?: JsonValue;
-  readonly payloadText?: string;
-  readonly payloadJson?: JsonValue;
-  readonly bytes?: number;
-  readonly truncated?: boolean;
-  readonly expiresAt?: Date;
-}
-interface TelemetryArtifactReference {
-  readonly artifactId: string;
-  readonly traceId?: string;
-  readonly spanId?: string;
-}
-interface TelemetrySpanEnd {
-  readonly status?: "ok" | "error";
-  readonly statusMessage?: string;
-  readonly endedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryChildSpanStart {
-  readonly name: string;
-  readonly kind?: "internal" | "client";
-  readonly startedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryScope {
-  readonly traceId?: string;
-  readonly spanId?: string;
-  readonly costTracking?: CostTrackingTelemetry;
-  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
-  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
-  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
-}
-interface TelemetrySpanScope extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  end(args?: TelemetrySpanEnd): Promise<void> | void;
+//#region ../core/src/contracts/runtimeTypes.d.ts
+/** Opaque unique identifier for a single HumanTask instance. */
+type HumanTaskId = string;
+/**
+ * Minimal handle handed to the `deliver` callback so it can route to the correct
+ * inbox channel.
+ */
+interface HumanTaskHandle {
+  readonly taskId: HumanTaskId;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly expiresAt: Date;
+  /** TODO: real signed URL; placeholder empty string for now. */
+  readonly resumeUrl: string;
   /**
-   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
-   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
-   *
-   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
-   * span instead of the orchestrator's node-level span.
+   * Arbitrary JSON metadata copied from `SuspensionRequest.request.metadata` at suspension time.
+   * Used by the agent runtime to round-trip the `agentCheckpoint` back to the
+   * resumed node via `ctx.resumeContext.task.metadata`.
    */
-  asNodeTelemetry(args: Readonly<{
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }>): NodeExecutionTelemetry;
+  readonly metadata?: Readonly<Record<string, JsonValue>>;
 }
-interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
-  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+/** Identity of the person who made a decision on the task. */
+interface HumanTaskActor {
+  readonly actorId: string;
+  readonly displayName?: string;
 }
-interface ExecutionTelemetry extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  forNode(args: Readonly<{
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }>): NodeExecutionTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/collectionTypes.d.ts
 /**
- * Represents a typed store for a single collection.
- * All rows include auto-managed id, created_at, and updated_at fields.
+ * Resume context injected into `NodeExecutionContext` when the engine re-activates
+ * a previously suspended node. `defineHumanApprovalNode` wraps this with parsed
+ * `TDecision`; at the engine layer `decision.value` is `unknown`.
  */
-interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Insert a new row. id, created_at, and updated_at are auto-populated.
-   */
-  insert(row: TRow): Promise<TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }>;
-  /**
-   * Get a single row by id.
-   */
-  get(id: string): Promise<(TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }) | null>;
-  /**
-   * Find a single row matching the provided filter.
-   */
-  findOne(filter: Partial<TRow>): Promise<(TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }) | null>;
-  /**
-   * List rows with optional pagination and filtering.
-   */
-  list(opts?: {
-    limit?: number;
-    offset?: number;
-    where?: Partial<TRow>;
-  }): Promise<{
-    rows: ReadonlyArray<TRow & {
-      id: string;
-      created_at: Date;
-      updated_at: Date;
-    }>;
-    total: number;
-  }>;
-  /**
-   * Update a row by id with partial data.
-   */
-  update(id: string, patch: Partial<TRow>): Promise<TRow & {
-    id: string;
-    created_at: Date;
-    updated_at: Date;
-  }>;
-  /**
-   * Delete a row by id. Hard delete only (no soft delete).
-   */
-  delete(id: string): Promise<{
-    deleted: boolean;
+interface ResumeContext {
+  readonly decision: Readonly<{
+    kind: "decided";
+    value: unknown;
+    actor: HumanTaskActor;
+    decidedAt: Date;
+  }> | Readonly<{
+    kind: "timed_out";
+    at: Date;
+  }> | Readonly<{
+    kind: "auto_accepted";
+    at: Date;
   }>;
+  readonly delivery: JsonValue;
+  readonly task: HumanTaskHandle;
 }
-/**
- * Runtime collections context: keyed by collection name.
- */
-type CollectionsContext = Readonly<Record<string, CollectionStore>>;
-//#endregion
-//#region ../core/src/contracts/runtimeTypes.d.ts
 interface NodeExecutionStatePublisher {
   markQueued(args: {
     nodeId: NodeId;
@@ -517,6 +563,14 @@ interface ExecutionContext {
    * Collections registered in the codemation config, keyed by collection name.
    */
   readonly collections?: CollectionsContext;
+  /**
+   * Resolve a DI token from the host container.
+   * Allows nodes to reach host-side services (e.g. `InboxChannelResolverToken`)
+   * without importing host code. Wired by `DefaultExecutionContextFactory`; throws
+   * a clear error when no resolver is configured (e.g. in unit tests that don't
+   * set up the full container).
+   */
+  resolve<T>(token: TypeToken<T>): T;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
   nodeId: NodeId;
@@ -524,6 +578,11 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   config: TConfig;
   telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
+  /**
+   * Present when this node activation is a HITL resume.
+   * The node checks `ctx.resumeContext !== undefined` and takes the resume branch.
+   */
+  resumeContext?: ResumeContext;
 }
 /**
  * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/node-example",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "publishConfig": {
     "access": "public"
   },
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@codemation/core": "0.11.0"
+    "@codemation/core": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",