@codemation/core 0.0.19 → 0.2.1

package/src/authoring/defineNode.types.ts

@@ -79,6 +79,11 @@ 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;
   readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
@@ -196,6 +201,7 @@ export function defineNode<
   const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson> {
     readonly kind = "node" as const;
     readonly type: TypeToken<unknown> = DefinedNodeRuntime;
+    readonly icon = options.icon;
 
     constructor(
       public readonly name: string,

package/src/browser.ts

@@ -1,3 +1,13 @@
+/**
+ * Browser / Next client–safe surface: no Node builtins or modules that pull `runStorage` (e.g. `node:stream/web`).
+ */
+export { AgentConnectionNodeCollector } from "./ai/AgentConnectionNodeCollector";
+export type {
+  AgentConnectionCredentialSource,
+  AgentConnectionNodeDescriptor,
+  AgentConnectionNodeRole,
+} from "./ai/AgentConnectionNodeCollector";
+export type { AgentNodeConfig } from "./ai/AiHost";
 export { ConnectionNodeIdFactory } from "./workflow/definition/ConnectionNodeIdFactory";
 export * from "./contracts/credentialTypes";
 export * from "./contracts/runtimeTypes";
@@ -5,4 +15,5 @@ export * from "./contracts/runFinishedAtFactory";
 export * from "./contracts/runTypes";
 export * from "./contracts/webhookTypes";
 export * from "./contracts/workflowTypes";
+export type { RetryPolicySpec } from "./contracts/retryPolicySpec.types";
 export { ItemsInputNormalizer } from "./serialization/ItemsInputNormalizer";

package/src/contracts/executionPersistenceContracts.ts

@@ -0,0 +1,186 @@
+import type { JsonValue, NodeActivationId, NodeId, RunId, WorkflowId } from "./workflowTypes";
+import type {
+  NodeExecutionError,
+  NodeExecutionStatus,
+  PersistedMutableRunState,
+  PersistedWorkflowSnapshot,
+  RunStatus,
+} from "./runTypes";
+
+/** Canonical id for persisted execution rows (activation or connection invocation). */
+export type ExecutionInstanceId = string;
+
+/** Stable id for persisted work-queue rows. */
+export type WorkItemId = string;
+
+/** Batch grouping for planner activations. */
+export type BatchId = string;
+
+/** Optimistic concurrency on the run root. */
+export type RunRevision = number;
+
+export type PersistedRunWorkItemKind = "queue" | "pending";
+
+export type WorkItemStatus = "queued" | "claimed" | "completed" | "failed" | "cancelled";
+
+export type PersistedExecutionInstanceKind = "workflowNodeActivation" | "connectionInvocation";
+
+export type ConnectionInvocationKind = "languageModel" | "tool" | "nestedAgent";
+
+export type PayloadStorageKind = "inline" | "external" | "omitted";
+
+/**
+ * Persisted run-work-queue row (queue entry or pending activation).
+ * Serialized to {@link RunWorkItem} in Prisma; engine still uses {@link PersistedRunState} queue + pending.
+ */
+export interface PersistedRunWorkItemRecord {
+  readonly workItemId: WorkItemId;
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly kind: PersistedRunWorkItemKind;
+  readonly orderIndex: number;
+  readonly status: WorkItemStatus;
+  readonly queueName?: string;
+  readonly claimToken?: string;
+  readonly claimedBy?: string;
+  readonly claimedAt?: string;
+  readonly availableAt: string;
+  readonly enqueuedAt: string;
+  readonly completedAt?: string;
+  readonly failedAt?: string;
+  readonly sourceInstanceId?: ExecutionInstanceId;
+  readonly parentInstanceId?: ExecutionInstanceId;
+  readonly itemsIn: number;
+  /** Queue entry when kind is queue; pending activation when kind is pending. */
+  readonly payloadJson: string;
+  readonly error?: Readonly<NodeExecutionError>;
+}
+
+/**
+ * Payload policy fields for large-batch externalization (optional on first rollout).
+ */
+export interface ExecutionPayloadPolicyFields {
+  readonly inputStorageKind: PayloadStorageKind;
+  readonly outputStorageKind: PayloadStorageKind;
+  readonly inputBytes?: number;
+  readonly outputBytes?: number;
+  readonly inputPreviewJson?: unknown;
+  readonly outputPreviewJson?: unknown;
+  readonly inputPayloadRef?: string;
+  readonly outputPayloadRef?: string;
+  readonly inputTruncated?: boolean;
+  readonly outputTruncated?: boolean;
+}
+
+/**
+ * One persisted execution row (workflow node activation or connection invocation).
+ */
+export interface PersistedExecutionInstanceRecord {
+  readonly instanceId: ExecutionInstanceId;
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly slotNodeId: NodeId;
+  readonly workflowNodeId: NodeId;
+  readonly kind: PersistedExecutionInstanceKind;
+  readonly connectionKind?: ConnectionInvocationKind;
+  readonly activationId?: NodeActivationId;
+  readonly batchId: BatchId;
+  readonly runIndex: number;
+  readonly parentInstanceId?: ExecutionInstanceId;
+  readonly parentRunId?: RunId;
+  readonly workerClaimToken?: string;
+  readonly status: NodeExecutionStatus;
+  readonly queuedAt?: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly updatedAt: string;
+  readonly itemCount: number;
+  readonly inputJson?: string;
+  readonly outputJson?: string;
+  readonly errorJson?: string;
+  readonly inputItemIndicesJson?: string;
+  readonly outputItemCount?: number;
+  readonly successfulItemCount?: number;
+  readonly failedItemCount?: number;
+  readonly truncatedInputPreviewJson?: string;
+  readonly truncatedOutputPreviewJson?: string;
+  readonly inputTruncated?: boolean;
+  readonly outputTruncated?: boolean;
+  readonly usedPinnedOutput?: boolean;
+  readonly payloadPolicy?: ExecutionPayloadPolicyFields;
+}
+
+/**
+ * Cached slot projection for planner/debugger/UI (not canonical history).
+ */
+export interface RunSlotProjectionState {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly revision: RunRevision;
+  readonly slotStatesByNodeId: Record<
+    NodeId,
+    Readonly<{
+      latestInstanceId?: ExecutionInstanceId;
+      latestTerminalInstanceId?: ExecutionInstanceId;
+      latestRunningInstanceId?: ExecutionInstanceId;
+      latestStatus?: NodeExecutionStatus;
+      invocationCount: number;
+      runCount: number;
+    }>
+  >;
+}
+
+export interface PersistedRunSlotProjectionRecord {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly revision: RunRevision;
+  readonly updatedAt: string;
+  readonly slotStatesJson: string;
+}
+
+export interface WorkflowRunDetailDto {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+  readonly status: RunStatus;
+  readonly workflowSnapshot?: PersistedWorkflowSnapshot;
+  readonly mutableState?: PersistedMutableRunState;
+  readonly slotStates: ReadonlyArray<SlotExecutionStateDto>;
+  readonly executionInstances: ReadonlyArray<ExecutionInstanceDto>;
+}
+
+export interface SlotExecutionStateDto {
+  readonly slotNodeId: NodeId;
+  readonly latestInstanceId?: ExecutionInstanceId;
+  readonly latestTerminalInstanceId?: ExecutionInstanceId;
+  readonly latestRunningInstanceId?: ExecutionInstanceId;
+  readonly status?: NodeExecutionStatus;
+  readonly invocationCount: number;
+  readonly runCount: number;
+}
+
+export interface ExecutionInstanceDto {
+  readonly instanceId: ExecutionInstanceId;
+  readonly slotNodeId: NodeId;
+  readonly workflowNodeId: NodeId;
+  readonly parentInstanceId?: ExecutionInstanceId;
+  readonly kind: PersistedExecutionInstanceKind;
+  readonly connectionKind?: ConnectionInvocationKind;
+  readonly runIndex: number;
+  readonly batchId: BatchId;
+  readonly activationId?: NodeActivationId;
+  readonly status: NodeExecutionStatus;
+  readonly queuedAt?: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly itemCount: number;
+  readonly inputJson?: JsonValue;
+  readonly outputJson?: JsonValue;
+  readonly error?: Readonly<NodeExecutionError>;
+}
+
+export interface WorkflowDetailSelectionState {
+  readonly selectedSlotNodeId: NodeId | null;
+  readonly selectedInstanceId: ExecutionInstanceId | null;
+}

package/src/contracts/index.ts

@@ -1,4 +1,5 @@
 export * from "./credentialTypes";
+export * from "./executionPersistenceContracts";
 export * from "./runtimeTypes";
 export * from "./runFinishedAtFactory";
 export * from "./runTypes";

package/src/contracts/runFinishedAtFactory.ts

@@ -1,10 +1,13 @@
 import type { PersistedRunState } from "./runTypes";
 
-type RunFinishedAtSource = Pick<PersistedRunState, "status" | "nodeSnapshotsByNodeId">;
+type RunFinishedAtSource = Pick<PersistedRunState, "status" | "nodeSnapshotsByNodeId" | "finishedAt">;
 
-/** Derives workflow end time from node snapshots for run listings. */
+/** Derives workflow end time from persisted run root or node snapshots for run listings. */
 export class RunFinishedAtFactory {
   static resolveIso(state: RunFinishedAtSource): string | undefined {
+    if (state.finishedAt && state.status !== "running" && state.status !== "pending") {
+      return state.finishedAt;
+    }
     if (state.status === "running" || state.status === "pending") {
       return undefined;
     }

package/src/contracts/runTypes.ts

@@ -228,10 +228,19 @@ export interface PendingNodeExecution {
   enqueuedAt: string;
 }
 
+export interface PersistedRunSchedulingState {
+  pending?: PendingNodeExecution;
+  queue: RunQueueEntry[];
+}
+
 export interface PersistedRunState {
   runId: RunId;
   workflowId: WorkflowId;
   startedAt: string;
+  /** Canonical terminal time for listings and retention when persisted on the run root. */
+  finishedAt?: string;
+  /** Optimistic concurrency / CAS on the run aggregate (repository may increment on save). */
+  revision?: number;
   parent?: ParentExecutionRef;
   executionOptions?: RunExecutionOptions;
   control?: PersistedRunControlState;
@@ -264,6 +273,7 @@ export interface WorkflowExecutionRepository {
     engineCounters?: EngineRunCounters;
   }): Promise<void>;
   load(runId: RunId): Promise<PersistedRunState | undefined>;
+  loadSchedulingState(runId: RunId): Promise<PersistedRunSchedulingState | undefined>;
   save(state: PersistedRunState): Promise<void>;
   deleteRun?(runId: RunId): Promise<void>;
 }

package/src/contracts/runtimeTypes.ts

@@ -298,6 +298,11 @@ export interface NodeActivationReceipt {
   queue?: string;
 }
 
+export interface PreparedNodeActivationDispatch {
+  readonly receipt: NodeActivationReceipt;
+  dispatch(): Promise<void>;
+}
+
 export interface NodeActivationContinuation {
   markNodeRunning(args: {
     runId: RunId;
@@ -321,8 +326,7 @@ export interface NodeActivationContinuation {
 
 export interface NodeActivationScheduler {
   setContinuation?(continuation: NodeActivationContinuation): void;
-  enqueue(request: NodeActivationRequest): Promise<NodeActivationReceipt>;
-  notifyPendingStatePersisted?(runId: RunId): void;
+  prepareDispatch(request: NodeActivationRequest): Promise<PreparedNodeActivationDispatch>;
   cancel?(receiptId: string): Promise<void>;
 }
 

package/src/contracts/workflowTypes.ts

@@ -24,8 +24,9 @@ export interface Edge {
 export type NodeConnectionName = string;
 
 /**
- * Named connection from an executable parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
- * but are not traversed by the main execution graph.
+ * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
+ * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
+ * also be connection-owned nodes for recursive agent attachments.
  */
 export interface WorkflowNodeConnection {
   readonly parentNodeId: NodeId;

package/src/events/EventPublishingWorkflowExecutionRepository.ts

@@ -1,4 +1,5 @@
 import type {
+  PersistedRunSchedulingState,
   PersistedRunState,
   RunId,
   RunPruneCandidate,
@@ -34,6 +35,10 @@ export class EventPublishingWorkflowExecutionRepository
     return await this.inner.load(runId);
   }
 
+  async loadSchedulingState(runId: RunId): Promise<PersistedRunSchedulingState | undefined> {
+    return await this.inner.loadSchedulingState(runId);
+  }
+
   async save(state: PersistedRunState): Promise<void> {
     await this.inner.save(state);
     await this.eventBus.publish({

package/src/execution/ActivationEnqueueService.ts

@@ -1,6 +1,7 @@
 import type {
   ConnectionInvocationRecord,
   EngineRunCounters,
+  PreparedNodeActivationDispatch,
   NodeActivationRequest,
   NodeActivationScheduler,
   NodeExecutionSnapshot,
@@ -25,8 +26,7 @@ import { NodeInputsByPortFactory } from "./NodeInputsByPortFactory";
 
 type PersistedRunStateRecord = NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>;
 
-type ActivationSchedulerPort = Pick<NodeActivationScheduler, "enqueue"> &
-  Pick<Partial<NodeActivationScheduler>, "notifyPendingStatePersisted">;
+type ActivationSchedulerPort = Pick<NodeActivationScheduler, "prepareDispatch">;
 
 export type ActivationEnqueueRequest = {
   runId: RunId;
@@ -62,7 +62,7 @@ export class ActivationEnqueueService {
   async enqueueActivationWithSnapshot(
     args: ActivationEnqueueRequest,
   ): Promise<{ result: RunResult; queuedSnapshot: NodeExecutionSnapshot }> {
-    const receipt = await this.activationScheduler.enqueue(args.request);
+    const preparedDispatch = await this.activationScheduler.prepareDispatch(args.request);
     const inputsByPort = NodeInputsByPortFactory.fromRequest(args.request);
     const itemsIn =
       args.request.kind === "multi"
@@ -76,8 +76,8 @@ export class ActivationEnqueueService {
       nodeId: args.request.nodeId,
       itemsIn,
       inputsByPort,
-      receiptId: receipt.receiptId,
-      queue: receipt.queue,
+      receiptId: preparedDispatch.receipt.receiptId,
+      queue: preparedDispatch.receipt.queue,
       batchId: args.request.batchId,
       enqueuedAt,
     };
@@ -112,14 +112,14 @@ export class ActivationEnqueueService {
         [args.request.nodeId]: queuedSnapshot,
       },
     });
-    this.notifyPendingStatePersisted(args.runId);
+    await this.dispatchPreparedActivation(preparedDispatch);
     return {
       result: { runId: args.runId, workflowId: args.workflowId, startedAt: args.startedAt, status: "pending", pending },
       queuedSnapshot,
     };
   }
 
-  private notifyPendingStatePersisted(runId: RunId): void {
-    this.activationScheduler.notifyPendingStatePersisted?.(runId);
+  private async dispatchPreparedActivation(preparedDispatch: PreparedNodeActivationDispatch): Promise<void> {
+    await preparedDispatch.dispatch();
   }
 }

package/src/execution/PersistedRunStateTerminalBuilder.ts

@@ -11,6 +11,8 @@ export class PersistedRunStateTerminalBuilder {
     queue: RunQueueEntry[];
     outputsByNode: PersistedRunState["outputsByNode"];
     nodeSnapshotsByNodeId: NonNullable<PersistedRunState["nodeSnapshotsByNodeId"]>;
+    /** When set, persisted on the run root for listings and retention pruning. */
+    finishedAtIso?: string;
   }): PersistedRunState {
     return {
       ...args.state,
@@ -20,6 +22,7 @@ export class PersistedRunStateTerminalBuilder {
       queue: args.queue,
       outputsByNode: args.outputsByNode,
       nodeSnapshotsByNodeId: args.nodeSnapshotsByNodeId,
+      finishedAt: args.finishedAtIso ?? args.state.finishedAt,
     };
   }
 }

package/src/index.ts

@@ -1,6 +1,12 @@
 export { SystemClock, type Clock } from "./contracts/Clock";
 export * from "./authoring";
 export * from "./ai/AiHost";
+export { AgentConnectionNodeCollector } from "./ai/AgentConnectionNodeCollector";
+export type {
+  AgentConnectionCredentialSource,
+  AgentConnectionNodeDescriptor,
+  AgentConnectionNodeRole,
+} from "./ai/AgentConnectionNodeCollector";
 export * from "./workflow";
 export * from "./di";
 export * from "./events";

package/src/orchestration/NodeExecutionRequestHandlerService.ts

@@ -33,17 +33,21 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
   ) {}
 
   async handleNodeExecutionRequest(request: NodeExecutionRequest): Promise<void> {
-    const state = await this.workflowExecutionRepository.load(request.runId);
+    const [state, schedulingState] = await Promise.all([
+      this.workflowExecutionRepository.load(request.runId),
+      this.workflowExecutionRepository.loadSchedulingState(request.runId),
+    ]);
     if (!state) {
       throw new Error(`Unknown runId: ${request.runId}`);
     }
     if (state.workflowId !== request.workflowId) {
       throw new Error(`workflowId mismatch for run ${request.runId}: ${state.workflowId} vs ${request.workflowId}`);
     }
-    if (state.status !== "pending" || !state.pending) {
+    const pendingExecution = schedulingState?.pending;
+    if (state.status !== "pending" || !pendingExecution) {
       return;
     }
-    if (state.pending.activationId !== request.activationId || state.pending.nodeId !== request.nodeId) {
+    if (pendingExecution.activationId !== request.activationId || pendingExecution.nodeId !== request.nodeId) {
       return;
     }
 
@@ -62,6 +66,7 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
     const resolvedParent = request.parent ?? state.parent;
     const data = this.runDataFactory.create(state.outputsByNode);
     const limits = this.resolveEngineLimitsFromState(state);
+    const persistedInput = pendingExecution.inputsByPort.in ?? request.input;
     const base = this.runExecutionContextFactory.create({
       runId: state.runId,
       workflowId: state.workflowId,
@@ -85,15 +90,15 @@ export class NodeExecutionRequestHandlerService implements NodeExecutionRequestH
         id: definition.id,
         config: definition.config,
       },
-      batchId: state.pending.batchId ?? "batch_1",
-      input: request.input,
+      batchId: pendingExecution.batchId ?? "batch_1",
+      input: persistedInput,
     });
 
     await this.continuation.markNodeRunning({
       runId: activationRequest.runId,
       activationId: activationRequest.activationId,
       nodeId: activationRequest.nodeId,
-      inputsByPort: { in: activationRequest.input },
+      inputsByPort: pendingExecution.inputsByPort,
     });
 
     let outputs;