@codemation/core 0.13.2 → 0.15.0

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;
+}

package/src/contracts/executionPersistenceContracts.ts

@@ -7,16 +7,12 @@ import type {
   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";
@@ -29,10 +25,6 @@ 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;
@@ -51,14 +43,10 @@ export interface PersistedRunWorkItemRecord {
   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;
@@ -72,9 +60,6 @@ export interface ExecutionPayloadPolicyFields {
   readonly outputTruncated?: boolean;
 }
 
-/**
- * One persisted execution row (workflow node activation or connection invocation).
- */
 export interface PersistedExecutionInstanceRecord {
   readonly instanceId: ExecutionInstanceId;
   readonly runId: RunId;
@@ -110,9 +95,6 @@ export interface PersistedExecutionInstanceRecord {
   readonly payloadPolicy?: ExecutionPayloadPolicyFields;
 }
 
-/**
- * Cached slot projection for planner/debugger/UI (not canonical history).
- */
 export interface RunSlotProjectionState {
   readonly runId: RunId;
   readonly workflowId: WorkflowId;
@@ -151,12 +133,6 @@ export interface WorkflowRunDetailDto {
   readonly iterations?: ReadonlyArray<RunIterationDto>;
 }
 
-/**
- * Per-item iteration projected from connection invocations and node activations.
- *
- * One iteration = one item processed by an agent within an activation. Multiple invocations
- * (LLM rounds, tool calls) belonging to the same iteration share the iterationId.
- */
 export interface RunIterationDto {
   readonly iterationId: string;
   readonly agentNodeId: NodeId;
@@ -168,9 +144,7 @@ export interface RunIterationDto {
   readonly finishedAt?: string;
   readonly invocationIds: ReadonlyArray<string>;
   readonly parentInvocationId?: string;
-  /** Estimated cost rolled up from telemetry cost metric points, keyed by ISO currency code (e.g. "USD"). Values are minor units (cents-of-cents per the metric's `cost.currency_scale`). */
   readonly estimatedCostMinorByCurrency?: Readonly<Record<string, number>>;
-  /** Currency scale (denominator) per currency, when present on the metric points. Joined with `estimatedCostMinorByCurrency` to format human-readable amounts. */
   readonly estimatedCostCurrencyScaleByCurrency?: Readonly<Record<string, number>>;
 }
 
@@ -202,16 +176,9 @@ export interface ExecutionInstanceDto {
   readonly inputJson?: JsonValue;
   readonly outputJson?: JsonValue;
   readonly error?: Readonly<NodeExecutionError>;
-  /** Per-item iteration that produced this instance. Set on connectionInvocation rows produced inside per-item runnable loops. */
   readonly iterationId?: string;
-  /** Item index (0-based) of the iteration. */
   readonly itemIndex?: number;
-  /** Parent invocation id when this instance was emitted by a sub-agent triggered by an outer LLM/tool call. */
   readonly parentInvocationId?: string;
-  /**
-   * When this instance is a SubWorkflow node activation, the run id of the child run it spawned.
-   * Used by the UI to deep-link directly to the child execution.
-   */
   readonly childRunId?: string;
 }
 

package/src/contracts/hitlSeamTypes.ts

@@ -1,18 +1,10 @@
 import type { TypeToken } from "../di";
 
-/**
- * Seam interfaces for HITL collaborators that are implemented in `@codemation/host`
- * and injected into `NodeSuspensionHandler` at runtime. Core defines the interface only —
- * no HTTP, vendor SDK, or Prisma dependencies here.
- */
-
-/** Signs and hashes a HITL resume token. Core only needs the sign and hash operations. */
 export interface HitlResumeTokenSignerSeam {
   sign(args: { taskId: string; expiresAt: Date; schemaHash: string }): string;
   hashToken(token: string): string;
 }
 
-/** Schedules a delayed BullMQ job that drives the timeout path. */
 export interface HitlTimeoutJobSchedulerSeam {
   enqueueTimeoutJob(args: { taskId: string; expiresAt: Date }): Promise<void>;
 }
@@ -25,10 +17,4 @@ export const HitlTimeoutJobSchedulerToken = Symbol.for("codemation.core.HitlTime
   HitlTimeoutJobSchedulerSeam | undefined
 >;
 
-/**
- * Optional workspace ID injected into NodeSuspensionHandler in managed mode (T7 security fix).
- * Allows the handler to stamp the workspaceId on each HumanTaskRecord so HitlCallbackHandler
- * can assert workspace identity independently of the HMAC middleware.
- * Not registered in non-managed mode; NodeSuspensionHandler defaults to null.
- */
 export const HitlWorkspaceIdToken = Symbol.for("codemation.core.HitlWorkspaceId") as TypeToken<string | undefined>;

package/src/contracts/humanTaskStoreTypes.ts

@@ -4,7 +4,6 @@ import type { JsonValue } from "./workflowTypes";
 
 export type HumanTaskStatus = "pending" | "decided" | "timed_out" | "auto_accepted" | "cancelled";
 
-/** Persisted record for a single HITL task instance. */
 export interface HumanTaskRecord {
   readonly id: string;
   readonly runId: string;
@@ -34,7 +33,6 @@ export interface HumanTaskStore {
   findById(taskId: string): Promise<HumanTaskRecord | undefined>;
   findByResumeTokenHash(tokenHash: string): Promise<HumanTaskRecord | undefined>;
   findPendingForWorkspace(workspaceId: string): Promise<ReadonlyArray<HumanTaskRecord>>;
-  /** Returns all pending tasks regardless of workspace. Used by the local dev inbox (non-managed mode). */
   findAllPending(): Promise<ReadonlyArray<HumanTaskRecord>>;
   markDecided(args: { taskId: string; decision: JsonValue; decidedBy: HumanTaskActor; decidedAt: Date }): Promise<void>;
   markTimedOut(taskId: string): Promise<void>;

package/src/contracts/inboxChannelTypes.ts

@@ -2,10 +2,6 @@ import type { TypeToken } from "../di";
 import type { HumanTaskActor, HumanTaskHandle, HumanTaskSubject } from "./runtimeTypes";
 import type { Item } from "./workflowTypes";
 
-/**
- * A single inbox delivery channel.
- * Implementations: `LocalInboxChannel`, `ControlPlaneInboxChannel`.
- */
 export interface InboxChannel {
   readonly kind: "local" | "control-plane-inbox";
   deliver(args: InboxDeliverArgs): Promise<InboxDelivery>;
@@ -18,7 +14,6 @@ export type InboxDeliverArgs = Readonly<{
   subject: HumanTaskSubject;
   priority: "low" | "normal" | "high";
   item: Item;
-  /** Present in managed mode (from `PairingConfig.workspaceId`). */
   workspaceId?: string;
 }>;
 
@@ -37,10 +32,6 @@ export type InboxOnTimeoutArgs = Readonly<{
   policy: "halt" | "auto-accept";
 }>;
 
-/**
- * Resolves the correct `InboxChannel` for the current deployment mode
- * (local dev vs. managed/CP). Implemented in `@codemation/host`.
- */
 export interface InboxChannelResolverSeam {
   resolve(): { channel: InboxChannel; workspaceId?: string };
 }

package/src/contracts/index.ts

@@ -1,5 +1,7 @@
 export * from "./AgentBindError";
+export * from "./dispatchTypes";
 export * from "./agentMcpTypes";
+export * from "./deploymentManifestTypes";
 export * from "./hitlSeamTypes";
 export * from "./humanTaskStoreTypes";
 export * from "./inboxChannelTypes";
@@ -15,6 +17,7 @@ export * from "./itemMeta";
 export * from "./params";
 export * from "./itemExpr";
 export * from "./runtimeTypes";
+export * from "./triggerInvokerTypes";
 export * from "./telemetryTypes";
 export * from "./testTriggerTypes";
 export * from "./runFinishedAtFactory";