@codemation/node-example 0.0.31 → 0.0.33

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @codemation/node-example
 
+## 0.0.33
+
+### Patch Changes
+
+- Updated dependencies [[`ed75183`](https://github.com/MadeRelevant/codemation/commit/ed75183f51ae71b06aa2e57ae4fc48ce9db2e4ce)]:
+  - @codemation/core@1.0.1
+
+## 0.0.32
+
+### Patch Changes
+
+- Updated dependencies [[`640e303`](https://github.com/MadeRelevant/codemation/commit/640e3032b1386568df725980a27761b6e230302c), [`640e303`](https://github.com/MadeRelevant/codemation/commit/640e3032b1386568df725980a27761b6e230302c)]:
+  - @codemation/core@1.0.0
+
 ## 0.0.31
 
 ### Patch Changes

package/dist/index.d.cts

@@ -2,8 +2,37 @@ import { ReadableStream } from "node:stream/web";
 import { InjectionToken as TypeToken } from "tsyringe";
 import { ZodType } from "zod";
 
-//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+//#region ../core/src/contracts/runTypes.d.ts
 
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+  details?: JsonValue;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
+type ConnectionInvocationAppendArgs = Readonly<{
+  invocationId: ConnectionInvocationId;
+  connectionNodeId: NodeId;
+  parentAgentNodeId: NodeId;
+  parentAgentActivationId: NodeActivationId;
+  status: NodeExecutionStatus;
+  managedInput?: JsonValue;
+  managedOutput?: JsonValue;
+  error?: NodeExecutionError;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  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).
@@ -87,6 +116,17 @@ 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;
@@ -123,32 +163,6 @@ interface CostTrackingTelemetry {
   forScope(scope: TelemetryScope): CostTrackingTelemetry;
 }
 //#endregion
-//#region ../core/src/contracts/runTypes.d.ts
-type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
-interface NodeExecutionError {
-  message: string;
-  name?: string;
-  stack?: string;
-  details?: JsonValue;
-}
-/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
-type ConnectionInvocationId = string;
-/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
-type ConnectionInvocationAppendArgs = Readonly<{
-  invocationId: ConnectionInvocationId;
-  connectionNodeId: NodeId;
-  parentAgentNodeId: NodeId;
-  parentAgentActivationId: NodeActivationId;
-  status: NodeExecutionStatus;
-  managedInput?: JsonValue;
-  managedOutput?: JsonValue;
-  error?: NodeExecutionError;
-  queuedAt?: string;
-  startedAt?: string;
-  finishedAt?: string;
-}>;
-//#endregion
 //#region ../core/src/contracts/runtimeTypes.d.ts
 interface NodeExecutionStatePublisher {
   markQueued(args: {
@@ -214,6 +228,12 @@ interface ExecutionContext {
   telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
+  iterationId?: NodeIterationId;
+  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
+  itemIndex?: number;
+  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
+  parentInvocationId?: ConnectionInvocationId;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
   nodeId: NodeId;
@@ -346,6 +366,12 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
+/**
+ * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
+ * per-item connection invocations and telemetry. Undefined when the executing node is a batch
+ * node or trigger that does not iterate items.
+ */
+type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;

package/dist/index.d.ts

@@ -2,8 +2,37 @@ import { ReadableStream } from "node:stream/web";
 import { InjectionToken as TypeToken } from "tsyringe";
 import { ZodType } from "zod";
 
-//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+//#region ../core/src/contracts/runTypes.d.ts
 
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+  details?: JsonValue;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
+type ConnectionInvocationAppendArgs = Readonly<{
+  invocationId: ConnectionInvocationId;
+  connectionNodeId: NodeId;
+  parentAgentNodeId: NodeId;
+  parentAgentActivationId: NodeActivationId;
+  status: NodeExecutionStatus;
+  managedInput?: JsonValue;
+  managedOutput?: JsonValue;
+  error?: NodeExecutionError;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  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).
@@ -87,6 +116,17 @@ 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;
@@ -123,32 +163,6 @@ interface CostTrackingTelemetry {
   forScope(scope: TelemetryScope): CostTrackingTelemetry;
 }
 //#endregion
-//#region ../core/src/contracts/runTypes.d.ts
-type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
-interface NodeExecutionError {
-  message: string;
-  name?: string;
-  stack?: string;
-  details?: JsonValue;
-}
-/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
-type ConnectionInvocationId = string;
-/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
-type ConnectionInvocationAppendArgs = Readonly<{
-  invocationId: ConnectionInvocationId;
-  connectionNodeId: NodeId;
-  parentAgentNodeId: NodeId;
-  parentAgentActivationId: NodeActivationId;
-  status: NodeExecutionStatus;
-  managedInput?: JsonValue;
-  managedOutput?: JsonValue;
-  error?: NodeExecutionError;
-  queuedAt?: string;
-  startedAt?: string;
-  finishedAt?: string;
-}>;
-//#endregion
 //#region ../core/src/contracts/runtimeTypes.d.ts
 interface NodeExecutionStatePublisher {
   markQueued(args: {
@@ -214,6 +228,12 @@ interface ExecutionContext {
   telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
+  iterationId?: NodeIterationId;
+  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
+  itemIndex?: number;
+  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
+  parentInvocationId?: ConnectionInvocationId;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
   nodeId: NodeId;
@@ -346,6 +366,12 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
+/**
+ * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
+ * per-item connection invocations and telemetry. Undefined when the executing node is a batch
+ * node or trigger that does not iterate items.
+ */
+type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/node-example",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "publishConfig": {
     "access": "public"
   },
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@codemation/core": "0.8.1"
+    "@codemation/core": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",