@codemation/core 0.14.0 → 0.15.0

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -33,11 +33,6 @@ import { Engine } from "../../orchestration/Engine";
 import type { EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types";
 import type { WebhookTriggerMatcherProvider } from "./EngineRuntimeRegistration.types";
 
-/**
- * Container-first entry: call on a host/test container **after** workflow, run, node, and credential
- * ports are registered. The registrar owns the default inline scheduler, engine binding,
- * and intent-surface wiring so hosts only override the seams they actually replace.
- */
 export class EngineRuntimeRegistrar {
   register(container: DependencyContainer, options?: EngineRuntimeRegistrationOptions): void {
     this.registerSupportFactories(container);

package/src/bootstrap/runtime/EngineRuntimeRegistration.types.ts

@@ -5,42 +5,19 @@ import type { TriggerRuntimeDiagnostics } from "../../contracts/runtimeTypes";
 import type { WorkflowPolicyRuntimeDefaults } from "../../contracts/workflowTypes";
 import type { EngineExecutionLimitsPolicyConfig } from "../../policies/executionLimits/EngineExecutionLimitsPolicy";
 
-/**
- * Creates the webhook route matcher used by {@link import("../api/Engine").Engine}.
- * Hosts may supply logging/diagnostics; tests often use the default factory without diagnostics.
- */
 export interface WebhookTriggerMatcherProvider {
   createMatcher(container: DependencyContainer): WebhookTriggerMatcher;
 }
 
-/**
- * Supplies optional trigger-runtime logging (inactive workflow skips, activation sync).
- */
 export interface TriggerRuntimeDiagnosticsProvider {
   create(container: DependencyContainer): TriggerRuntimeDiagnostics | undefined;
 }
 
 export interface EngineRuntimeRegistrationOptions {
-  /**
-   * Static limits merged into the factory when the policy token is first resolved.
-   * Prefer {@link resolveEngineExecutionLimits} when limits can change after registration (e.g. host `useRuntimeConfig`).
-   */
   engineExecutionLimits?: Partial<EngineExecutionLimitsPolicyConfig>;
-  /**
-   * Called when the limits policy is first resolved; overrides {@link engineExecutionLimits} when both are set.
-   * Use this for host wiring so `runtime.engineExecutionLimits` applied after `registerCoreInfrastructure` is honored.
-   */
   resolveEngineExecutionLimits?: () => Partial<EngineExecutionLimitsPolicyConfig> | undefined;
-  /**
-   * When {@link webhookTriggerMatcherProvider} is omitted, the registrar builds
-   * {@link import("../../runtime/WorkflowRepositoryWebhookTriggerMatcher").WorkflowRepositoryWebhookTriggerMatcher}
-   * using this optional routing diagnostics surface.
-   */
   webhookTriggerRoutingDiagnostics?: WebhookTriggerRoutingDiagnostics;
-  /** Overrides default webhook matcher construction (e.g. host-injected loggers). */
   webhookTriggerMatcherProvider?: WebhookTriggerMatcherProvider;
-  /** Overrides default trigger diagnostics (undefined when omitted). */
   triggerRuntimeDiagnosticsProvider?: TriggerRuntimeDiagnosticsProvider;
-  /** Runtime retention/storage defaults used when workflows omit prune/storage policy fields. */
   workflowPolicyRuntimeDefaults?: WorkflowPolicyRuntimeDefaults;
 }

package/src/browser.ts

@@ -1,6 +1,3 @@
-/**
- * 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,

package/src/contracts/AgentBindError.ts

@@ -1,8 +1,3 @@
-/**
- * Thrown at agent bind time when mcpServers declarations cannot be resolved.
- * Causes include: unknown server id, missing credential instance, insufficient scopes,
- * and ambiguous shorthand binding (multiple credential instances match).
- */
 export class AgentBindError extends Error {
   constructor(message: string) {
     super(message);

package/src/contracts/Clock.ts

@@ -1,4 +1,3 @@
-/** Port for time; inject `SystemClock` in production and a fake/test clock in tests. */
 export interface Clock {
   now(): Date;
 }

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -9,24 +9,14 @@ export class CodemationTelemetryAttributeNames {
   static readonly connectionInvocationId = "codemation.connection.invocation_id";
   static readonly toolName = "codemation.tool.name";
   static readonly traceParentRunId = "codemation.parent.run.id";
-  /** Per-item iteration that emitted this span/metric. Set on spans recorded inside a runnable per-item loop. */
   static readonly iterationId = "codemation.iteration.id";
-  /** Item index (0-based) of the iteration. */
   static readonly iterationIndex = "codemation.iteration.index";
-  /** Set when this span/metric was recorded under a sub-agent triggered by an outer LLM/tool call. */
   static readonly parentInvocationId = "codemation.parent.invocation_id";
-  /** MCP server id on spans created for callTool invocations. */
   static readonly mcpServerId = "mcp.server_id";
-  /** MCP tool name on spans created for callTool invocations. */
   static readonly mcpToolName = "mcp.tool_name";
-  /** Terminal node-execution status (e.g. `"hitl-approved"`, `"hitl-rejected"`) on HITL outcome spans. */
   static readonly nodeExecutionStatus = "codemation.node.execution_status";
-  /** Populated on run-halted spans; discriminates the halt reason (e.g. `"hitl-rejected"`). */
   static readonly runHaltReason = "codemation.run.halt_reason";
-  /** Human task ID on `hitl.task.*` span events. */
   static readonly hitlTaskId = "codemation.hitl.task_id";
-  /** HITL channel name (e.g. `"inbox"`, `"control-plane-inbox"`) on `hitl.task.*` span events. */
   static readonly hitlChannel = "codemation.hitl.channel";
-  /** Decision outcome (e.g. `"approved"`, `"rejected"`) on `hitl.task.decided` span events. */
   static readonly hitlDecisionStatus = "codemation.hitl.decision_status";
 }

package/src/contracts/NoOpAgentMcpIntegration.ts

@@ -1,11 +1,5 @@
 import type { AgentMcpIntegration, AgentMcpToolMap } from "./agentMcpTypes";
 
-/**
- * No-op implementation of AgentMcpIntegration.
- * Registered by the core engine runtime as a fallback when the host does not
- * supply a real implementation (e.g. in unit tests or headless engine setups).
- * Always returns an empty tool map so the agent runs with node-backed tools only.
- */
 export class NoOpAgentMcpIntegration implements AgentMcpIntegration {
   async prepareMcpTools(): Promise<AgentMcpToolMap> {
     return new Map();

package/src/contracts/NoOpTelemetrySpanScope.ts

@@ -11,12 +11,6 @@ import type {
 } from "./telemetryTypes";
 import { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
 
-/**
- * Standalone no-op {@link NodeExecutionTelemetry} value used as the return for `asNodeTelemetry`.
- *
- * Defined here (instead of in `NoOpNodeExecutionTelemetry.ts`) so that {@link NoOpTelemetrySpanScope}
- * can return it without importing the other module — both no-ops share this leaf.
- */
 const noOpNodeExecutionTelemetry: NodeExecutionTelemetry = {
   traceId: "00000000000000000000000000000000",
   spanId: "0000000000000000",
@@ -53,6 +47,5 @@ const noOpTelemetrySpanScope: TelemetrySpanScope = {
 
 export class NoOpTelemetrySpanScope {
   static readonly value: TelemetrySpanScope = noOpTelemetrySpanScope;
-  /** Internal: the shared no-op {@link NodeExecutionTelemetry} that {@link NoOpNodeExecutionTelemetry} re-exposes. */
   static readonly nodeExecutionTelemetryValue: NodeExecutionTelemetry = noOpNodeExecutionTelemetry;
 }

package/src/contracts/RetryPolicy.ts

@@ -15,9 +15,7 @@ export class RetryPolicy implements FixedRetryPolicySpec {
     }
   }
 
-  /** Default for HTTP-style transient failures: 3 tries, 1s between attempts. */
   static readonly defaultForHttp: FixedRetryPolicySpec = { kind: "fixed", maxAttempts: 3, delayMs: 1000 };
 
-  /** Default for LLM / agent calls: 3 tries, 2s fixed backoff. */
   static readonly defaultForAiAgent: FixedRetryPolicySpec = { kind: "fixed", maxAttempts: 3, delayMs: 2000 };
 }

package/src/contracts/agentMcpTypes.ts

@@ -3,44 +3,15 @@ import type { ConnectionInvocationAppendArgs, ConnectionInvocationId } from "./r
 import type { TelemetrySpanEventRecord } from "./telemetryTypes";
 import type { NodeActivationId, NodeIterationId } from "./workflowTypes";
 
-/**
- * Emitted as a span event when a credential is missing required scopes
- * (bind-time) or when callTool returns a permission error (runtime).
- * The credential type id can be looked up from the credential instance when needed.
- */
 export interface NeedsReconsentEvent {
   readonly serverId: string;
   readonly credentialInstanceId: string;
   readonly missingScopesHint?: readonly string[];
 }
 
-/**
- * An opaque MCP tool map: keyed by serverId → (toolName → tool definition).
- * Typed as unknown so core does not depend on the AI SDK's ToolSet type.
- * AIAgentNode (in core-nodes, which does depend on ai) casts this to
- * ReadonlyMap<string, ToolSet> before passing to DeferredMetaToolStrategyFactory.
- */
 export type AgentMcpToolMap = ReadonlyMap<string, Readonly<Record<string, unknown>>>;
 
-/**
- * Contract implemented by the host. Resolves MCP server bindings for an agent run
- * via the standard credential-binding table (one slot per declared server, keyed
- * by `(workflowId, mcpConnectionNodeId, "credential")`), and returns a ready-to-use
- * tool map with wrapped execute callbacks for telemetry and 403 detection.
- * Core-nodes imports this interface so AIAgentNode can inject it without
- * depending on the host.
- */
 export interface AgentMcpIntegration {
-  /**
-   * Look up the credential binding per server, validate scopes, open pool
-   * connections, and return a tool map keyed by serverId. Each tool's
-   * execute callback includes:
-   * - Telemetry child span (mcp.server_id, mcp.tool_name attributes)
-   * - 403/permission error detection → emits a NeedsReconsentEvent span event
-   *
-   * Throws `AgentBindError` on validation failures (missing server, unbound
-   * credential slot, missing credential instance, insufficient scopes).
-   */
   prepareMcpTools(args: {
     readonly workflowId: WorkflowId;
     readonly agentNodeId: NodeId;
@@ -50,15 +21,10 @@ export interface AgentMcpIntegration {
     readonly startChildSpan: (args: { readonly name: string; readonly attributes?: Record<string, string> }) => {
       readonly end: (args?: { status?: "ok" | "error"; statusMessage?: string }) => void;
     };
-    /** Per-MCP-tool-call invocation appender. Optional; when omitted the wrapper emits only telemetry spans. */
     readonly appendMcpInvocation?: (args: ConnectionInvocationAppendArgs) => Promise<void>;
-    /** Agent activation id to attach to each invocation record (used by canvas + inspector grouping). */
     readonly parentAgentActivationId?: NodeActivationId;
-    /** Per-item iteration id when the agent runs inside a per-item loop. */
     readonly iterationId?: NodeIterationId;
-    /** Item index (0-based) of the iteration that owns these tool calls. */
     readonly itemIndex?: number;
-    /** Parent invocation id when this agent is itself executing as a sub-agent. */
     readonly parentInvocationId?: ConnectionInvocationId;
   }): Promise<AgentMcpToolMap>;
 }

package/src/contracts/assertionTypes.ts

@@ -1,45 +1,18 @@
 import type { JsonValue, NodeId } from "./workflowTypes";
 
-/**
- * One assertion emitted by an assertion-emitting node (a node whose config sets
- * `emitsAssertions: true`). Each emitted item on `main` carries one of these as `item.json`.
- *
- * Pass/fail is derived from `score >= (passThreshold ?? 0.5)` — see {@link deriveAssertionPassed}.
- * The `errored` marker is for cases where the assertion code itself threw (distinct from
- * "the assertion was evaluated and the score was low") and is treated as a hard fail in rollups
- * regardless of `score`.
- */
 export interface AssertionResult {
   readonly name: string;
-  /** 0..1 score. Source of truth for pass/fail (compared against `passThreshold`). */
   readonly score: number;
-  /** 0..1 threshold for "passed". When omitted, consumers default to 0.5. */
   readonly passThreshold?: number;
-  /** True when evaluating the assertion threw — treated as fail regardless of `score`. */
   readonly errored?: true;
-  /** What the assertion expected. Free-form JSON; UIs render with a JSON viewer. */
   readonly expected?: JsonValue;
-  /** What the workflow actually produced. */
   readonly actual?: JsonValue;
-  /** Short human-readable explanation, especially for fails / errors. */
   readonly message?: string;
-  /** Bag of supplemental fields (e.g. judge prompt, judge raw response, comparison method). */
   readonly details?: Readonly<Record<string, JsonValue>>;
 }
 
-/**
- * Default {@link AssertionResult.passThreshold} when authors omit it. Boolean-style assertions
- * (assertEqual / contains / etc.) emit `score: 1` or `score: 0` so this default works for them;
- * AI-judge assertions are expected to set their own threshold.
- */
 export const DEFAULT_ASSERTION_PASS_THRESHOLD = 0.5;
 
-/**
- * Derive whether an assertion result is considered "passing" using the score-based contract:
- * `errored` always fails, otherwise `score >= (passThreshold ?? 0.5)`. This is the canonical
- * derivation — UI and rollup code should call it rather than inlining the comparison so future
- * tweaks (e.g. NaN handling) land in one place.
- */
 export function deriveAssertionPassed(result: {
   readonly score: number;
   readonly passThreshold?: number;
@@ -50,14 +23,8 @@ export function deriveAssertionPassed(result: {
   return result.score >= threshold;
 }
 
-/**
- * Provenance for a persisted {@link AssertionResult}: which node produced it and where in the
- * per-item iteration tree it landed. Filled in by the host-side persister, not the node itself.
- */
 export interface AssertionResultProvenance {
   readonly nodeId: NodeId;
-  /** Per-item iteration id when the emitting node ran inside a per-item loop. */
   readonly iterationId?: string;
-  /** Item index (0-based) within the activation that produced this assertion. */
   readonly itemIndex?: number;
 }

package/src/contracts/baseTypes.ts

@@ -1,9 +1,3 @@
-/**
- * Minimal base types that have no dependencies on other contracts.
- * Used by credentialTypes, workflowTypes, and other contract layers
- * to avoid circular dependencies.
- */
-
 export type WorkflowId = string;
 export type NodeId = string;
 export type OutputPortKey = string;

package/src/contracts/collectionTypes.ts

@@ -1,44 +1,19 @@
-/**
- * Represents a typed store for a single collection.
- * All rows include auto-managed id, created_at, and updated_at fields.
- */
 export 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.
- */
 export type CollectionsContext = Readonly<Record<string, CollectionStore>>;

package/src/contracts/credentialTypes.ts

@@ -13,22 +13,11 @@ export type CredentialFieldSchema = Readonly<{
   type: "string" | "password" | "textarea" | "json" | "boolean";
   required?: true;
   order?: number;
-  /**
-   * Where this field appears in the credential dialog. Use `"advanced"` for optional or
-   * power-user fields; they render inside a collapsible section (see `CredentialTypeDefinition.advancedSection`).
-   * Defaults to `"default"` when omitted.
-   */
   visibility?: "default" | "advanced";
   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;
 }>;
 
@@ -93,20 +82,9 @@ export type CredentialOAuth2AuthDefinition = Readonly<
     }
   | {
       kind: "oauth2";
-      /**
-       * Free-form provider identifier for telemetry, DB rows, and Better Auth provider naming.
-       * Not used for any registry lookup — URLs come from {@link authorizeUrl} / {@link tokenUrl}.
-       */
       providerId: string;
-      /**
-       * Authorization endpoint. May contain `{publicFieldKey}` placeholders that the runtime
-       * substitutes from the credential's resolved public config (URL-encoded).
-       * Example: `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize`
-       */
       authorizeUrl: string;
-      /** Token endpoint. Same templating rules as {@link authorizeUrl}. */
       tokenUrl: string;
-      /** Optional userinfo endpoint. Same templating rules as {@link authorizeUrl}. */
       userInfoUrl?: string;
       scopes: ReadonlyArray<string>;
       scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
@@ -118,11 +96,8 @@ export type CredentialOAuth2AuthDefinition = Readonly<
 export type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;
 
 export type CredentialAdvancedSectionPresentation = Readonly<{
-  /** Collapsible section title (default: "Advanced"). */
   title?: string;
-  /** Optional short helper text shown inside the section (above the fields). */
   description?: string;
-  /** When true, the advanced section starts expanded. Default: false (collapsed). */
   defaultOpen?: boolean;
 }>;
 
@@ -132,25 +107,13 @@ export type CredentialTypeDefinition = Readonly<{
   description?: string;
   publicFields?: ReadonlyArray<CredentialFieldSchema>;
   secretFields?: ReadonlyArray<CredentialFieldSchema>;
-  /**
-   * Optional labels for the collapsible block that contains every field with `visibility: "advanced"`.
-   * If omitted, the UI still shows that block with defaults (title "Advanced", collapsed).
-   */
   advancedSection?: CredentialAdvancedSectionPresentation;
   supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
   auth?: CredentialAuthDefinition;
 }>;
 
-/**
- * JSON-shaped credential field bag (public config, resolved secret material, etc.).
- */
 export 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.
- */
 export type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
   instanceId: CredentialInstanceId;
   typeId: CredentialTypeId;
@@ -162,23 +125,9 @@ export type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord
   setupStatus: CredentialSetupStatus;
   createdAt: string;
   updatedAt: string;
-  /**
-   * Pointer to where the credential material bytes live. For OSS / standalone
-   * rows this is `{source: "local", ref: instanceId}` and the bytes co-locate
-   * with the row in the workspace DB. For managed-mode rows this is
-   * `{source: "control-plane", ref: <cp_id>}` and the bytes live at CP.
-   *
-   * The seam is read through `CredentialMaterialProvider`. See
-   * `docs/design/credentials-oauth-unification.md` ("Material provider seam").
-   */
   material: Readonly<{ source: "local" | "control-plane"; ref: 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).
- */
 export type CredentialSessionFactoryArgs<
   TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord,
   TMaterial extends CredentialJsonRecord = CredentialJsonRecord,
@@ -194,15 +143,23 @@ export type CredentialSessionFactory<
   TSession = unknown,
 > = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<TSession>;
 
+export type CredentialAccessTokenSessionArgs<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> =
+  Readonly<{
+    accessToken: string;
+    grantedScopes: ReadonlyArray<string>;
+    publicConfig: TPublicConfig;
+  }>;
+
+export type CredentialAccessTokenSessionFactory<
+  TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord,
+  TSession = unknown,
+> = (args: CredentialAccessTokenSessionArgs<TPublicConfig>) => Promise<TSession>;
+
 export 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.
- */
 export type CredentialType<
   TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord,
   TMaterial extends CredentialJsonRecord = CredentialJsonRecord,
@@ -210,14 +167,10 @@ export type CredentialType<
 > = Readonly<{
   definition: CredentialTypeDefinition;
   createSession: CredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
+  createSessionFromAccessToken?: CredentialAccessTokenSessionFactory<TPublicConfig, 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.
- */
 export type AnyCredentialType = CredentialType<any, any, unknown>;
 
 export interface CredentialSessionService {

package/src/contracts/deploymentManifestTypes.ts

@@ -0,0 +1,158 @@
+import { randomUUID } from "node:crypto";
+
+import type { NodeId, WorkflowId } from "./baseTypes";
+import type { CredentialRequirement } from "./credentialTypes";
+import type { PersistedWorkflowSnapshot } from "./runTypes";
+import type { JsonObject, NodeDefinition, PollingTriggerConfig } from "./workflowTypes";
+import type { WorkflowDefinition } from "../types";
+import { AgentConfigInspector } from "../ai/AgentConfigInspectorFactory";
+import { PersistedWorkflowTokenRegistry } from "../workflowSnapshots/PersistedWorkflowTokenRegistry";
+import { WorkflowSnapshotCodec } from "../workflowSnapshots/WorkflowSnapshotCodec";
+
+export const DEPLOYMENT_MANIFEST_SCHEMA_VERSION = 2 as const;
+
+export type DeploymentManifestSchemaVersion = typeof DEPLOYMENT_MANIFEST_SCHEMA_VERSION;
+
+export type ManifestTriggerConfig = Readonly<{
+  nodeId: NodeId;
+  triggerKind: "live" | "test";
+  config: JsonObject;
+  pollIntervalMs?: number;
+  nodeTypeId?: string;
+}>;
+
+export type ManifestNodeCredentialShape = Readonly<{
+  nodeId: NodeId;
+  requirements: ReadonlyArray<CredentialRequirement>;
+}>;
+
+export type WorkflowDeploymentManifest<TCanvas = JsonObject> = Readonly<{
+  manifestId: string;
+  schemaVersion: DeploymentManifestSchemaVersion;
+  workflowId: WorkflowId;
+  canvas: TCanvas;
+  snapshot: PersistedWorkflowSnapshot;
+  triggers: ReadonlyArray<ManifestTriggerConfig>;
+  credentialShapes: ReadonlyArray<ManifestNodeCredentialShape>;
+}>;
+
+export function serializeManifest<TCanvas>(manifest: WorkflowDeploymentManifest<TCanvas>): string {
+  return JSON.stringify(manifest);
+}
+
+export function deserializeManifest<TCanvas = JsonObject>(raw: string): WorkflowDeploymentManifest<TCanvas> {
+  return JSON.parse(raw) as WorkflowDeploymentManifest<TCanvas>;
+}
+
+export type ManifestCanvasNode = Readonly<{
+  id: NodeId;
+  kind: string;
+  name: string | undefined;
+  type?: string;
+  role?: string;
+  triggerKind?: "live" | "test";
+  declaredOutputPorts?: ReadonlyArray<string>;
+  declaredInputPorts?: ReadonlyArray<string>;
+}>;
+
+export type ManifestCanvas = Readonly<{
+  id: WorkflowId;
+  name: string;
+  nodes: ReadonlyArray<ManifestCanvasNode>;
+  edges: WorkflowDefinition["edges"];
+}>;
+
+type TriggerNodeConfigShape = Readonly<{ triggerKind?: "live" | "test" }>;
+
+function isPollingTriggerConfig(config: unknown): config is PollingTriggerConfig {
+  return typeof (config as PollingTriggerConfig).getTriggerPollConfig === "function";
+}
+
+function resolveNodeTypeName(node: NodeDefinition): string {
+  const configToken = node.config?.type as Readonly<{ name?: unknown }> | undefined;
+  if (typeof configToken?.name === "string" && configToken.name) {
+    return configToken.name;
+  }
+  const nodeToken = node.type as Readonly<{ name?: unknown }> | undefined;
+  if (typeof nodeToken?.name === "string" && nodeToken.name) {
+    return nodeToken.name;
+  }
+  return "Node";
+}
+
+function resolveCanvasNode(node: NodeDefinition): ManifestCanvasNode {
+  const config = node.config;
+  const type = resolveNodeTypeName(node);
+  const role = AgentConfigInspector.isAgentNodeConfig(config) ? "agent" : "workflowNode";
+  const triggerKind = node.kind === "trigger" ? ((config as TriggerNodeConfigShape).triggerKind ?? "live") : undefined;
+  const c = config as {
+    declaredOutputPorts?: readonly string[];
+    declaredInputPorts?: readonly string[];
+  };
+  return {
+    id: node.id,
+    kind: node.kind,
+    name: node.name ?? config?.name,
+    type,
+    role,
+    ...(triggerKind !== undefined && { triggerKind }),
+    ...(c.declaredOutputPorts !== undefined && { declaredOutputPorts: c.declaredOutputPorts }),
+    ...(c.declaredInputPorts !== undefined && { declaredInputPorts: c.declaredInputPorts }),
+  };
+}
+
+export function emitWorkflowManifest(workflow: WorkflowDefinition): WorkflowDeploymentManifest<ManifestCanvas> {
+  const registry = new PersistedWorkflowTokenRegistry();
+  registry.registerFromWorkflows([workflow]);
+  const codec = new WorkflowSnapshotCodec(registry);
+  const snapshot = codec.create(workflow);
+
+  const canvas = {
+    id: workflow.id,
+    name: workflow.name,
+    nodes: workflow.nodes.map(resolveCanvasNode),
+    edges: workflow.edges,
+  };
+
+  const triggers: ManifestTriggerConfig[] = workflow.nodes
+    .filter((n) => n.kind === "trigger")
+    .map((n) => {
+      const config = n.config;
+      const cfg = config as unknown as Record<string, unknown>;
+      const triggerKind = (config as TriggerNodeConfigShape).triggerKind ?? "live";
+      const pollCfg = isPollingTriggerConfig(config) ? config.getTriggerPollConfig() : undefined;
+      const endpointKey = typeof cfg["endpointKey"] === "string" ? cfg["endpointKey"] : undefined;
+      const methods = Array.isArray(cfg["methods"]) ? (cfg["methods"] as string[]) : undefined;
+      const webhookFields: JsonObject =
+        endpointKey !== undefined && methods !== undefined ? { endpointKey, methods } : {};
+      const nodeTypeId = registry.getTokenId(config.type) ?? undefined;
+      const entry: ManifestTriggerConfig = {
+        nodeId: n.id,
+        triggerKind,
+        config: pollCfg !== undefined ? pollCfg.config : webhookFields,
+        nodeTypeId,
+      };
+      if (pollCfg?.pollIntervalMs !== undefined) {
+        return { ...entry, pollIntervalMs: pollCfg.pollIntervalMs };
+      }
+      return entry;
+    });
+
+  const credentialShapes: ManifestNodeCredentialShape[] = workflow.nodes
+    .map((n) => {
+      const requirements = n.config.getCredentialRequirements?.();
+      if (!requirements || requirements.length === 0) return null;
+      return { nodeId: n.id, requirements } satisfies ManifestNodeCredentialShape;
+    })
+    .filter((s): s is ManifestNodeCredentialShape => s !== null);
+
+  return {
+    manifestId: randomUUID(),
+    schemaVersion: DEPLOYMENT_MANIFEST_SCHEMA_VERSION,
+    workflowId: workflow.id,
+    canvas,
+    snapshot,
+    triggers,
+    credentialShapes,
+  };
+}

package/src/contracts/dispatchTypes.ts

@@ -0,0 +1,29 @@
+import type { BinaryAttachment, JsonValue, RunId, WorkflowId } from "./workflowTypes";
+import type { NodeId } from "./baseTypes";
+
+export type WorkspaceId = string;
+
+export type DispatchBinaryRef = BinaryAttachment;
+
+export interface DispatchItemMeta {
+  readonly id: string;
+  readonly json?: JsonValue;
+  readonly binary?: Readonly<Record<string, DispatchBinaryRef>>;
+}
+
+export interface WorkflowDispatch {
+  readonly runId: RunId;
+  readonly workspaceId: WorkspaceId;
+  readonly workflowId: WorkflowId;
+  readonly triggerNodeId: NodeId;
+  readonly items: ReadonlyArray<DispatchItemMeta>;
+  readonly triggerContext: JsonValue;
+}
+
+export function serializeDispatch(dispatch: WorkflowDispatch): string {
+  return JSON.stringify(dispatch);
+}
+
+export function deserializeDispatch(raw: string): WorkflowDispatch {
+  return JSON.parse(raw) as WorkflowDispatch;
+}