@codemation/host 0.0.1

package/dist/index-Bs4F1IsC.d.ts

@@ -0,0 +1,1044 @@
+import "reflect-metadata";
+import { ReadableStream } from "node:stream/web";
+import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
+
+//#region ../core/src/contracts/Clock.d.ts
+/** Port for time; inject `SystemClock` in production and a fake/test clock in tests. */
+interface Clock {
+  now(): Date;
+}
+//#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/runTypes.d.ts
+interface RunExecutionOptions {
+  /** Run-intent override: force the inline scheduler and bypass node-level offload decisions. */
+  localOnly?: boolean;
+  /** Marks runs started from webhook handling so orchestration can apply webhook-specific continuation rules. */
+  webhook?: boolean;
+  mode?: "manual" | "debug";
+  sourceWorkflowId?: WorkflowId;
+  sourceRunId?: RunId;
+  derivedFromRunId?: RunId;
+  isMutable?: boolean;
+  /** Set by the engine for this run: 0 = root, 1 = first child subworkflow, … */
+  subworkflowDepth?: number;
+  /** Effective cap after engine policy merge (successful node completions per run). */
+  maxNodeActivations?: number;
+  /** Effective cap after engine policy merge (subworkflow nesting). */
+  maxSubworkflowDepth?: number;
+}
+/** Engine-owned counters persisted with the run (worker-safe). */
+interface EngineRunCounters {
+  completedNodeActivations: number;
+}
+type RunStopCondition = Readonly<{
+  kind: "workflowCompleted";
+}> | Readonly<{
+  kind: "nodeCompleted";
+  nodeId: NodeId;
+}>;
+interface RunStateResetRequest {
+  clearFromNodeId: NodeId;
+}
+interface PersistedRunControlState {
+  stopCondition?: RunStopCondition;
+}
+interface PersistedWorkflowSnapshotNode {
+  id: NodeId;
+  kind: NodeKind;
+  name?: string;
+  nodeTokenId: PersistedTokenId;
+  configTokenId: PersistedTokenId;
+  tokenName?: string;
+  configTokenName?: string;
+  config: unknown;
+}
+interface PersistedWorkflowSnapshot {
+  id: WorkflowId;
+  name: string;
+  nodes: ReadonlyArray<PersistedWorkflowSnapshotNode>;
+  edges: ReadonlyArray<Edge>;
+  /** When the snapshot was built from a live workflow definition that configured a workflow error handler. */
+  workflowErrorHandlerConfigured?: boolean;
+  /** Connection metadata for child nodes not in the execution graph (e.g. AI agent attachments). */
+  connections?: ReadonlyArray<WorkflowNodeConnection>;
+}
+type PinnedNodeOutputsByPort = Readonly<Record<OutputPortKey, Items>>;
+interface PersistedMutableNodeState {
+  pinnedOutputsByPort?: PinnedNodeOutputsByPort;
+  lastDebugInput?: Items;
+}
+interface PersistedMutableRunState {
+  nodesById: Readonly<Record<NodeId, PersistedMutableNodeState>>;
+}
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+interface RunQueueEntry {
+  nodeId: NodeId;
+  input: Items;
+  toInput?: InputPortKey;
+  batchId?: string;
+  from?: Readonly<{
+    nodeId: NodeId;
+    output: OutputPortKey;
+  }>;
+  collect?: Readonly<{
+    expectedInputs: ReadonlyArray<InputPortKey>;
+    received: Readonly<Record<InputPortKey, Items>>;
+  }>;
+}
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+}
+interface NodeExecutionSnapshot {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId?: NodeActivationId;
+  parent?: ParentExecutionRef;
+  status: NodeExecutionStatus;
+  usedPinnedOutput?: boolean;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  updatedAt: string;
+  inputsByPort?: NodeInputsByPort;
+  outputs?: NodeOutputs;
+  error?: NodeExecutionError;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/**
+ * One logical LLM or tool call under an owning workflow node (e.g. AI agent).
+ * The owning node defines what {@link managedInput} and {@link managedOutput} contain.
+ */
+interface ConnectionInvocationRecord {
+  readonly invocationId: ConnectionInvocationId;
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly connectionNodeId: NodeId;
+  readonly parentAgentNodeId: NodeId;
+  readonly parentAgentActivationId: NodeActivationId;
+  readonly status: NodeExecutionStatus;
+  readonly managedInput?: JsonValue;
+  readonly managedOutput?: JsonValue;
+  readonly error?: NodeExecutionError;
+  readonly queuedAt?: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly updatedAt: 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;
+}>;
+interface RunCurrentState {
+  outputsByNode: Record<NodeId, NodeOutputs>;
+  nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
+  /** Append-only history of connection-scoped invocations (LLM/tool) for inspector and canvas. */
+  connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
+  mutableState?: PersistedMutableRunState;
+}
+interface CurrentStateExecutionRequest {
+  workflow: WorkflowDefinition;
+  items?: Items;
+  parent?: ParentExecutionRef;
+  executionOptions?: RunExecutionOptions;
+  workflowSnapshot?: PersistedWorkflowSnapshot;
+  mutableState?: PersistedMutableRunState;
+  currentState?: RunCurrentState;
+  stopCondition?: RunStopCondition;
+  reset?: RunStateResetRequest;
+}
+type RunStatus = "running" | "pending" | "completed" | "failed";
+interface RunSummary {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: RunStatus;
+  /** ISO timestamp when the run finished (derived from node snapshots or store `updatedAt`); omit while running/pending. */
+  finishedAt?: string;
+  parent?: ParentExecutionRef;
+  executionOptions?: RunExecutionOptions;
+}
+interface PendingNodeExecution {
+  runId: RunId;
+  activationId: NodeActivationId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  itemsIn: number;
+  inputsByPort: NodeInputsByPort;
+  receiptId: string;
+  queue?: string;
+  batchId?: string;
+  enqueuedAt: string;
+}
+interface PersistedRunState {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  parent?: ParentExecutionRef;
+  executionOptions?: RunExecutionOptions;
+  control?: PersistedRunControlState;
+  workflowSnapshot?: PersistedWorkflowSnapshot;
+  mutableState?: PersistedMutableRunState;
+  /** Frozen at createRun from workflow + runtime defaults for prune/storage decisions. */
+  policySnapshot?: PersistedRunPolicySnapshot;
+  /** Successful node completions so far (for activation budget). */
+  engineCounters?: EngineRunCounters;
+  status: RunStatus;
+  pending?: PendingNodeExecution;
+  queue: RunQueueEntry[];
+  outputsByNode: Record<NodeId, NodeOutputs>;
+  nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
+  /** Append-only history of connection invocations (LLM/tool) nested under owning nodes. */
+  connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
+}
+interface WorkflowExecutionRepository {
+  createRun(args: {
+    runId: RunId;
+    workflowId: WorkflowId;
+    startedAt: string;
+    parent?: ParentExecutionRef;
+    executionOptions?: RunExecutionOptions;
+    control?: PersistedRunControlState;
+    workflowSnapshot?: PersistedWorkflowSnapshot;
+    mutableState?: PersistedMutableRunState;
+    policySnapshot?: PersistedRunPolicySnapshot;
+    engineCounters?: EngineRunCounters;
+  }): Promise<void>;
+  load(runId: RunId): Promise<PersistedRunState | undefined>;
+  save(state: PersistedRunState): Promise<void>;
+  deleteRun?(runId: RunId): Promise<void>;
+}
+type RunResult = {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "completed";
+  outputs: Items;
+} | {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "pending";
+  pending: PendingNodeExecution;
+} | {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "failed";
+  error: {
+    message: string;
+  };
+};
+type WebhookRunResult = Readonly<{
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  runStatus: "pending" | "completed";
+  response: Items;
+}>;
+interface PersistedWorkflowTokenRegistryLike {
+  register(type: TypeToken<unknown>, packageId: string, persistedNameOverride?: string): string;
+  getTokenId(type: TypeToken<unknown>): string | undefined;
+  resolve(tokenId: string): TypeToken<unknown> | undefined;
+  registerFromWorkflows?(workflows: ReadonlyArray<WorkflowDefinition>): void;
+}
+//#endregion
+//#region ../core/src/contracts/workflowActivationPolicy.d.ts
+/**
+ * Host-controlled policy: when false, trigger {@link TriggerNode} setup is skipped and webhook routes
+ * for that workflow are not registered (see engine trigger runtime + webhook matcher).
+ */
+interface WorkflowActivationPolicy {
+  isActive(workflowId: WorkflowId): boolean;
+}
+//#endregion
+//#region ../core/src/contracts/webhookTypes.d.ts
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Match for an incoming HTTP request: user-defined URL segment + workflow trigger node. */
+interface WebhookInvocationMatch {
+  /** Same value as the webhook trigger's configured endpoint key (URL segment under the webhook base path). */
+  endpointPath: string;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  methods: ReadonlyArray<HttpMethod>;
+  parseJsonBody?: (body: unknown) => unknown;
+}
+/** Result of resolving an HTTP method + endpoint path against the catalog webhook index (404 vs 405 vs match). */
+type WebhookTriggerResolution = {
+  status: "notFound";
+} | {
+  status: "methodNotAllowed";
+  match: WebhookInvocationMatch;
+} | {
+  status: "ok";
+  match: WebhookInvocationMatch;
+};
+/**
+ * Resolves webhook routes from workflow definitions (catalog-backed index, no registration at trigger setup).
+ */
+interface WebhookTriggerMatcher {
+  match(args: {
+    endpointPath: string;
+    method: HttpMethod;
+  }): WebhookInvocationMatch | undefined;
+  lookup(endpointPath: string): WebhookInvocationMatch | undefined;
+  onEngineWorkflowsLoaded?(): void;
+  onEngineStopped?(): void;
+  /** Rebuild route index after activation changes without stopping the engine. */
+  reloadWebhookRoutes?(): void;
+}
+//#endregion
+//#region ../core/src/contracts/runtimeTypes.d.ts
+interface WorkflowRepository {
+  list(): ReadonlyArray<WorkflowDefinition>;
+  get(workflowId: WorkflowId): WorkflowDefinition | undefined;
+}
+interface LiveWorkflowRepository extends WorkflowRepository {
+  setWorkflows(workflows: ReadonlyArray<WorkflowDefinition>): void;
+}
+interface NodeResolver {
+  resolve<T>(token: TypeToken<T>): T;
+}
+interface NodeExecutionStatePublisher {
+  markQueued(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void>;
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void>;
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+}
+type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
+interface BinaryStorageWriteRequest {
+  storageKey: string;
+  body: BinaryBody;
+}
+interface BinaryStorageWriteResult {
+  storageKey: string;
+  size: number;
+  sha256?: string;
+}
+interface BinaryStorageReadResult {
+  body: ReadableStream<Uint8Array>;
+  size?: number;
+}
+interface BinaryStorageStatResult {
+  exists: boolean;
+  size?: number;
+}
+interface BinaryStorage {
+  readonly driverName: string;
+  write(args: BinaryStorageWriteRequest): Promise<BinaryStorageWriteResult>;
+  openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined>;
+  stat(storageKey: string): Promise<BinaryStorageStatResult>;
+  delete(storageKey: string): Promise<void>;
+}
+interface BinaryAttachmentCreateRequest {
+  name: string;
+  body: BinaryBody;
+  mimeType: string;
+  filename?: string;
+  previewKind?: BinaryAttachment["previewKind"];
+}
+interface NodeBinaryAttachmentService extends ExecutionBinaryService {
+  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
+}
+interface ExecutionBinaryService {
+  forNode(args: {
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }): NodeBinaryAttachmentService;
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+}
+interface ExecutionContext {
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  /** This run's subworkflow depth (0 = root). */
+  subworkflowDepth: number;
+  /** Effective activation budget cap for this run (after policy merge). */
+  engineMaxNodeActivations: number;
+  /** Effective subworkflow nesting cap for this run (after policy merge). */
+  engineMaxSubworkflowDepth: number;
+  now: () => Date;
+  data: RunDataSnapshot;
+  nodeState?: NodeExecutionStatePublisher;
+  binary: ExecutionBinaryService;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+}
+interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  config: TConfig;
+  binary: NodeBinaryAttachmentService;
+}
+interface NodeExecutionRequest {
+  runId: RunId;
+  activationId: NodeActivationId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  input: Items;
+  parent?: ParentExecutionRef;
+  queue?: string;
+  executionOptions?: RunExecutionOptions;
+}
+interface NodeExecutionScheduler {
+  enqueue(request: NodeExecutionRequest): Promise<{
+    receiptId: string;
+  }>;
+  cancel?(receiptId: string): Promise<void>;
+}
+interface NodeActivationContinuation {
+  markNodeRunning(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    inputsByPort: NodeInputsByPort;
+  }): Promise<void>;
+  resumeFromNodeResult(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    outputs: NodeOutputs;
+  }): Promise<RunResult>;
+  resumeFromNodeError(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    error: Error;
+  }): Promise<RunResult>;
+}
+interface WorkflowSnapshotResolver {
+  resolve(args: {
+    workflowId: WorkflowId;
+    workflowSnapshot?: PersistedWorkflowSnapshot;
+  }): WorkflowDefinition | undefined;
+}
+//#endregion
+//#region ../core/src/contracts/workflowTypes.d.ts
+type WorkflowId = string;
+type NodeId = string;
+type OutputPortKey = string;
+type InputPortKey = string;
+type PersistedTokenId = string;
+type NodeKind = "trigger" | "node";
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+type JsonArray = ReadonlyArray<JsonValue>;
+interface Edge {
+  from: {
+    nodeId: NodeId;
+    output: OutputPortKey;
+  };
+  to: {
+    nodeId: NodeId;
+    input: InputPortKey;
+  };
+}
+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.
+ */
+interface WorkflowNodeConnection {
+  readonly parentNodeId: NodeId;
+  readonly connectionName: NodeConnectionName;
+  readonly childNodeIds: ReadonlyArray<NodeId>;
+}
+interface WorkflowDefinition {
+  id: WorkflowId;
+  name: string;
+  nodes: NodeDefinition[];
+  edges: Edge[];
+  /**
+   * Optional metadata: which nodes are connection-owned children (e.g. AI agent `llm` / `tools` slots).
+   * When omitted, all nodes in {@link nodes} are treated as executable for topology.
+   */
+  readonly connections?: ReadonlyArray<WorkflowNodeConnection>;
+  /** Directory + file-stem path under a workflow discovery root (for UI grouping only). */
+  discoveryPathSegments?: readonly string[];
+  /** Retention for run JSON and binaries (seconds). Host/env may supply defaults when omitted. */
+  readonly prunePolicy?: WorkflowPrunePolicySpec;
+  /** Whether to keep run data after completion. Host/env may supply defaults when omitted. */
+  readonly storagePolicy?: WorkflowStoragePolicySpec;
+  /** Invoked after a node fails permanently (retries exhausted) and node error handler did not recover. */
+  readonly workflowErrorHandler?: WorkflowErrorHandlerSpec;
+}
+interface NodeConfigBase {
+  readonly kind: NodeKind;
+  readonly type: TypeToken<unknown>;
+  readonly name?: string;
+  readonly id?: NodeId;
+  readonly icon?: string;
+  readonly execution?: Readonly<{
+    hint?: "local" | "worker";
+    queue?: string;
+  }>;
+  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
+  readonly retryPolicy?: RetryPolicySpec;
+  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
+  readonly nodeErrorHandler?: NodeErrorHandlerSpec;
+  /**
+   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
+   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
+   * main batches skip downstream execution and propagate the empty path.
+   */
+  readonly continueWhenEmptyOutput?: boolean;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+interface NodeDefinition {
+  id: NodeId;
+  kind: NodeKind;
+  type: TypeToken<unknown>;
+  name?: string;
+  config: NodeConfigBase;
+}
+type PairedItemRef = Readonly<{
+  nodeId: NodeId;
+  output: OutputPortKey;
+  itemIndex: number;
+}>;
+type BinaryPreviewKind = "image" | "audio" | "video" | "download";
+type BinaryAttachment = Readonly<{
+  id: string;
+  storageKey: string;
+  mimeType: string;
+  size: number;
+  storageDriver: string;
+  previewKind: BinaryPreviewKind;
+  createdAt: string;
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  filename?: string;
+  sha256?: string;
+}>;
+type ItemBinary = Readonly<Record<string, BinaryAttachment>>;
+type Item<TJson = unknown> = Readonly<{
+  json: TJson;
+  binary?: ItemBinary;
+  meta?: Readonly<Record<string, unknown>>;
+  paired?: ReadonlyArray<PairedItemRef>;
+}>;
+type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
+type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
+type RunId = string;
+type NodeActivationId = string;
+interface ParentExecutionRef {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
+  subworkflowDepth?: number;
+  /** Effective max node activations from the parent run (propagated to child policy merge). */
+  engineMaxNodeActivations?: number;
+  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
+  engineMaxSubworkflowDepth?: number;
+}
+interface RunDataSnapshot {
+  getOutputs(nodeId: NodeId): NodeOutputs | undefined;
+  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
+  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+}
+interface RunIdFactory {
+  makeRunId(): RunId;
+}
+interface ActivationIdFactory {
+  makeActivationId(): NodeActivationId;
+}
+/** Whether to persist run execution data after the workflow finishes. */
+type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
+type WorkflowStoragePolicySpec = WorkflowStoragePolicyMode | TypeToken<WorkflowStoragePolicyResolver>;
+interface WorkflowStoragePolicyResolver {
+  shouldPersist(args: WorkflowStoragePolicyDecisionArgs): boolean | Promise<boolean>;
+}
+interface WorkflowStoragePolicyDecisionArgs {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly workflow: WorkflowDefinition;
+  readonly finalStatus: "completed" | "failed";
+  readonly startedAt: string;
+  readonly finishedAt: string;
+}
+interface WorkflowPrunePolicySpec {
+  readonly runDataRetentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+}
+interface PersistedRunPolicySnapshot {
+  readonly retentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+  readonly storagePolicy: WorkflowStoragePolicyMode;
+}
+interface WorkflowErrorHandler {
+  onError(ctx: WorkflowErrorContext): void | Promise<void>;
+}
+interface WorkflowErrorContext {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly workflow: WorkflowDefinition;
+  readonly failedNodeId: NodeId;
+  readonly error: Error;
+  readonly startedAt: string;
+  readonly finishedAt: string;
+}
+type WorkflowErrorHandlerSpec = TypeToken<WorkflowErrorHandler> | WorkflowErrorHandler;
+interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
+  readonly kind: "single" | "multi";
+  readonly items: Items;
+  readonly inputsByPort: Readonly<Record<InputPortKey, Items>> | undefined;
+  readonly ctx: NodeExecutionContext<TConfig>;
+  readonly error: Error;
+}
+interface NodeErrorHandler {
+  handle<TConfig extends NodeConfigBase>(args: NodeErrorHandlerArgs<TConfig>): Promise<NodeOutputs>;
+}
+type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
+//#endregion
+//#region ../core/src/contracts/credentialTypes.d.ts
+type CredentialTypeId = string;
+type CredentialInstanceId = string;
+type CredentialMaterialSourceKind = "db" | "env" | "code";
+type CredentialSetupStatus = "draft" | "ready";
+type CredentialHealthStatus = "unknown" | "healthy" | "failing";
+type CredentialFieldSchema = Readonly<{
+  key: string;
+  label: string;
+  type: "string" | "password" | "textarea" | "json" | "boolean";
+  required?: true;
+  order?: number;
+  placeholder?: string;
+  helpText?: string;
+  /** When set, host resolves this field from process.env at runtime; env wins over stored values. */
+  envVarName?: string;
+  /**
+   * When set, the dialog shows a copy action for this exact string (e.g. a static OAuth redirect URI
+   * pattern or documentation URL). Do not use for secret values.
+   */
+  copyValue?: string;
+  /** Accessible label for the copy control (default: Copy). */
+  copyButtonLabel?: string;
+}>;
+type CredentialRequirement = Readonly<{
+  slotKey: string;
+  label: string;
+  acceptedTypes: ReadonlyArray<CredentialTypeId>;
+  optional?: true;
+  helpText?: string;
+  helpUrl?: string;
+}>;
+type CredentialBindingKey = Readonly<{
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  slotKey: string;
+}>;
+type CredentialBinding = Readonly<{
+  key: CredentialBindingKey;
+  instanceId: CredentialInstanceId;
+  updatedAt: string;
+}>;
+type CredentialHealth = Readonly<{
+  status: CredentialHealthStatus;
+  message?: string;
+  testedAt?: string;
+  expiresAt?: string;
+  details?: Readonly<Record<string, unknown>>;
+}>;
+type OAuth2ProviderFromPublicConfig = Readonly<{
+  authorizeUrlFieldKey: string;
+  tokenUrlFieldKey: string;
+  userInfoUrlFieldKey?: string;
+}>;
+type CredentialOAuth2AuthDefinition = Readonly<{
+  kind: "oauth2";
+  providerId: string;
+  scopes: ReadonlyArray<string>;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+} | {
+  kind: "oauth2";
+  providerFromPublicConfig: OAuth2ProviderFromPublicConfig;
+  scopes: ReadonlyArray<string>;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+}>;
+type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;
+type CredentialTypeDefinition = Readonly<{
+  typeId: CredentialTypeId;
+  displayName: string;
+  description?: string;
+  publicFields?: ReadonlyArray<CredentialFieldSchema>;
+  secretFields?: ReadonlyArray<CredentialFieldSchema>;
+  supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+  auth?: CredentialAuthDefinition;
+}>;
+/**
+ * JSON-shaped credential field bag (public config, resolved secret material, etc.).
+ */
+type CredentialJsonRecord = Readonly<Record<string, unknown>>;
+/**
+ * Persisted credential instance with typed `publicConfig`.
+ * Hosts may specialize `secretRef` with a stricter union while remaining
+ * assignable here for session/test callbacks.
+ */
+type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
+  instanceId: CredentialInstanceId;
+  typeId: CredentialTypeId;
+  displayName: string;
+  sourceKind: CredentialMaterialSourceKind;
+  publicConfig: TPublicConfig;
+  secretRef: CredentialJsonRecord;
+  tags: ReadonlyArray<string>;
+  setupStatus: CredentialSetupStatus;
+  createdAt: string;
+  updatedAt: string;
+}>;
+/**
+ * Arguments passed to `CredentialType.createSession` and `CredentialType.test`.
+ * Declare `TPublicConfig` / `TMaterial` on `CredentialType` so implementations are checked
+ * against your credential shapes (similar to `NodeExecutionContext.config` for nodes).
+ */
+type CredentialSessionFactoryArgs<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
+  instance: CredentialInstanceRecord<TPublicConfig>;
+  material: TMaterial;
+  publicConfig: TPublicConfig;
+}>;
+type CredentialSessionFactory<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<TSession>;
+type CredentialHealthTester<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<CredentialHealth>;
+/**
+ * Full credential type implementation: `definition` (UI/schema), `createSession`, and `test`.
+ * Use this at registration and config boundaries; `CredentialTypeDefinition` is only the schema slice.
+ */
+type CredentialType<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = Readonly<{
+  definition: CredentialTypeDefinition;
+  createSession: CredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
+  test: CredentialHealthTester<TPublicConfig, TMaterial>;
+}>;
+/**
+ * Credential type with unspecified generics — used for `CodemationConfig.credentialTypes`, the host registry,
+ * and anywhere a concrete `CredentialType<YourPublic, YourMaterial, YourSession>` is placed in a heterogeneous list.
+ * Using `any` here avoids unsafe `as` casts while keeping typed `satisfies CredentialType<…>` definitions.
+ */
+type AnyCredentialType = CredentialType<any, any, unknown>;
+interface CredentialSessionService {
+  getSession<TSession = unknown>(args: Readonly<{
+    workflowId: WorkflowId;
+    nodeId: NodeId;
+    slotKey: string;
+  }>): Promise<TSession>;
+}
+interface CredentialTypeRegistry {
+  listTypes(): ReadonlyArray<CredentialTypeDefinition>;
+  getType(typeId: CredentialTypeId): CredentialTypeDefinition | undefined;
+}
+//#endregion
+//#region ../core/src/events/runEvents.d.ts
+type RunEvent = Readonly<{
+  kind: "runCreated";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+}> | Readonly<{
+  kind: "runSaved";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  state: PersistedRunState;
+}> | Readonly<{
+  kind: "nodeQueued";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}> | Readonly<{
+  kind: "nodeStarted";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}> | Readonly<{
+  kind: "nodeCompleted";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}> | Readonly<{
+  kind: "nodeFailed";
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  at: string;
+  snapshot: NodeExecutionSnapshot;
+}>;
+//#endregion
+//#region ../core/src/policies/executionLimits/EngineExecutionLimitsPolicy.d.ts
+interface EngineExecutionLimitsPolicyConfig {
+  readonly defaultMaxNodeActivations: number;
+  readonly hardMaxNodeActivations: number;
+  readonly defaultMaxSubworkflowDepth: number;
+  readonly hardMaxSubworkflowDepth: number;
+}
+/**
+ * Resolves per-run execution limits: defaults, hard ceilings, and subworkflow depth for new runs.
+ */
+declare class EngineExecutionLimitsPolicy {
+  private readonly config;
+  constructor(config?: EngineExecutionLimitsPolicyConfig);
+  /**
+   * Effective options for a new root run (depth 0): defaults merged with engine ceilings.
+   * Replaces a separate one-method factory for root-run bootstrap.
+   */
+  createRootExecutionOptions(): RunExecutionOptions;
+  mergeExecutionOptionsForNewRun(parent: ParentExecutionRef | undefined, user: RunExecutionOptions | undefined): RunExecutionOptions;
+  private capNumber;
+}
+//#endregion
+//#region ../core/src/orchestration/Engine.d.ts
+interface EngineTriggerRuntime {
+  startTriggers(): Promise<void>;
+  stop(): Promise<void>;
+  syncWorkflowTriggersForActivation(workflowId: WorkflowId): Promise<void>;
+  createTriggerTestItems(args: {
+    workflow: WorkflowDefinition;
+    nodeId: NodeId;
+  }): Promise<Items | undefined>;
+}
+interface EngineRunStartService {
+  runWorkflow(wf: WorkflowDefinition, startAt: NodeId, items: Items, parent?: ParentExecutionRef, executionOptions?: RunExecutionOptions, persistedStateOverrides?: Readonly<{
+    workflowSnapshot?: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["workflowSnapshot"];
+    mutableState?: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["mutableState"];
+  }>): Promise<RunResult>;
+  runWorkflowFromState(request: CurrentStateExecutionRequest): Promise<RunResult>;
+}
+interface EngineRunContinuationService {
+  markNodeRunning(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    inputsByPort: NodeInputsByPort;
+  }): Promise<void>;
+  resumeFromNodeResult(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    outputs: NodeOutputs;
+  }): Promise<RunResult>;
+  resumeFromNodeError(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    error: Error;
+  }): Promise<RunResult>;
+  resumeFromStepResult(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    outputs: NodeOutputs;
+  }): Promise<RunResult>;
+  resumeFromStepError(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    error: Error;
+  }): Promise<RunResult>;
+  waitForCompletion(runId: RunId): Promise<Extract<RunResult, {
+    status: "completed" | "failed";
+  }>>;
+  waitForWebhookResponse(runId: RunId): Promise<WebhookRunResult>;
+}
+interface EngineFacadeDeps {
+  liveWorkflowRepository: LiveWorkflowRepository;
+  tokenRegistry: PersistedWorkflowTokenRegistryLike;
+  webhookTriggerMatcher: WebhookTriggerMatcher;
+  workflowSnapshotResolver: WorkflowSnapshotResolver;
+  triggerRuntime: EngineTriggerRuntime;
+  runStartService: EngineRunStartService;
+  runContinuationService: EngineRunContinuationService;
+}
+/**
+ * Runtime facade for orchestration, continuation, triggers, and webhook routing.
+ * Prefer {@link import("../intents/RunIntentService").RunIntentService} for host/HTTP invocation boundaries.
+ * The class token is exported from `@codemation/core/bootstrap` (not the main `@codemation/core` barrel).
+ */
+declare class Engine implements NodeActivationContinuation {
+  private readonly deps;
+  constructor(deps: EngineFacadeDeps);
+  loadWorkflows(workflows: ReadonlyArray<WorkflowDefinition>): void;
+  getTokenRegistry(): EngineFacadeDeps["tokenRegistry"];
+  resolveWorkflowSnapshot(args: {
+    workflowId: WorkflowId;
+    workflowSnapshot?: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["workflowSnapshot"];
+  }): WorkflowDefinition | undefined;
+  startTriggers(): Promise<void>;
+  syncWorkflowTriggersForActivation(workflowId: WorkflowId): Promise<void>;
+  start(workflows: WorkflowDefinition[]): Promise<void>;
+  stop(): Promise<void>;
+  resolveWebhookTrigger(args: {
+    endpointPath: string;
+    method: HttpMethod;
+  }): WebhookTriggerResolution;
+  createTriggerTestItems(args: {
+    workflow: WorkflowDefinition;
+    nodeId: NodeId;
+  }): Promise<Items | undefined>;
+  runWorkflow(wf: WorkflowDefinition, startAt: NodeId, items: Items, parent?: ParentExecutionRef, executionOptions?: RunExecutionOptions, persistedStateOverrides?: Readonly<{
+    workflowSnapshot?: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["workflowSnapshot"];
+    mutableState?: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["mutableState"];
+  }>): Promise<RunResult>;
+  runWorkflowFromState(request: CurrentStateExecutionRequest): Promise<RunResult>;
+  markNodeRunning(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    inputsByPort: NodeInputsByPort;
+  }): Promise<void>;
+  resumeFromNodeResult(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    outputs: NodeOutputs;
+  }): Promise<RunResult>;
+  resumeFromNodeError(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    error: Error;
+  }): Promise<RunResult>;
+  resumeFromStepResult(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    outputs: NodeOutputs;
+  }): Promise<RunResult>;
+  resumeFromStepError(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    error: Error;
+  }): Promise<RunResult>;
+  waitForCompletion(runId: RunId): Promise<Extract<RunResult, {
+    status: "completed" | "failed";
+  }>>;
+  waitForWebhookResponse(runId: RunId): Promise<WebhookRunResult>;
+}
+//#endregion
+//#region ../core/src/runtime/RunIntentService.d.ts
+type StartWorkflowIntent = {
+  workflow: WorkflowDefinition;
+  startAt?: string;
+  items: Items;
+  parent?: CurrentStateExecutionRequest["parent"];
+  executionOptions?: RunExecutionOptions;
+  workflowSnapshot?: CurrentStateExecutionRequest["workflowSnapshot"];
+  mutableState?: CurrentStateExecutionRequest["mutableState"];
+  currentState?: RunCurrentState;
+  stopCondition?: RunStopCondition;
+  reset?: CurrentStateExecutionRequest["reset"];
+};
+type RerunFromNodeIntent = {
+  workflow: WorkflowDefinition;
+  nodeId: NodeId;
+  currentState: RunCurrentState;
+  items?: Items;
+  parent?: CurrentStateExecutionRequest["parent"];
+  executionOptions?: RunExecutionOptions;
+  workflowSnapshot?: CurrentStateExecutionRequest["workflowSnapshot"];
+  mutableState?: CurrentStateExecutionRequest["mutableState"];
+};
+type MatchedWebhookRunIntent = {
+  endpointPath: string;
+  method: HttpMethod;
+  requestItem: Items[number];
+};
+type WebhookMatchRunIntent = {
+  match: WebhookInvocationMatch;
+  requestItem: Items[number];
+};
+declare class RunIntentService {
+  private readonly engine;
+  private readonly workflowRepository;
+  constructor(engine: Engine, workflowRepository: WorkflowRepository);
+  startWorkflow(args: StartWorkflowIntent): Promise<RunResult>;
+  rerunFromNode(args: RerunFromNodeIntent): Promise<RunResult>;
+  resolveWebhookTrigger(args: {
+    endpointPath: string;
+    method: HttpMethod;
+  }): WebhookTriggerResolution;
+  runMatchedWebhook(args: MatchedWebhookRunIntent): Promise<WebhookRunResult>;
+  runWebhookMatch(args: WebhookMatchRunIntent): Promise<WebhookRunResult>;
+  /**
+   * Webhook-triggered runs always force inline execution first.
+   * This is the highest-precedence scheduler override: it wins over node hints and container defaults.
+   */
+  private createWebhookExecutionOptions;
+}
+//#endregion
+export { RunIdFactory as A, PersistedRunState as B, CredentialTypeId as C, Item as D, BinaryAttachment as E, NodeExecutionScheduler as F, RunSummary as H, NodeResolver as I, WorkflowRepository as L, WorkflowId as M, BinaryStorage as N, NodeDefinition as O, NodeActivationContinuation as P, WebhookInvocationMatch as R, CredentialTypeDefinition as S, ActivationIdFactory as T, WorkflowExecutionRepository as U, RunCurrentState as V, Clock as W, CredentialRequirement as _, EngineExecutionLimitsPolicyConfig as a, CredentialSetupStatus as b, CredentialBinding as c, CredentialHealth as d, CredentialInstanceId as f, CredentialOAuth2AuthDefinition as g, CredentialMaterialSourceKind as h, EngineExecutionLimitsPolicy as i, WorkflowDefinition as j, RunId as k, CredentialBindingKey as l, CredentialJsonRecord as m, Container as n, RunEvent as o, CredentialInstanceRecord as p, TypeToken as r, AnyCredentialType as s, RunIntentService as t, CredentialFieldSchema as u, CredentialSessionFactoryArgs as v, CredentialTypeRegistry as w, CredentialType as x, CredentialSessionService as y, WorkflowActivationPolicy as z };
+//# sourceMappingURL=index-Bs4F1IsC.d.ts.map