@codemation/core 0.11.0 → 0.12.0

package/src/authoring/defineHumanApprovalNode.types.ts

@@ -0,0 +1,379 @@
+import type {
+  Duration,
+  ExecutionContext,
+  HumanTaskActor,
+  HumanTaskHandle,
+  HumanTaskSubject,
+  NodeExecutionContext,
+  ResumeContext,
+} from "../contracts/runtimeTypes";
+import type { Item, JsonValue, NodeInspectorSummaryRow, NodeConfigBase } from "../contracts/workflowTypes";
+import type { CredentialJsonRecord } from "../contracts/credentialTypes";
+import type { ZodObject, ZodType } from "zod";
+import type { DefinedNodeCredentialBindings } from "./defineNode.types";
+import { SuspensionRequest } from "../contracts/runtimeTypes";
+import { defineNode } from "./defineNode.types";
+import type { DefinedNode } from "./defineNode.types";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Decision shape merged into `item.json` after a HITL approval task resolves.
+ *
+ * - `"approved"` / `"rejected"` — from a human decision (uses `approvedPredicate`).
+ * - `"timed-out"` — timeout fired with `onTimeout: "halt"`.
+ * - `"auto-accepted"` — timeout fired with `onTimeout: "auto-accept"`.
+ */
+export interface HumanApprovalDecisionResult {
+  readonly status: "approved" | "rejected" | "timed-out" | "auto-accepted";
+  /** Identity of the person who decided; absent for automated outcomes. */
+  readonly actor?: HumanTaskActor;
+  /** ISO 8601 timestamp of the decision. */
+  readonly decidedAt?: Date;
+  /** Optional free-text note from the reviewer. */
+  readonly note?: string;
+  /**
+   * Full raw decision payload (only present for `"approved"` / `"rejected"`).
+   * Shape is determined by the channel's `decisionSchema`.
+   */
+  readonly payload?: Record<string, unknown>;
+}
+
+/**
+ * Output item shape emitted by a `defineHumanApprovalNode`-based node.
+ * Original `item.json` fields are preserved and `decision` is merged in.
+ * If the input `item.json` already contained a `decision` key it is **overwritten**.
+ */
+export type HumanApprovalOutputJson<TInputJson extends Record<string, unknown>> = TInputJson & {
+  readonly decision: HumanApprovalDecisionResult;
+};
+
+/**
+ * Extends {@link DefinedNode} with the `humanApprovalToolBehavior` metadata marker.
+ * Story 10 reads this field when attaching the node as an agent tool.
+ */
+export interface DefinedHumanApprovalNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson extends Record<string, unknown>,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> extends DefinedNode<TKey, TConfig, TInputJson, HumanApprovalOutputJson<TInputJson>, TBindings> {
+  /**
+   * Behavior hint consumed by the agent runtime (story 10) when this node is attached as a tool.
+   * `"return"` (default) — return the rejection to the agent as a tool result.
+   * `"halt"` — halt the agent run on rejection.
+   *
+   * Standalone DSL usage ignores this field.
+   */
+  readonly humanApprovalToolBehavior: { onRejected: "return" | "halt" };
+}
+
+// ---------------------------------------------------------------------------
+// isHumanApprovalNode predicate
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when `node` was created by {@link defineHumanApprovalNode}.
+ * Uses the `humanApprovalToolBehavior` typed field as the discriminant.
+ */
+export function isHumanApprovalNode(
+  node: unknown,
+): node is DefinedHumanApprovalNode<string, Record<string, unknown>, Record<string, unknown>, undefined> {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    "humanApprovalToolBehavior" in node &&
+    typeof (node as { humanApprovalToolBehavior: unknown }).humanApprovalToolBehavior === "object"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// defineHumanApprovalNode
+// ---------------------------------------------------------------------------
+
+/**
+ * Authoring helper that compiles a HITL approval channel down to a regular
+ * {@link defineNode}-backed node with `SuspensionRequest` semantics.
+ *
+ * **Fast-forward decision semantics:**
+ * - On the first `execute` call (no `ctx.resumeContext`): throws a `SuspensionRequest`
+ *   that calls the author's `deliver`. The engine persists the suspension and continues.
+ * - On resume (`ctx.resumeContext` set): calls `onDecision`/`onTimeout` as appropriate,
+ *   merges a `decision` key into `item.json`, and returns an item with the original
+ *   `binary` map passed by reference (no copy).
+ *
+ * **Output shape per item:**
+ * ```ts
+ * // Input:  { json: { invoiceId: 42 }, binary?: {...} }
+ * // Output: { json: { invoiceId: 42, decision: { status: "approved", actor, decidedAt } }, binary: <unchanged> }
+ * ```
+ * If `item.json` already has a `decision` key it is **overwritten**. Namespace as
+ * needed if your schema reserves that key for another purpose.
+ *
+ * **Predicate persistence:**
+ * The `approvedPredicate` function is NOT serialized to the suspension record (except
+ * as an audit-only string via `toString()`). On resume, the workflow definition is
+ * reloaded from code at process start and the predicate closure is rebuilt naturally.
+ * If a deploy ships a changed predicate between suspend and resume, the *new* predicate
+ * runs — document this in your runbook when the predicate carries business logic that
+ * may change across deploys.
+ *
+ * @example
+ * ```ts
+ * export const slackApprovalNode = defineHumanApprovalNode({
+ *   key: "my-plugin.slackApproval",
+ *   title: "Slack Approval",
+ *   channel: "slack",
+ *   configSchema: z.object({ channel: z.string(), message: z.string() }),
+ *   decisionSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
+ *
+ *   async deliver({ task, config, item }, ctx) {
+ *     const ts = await postSlackMessage(config.channel, `Approve? <${task.resumeUrl}>`);
+ *     return { channel: config.channel, ts };
+ *   },
+ *
+ *   async onDecision({ decision, actor, delivery }, ctx) {
+ *     await updateSlackMessage(delivery.channel, delivery.ts, decision.approved ? "✅" : "❌");
+ *   },
+ * });
+ * ```
+ */
+export function defineHumanApprovalNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson extends Record<string, unknown>,
+  TDecision extends Record<string, unknown>,
+  TDelivery extends JsonValue,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+>(opts: {
+  key: TKey;
+  title: string;
+  description?: string;
+  icon?: string;
+  channel: string;
+
+  configSchema: ZodType<TConfig>;
+  inputSchema?: ZodType<TInputJson>;
+  decisionSchema: ZodType<TDecision>;
+  credentials?: TBindings;
+
+  /**
+   * Custom predicate that decides whether a decision counts as "approved".
+   * When omitted, the helper checks if `decisionSchema` is a Zod object with an
+   * `approved: boolean` field; if so it uses `decision.approved === true`.
+   * If neither holds, `defineHumanApprovalNode` throws at **definition time** (not runtime).
+   */
+  approvedPredicate?: (decision: TDecision) => boolean;
+  /** Default suspension timeout. Defaults to `"24h"`. */
+  defaultTimeout?: Duration;
+  /** What to do when the task times out. Defaults to `"halt"`. */
+  defaultOnTimeout?: "halt" | "auto-accept";
+
+  inspectorSummary?: (config: TConfig) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
+
+  deliver: (
+    args: {
+      task: HumanTaskHandle;
+      config: TConfig;
+      input: TInputJson;
+      item: Item;
+    },
+    ctx: ExecutionContext,
+  ) => Promise<TDelivery>;
+
+  onDecision?: (
+    args: {
+      decision: TDecision;
+      actor: HumanTaskActor;
+      task: HumanTaskHandle;
+      delivery: TDelivery;
+      item: Item;
+    },
+    ctx: ExecutionContext,
+  ) => Promise<void>;
+
+  onTimeout?: (
+    args: {
+      task: HumanTaskHandle;
+      delivery: TDelivery;
+      item: Item;
+      policy: "halt" | "auto-accept";
+    },
+    ctx: ExecutionContext,
+  ) => Promise<void>;
+}): DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings> {
+  // Resolve the approved predicate at definition time so we throw early when
+  // the schema is ambiguous.
+  const resolvedPredicate = resolveApprovedPredicate(opts.decisionSchema, opts.approvedPredicate);
+
+  const timeout = opts.defaultTimeout ?? "24h";
+  const onTimeout = opts.defaultOnTimeout ?? "halt";
+
+  // TOutputJson is `unknown` here because `execute` returns an Item-shaped object
+  // that the engine's NodeOutputNormalizer converts to the proper output. The public
+  // interface's DefinedHumanApprovalNode carries the correct output type for DSL use.
+  const inner = defineNode<TKey, TConfig, TInputJson, unknown, TBindings>({
+    key: opts.key,
+    title: opts.title,
+    description: opts.description,
+    icon: opts.icon,
+    configSchema: opts.configSchema,
+    inputSchema: opts.inputSchema,
+    credentials: opts.credentials,
+    inspectorSummary: opts.inspectorSummary ? ({ config }) => opts.inspectorSummary!(config) : undefined,
+
+    async execute(args, { config, execution: ctx }) {
+      if (!ctx.resumeContext) {
+        // First pass — suspend.
+        const subject = buildSubject(opts.title, args.item, ctx);
+        throw new SuspensionRequest({
+          decisionSchema: opts.decisionSchema,
+          timeout,
+          onTimeout,
+          subject,
+          metadata: {
+            channel: opts.channel,
+            nodeKey: opts.key,
+            // Stored for audit only; never re-evaluated. See JSDoc on defineHumanApprovalNode.
+            approvedPredicateSource: opts.approvedPredicate?.toString() ?? null,
+          },
+          deliver: (handle: HumanTaskHandle) =>
+            opts.deliver(
+              {
+                task: handle,
+                config,
+                input: args.input as TInputJson,
+                item: args.item,
+              },
+              ctx,
+            ),
+        });
+      }
+
+      // Resume pass.
+      return await handleResume(
+        args.item,
+        ctx.resumeContext,
+        opts.decisionSchema,
+        resolvedPredicate,
+        opts.onDecision,
+        opts.onTimeout,
+        ctx,
+      );
+    },
+  });
+
+  return Object.assign(inner, {
+    humanApprovalToolBehavior: { onRejected: "return" as const },
+  }) as unknown as DefinedHumanApprovalNode<TKey, TConfig, TInputJson, TBindings>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (module-private)
+// ---------------------------------------------------------------------------
+
+function resolveApprovedPredicate<TDecision extends Record<string, unknown>>(
+  schema: ZodType<TDecision>,
+  predicate: ((d: TDecision) => boolean) | undefined,
+): (d: TDecision) => boolean {
+  if (predicate) {
+    return predicate;
+  }
+  // Zod 4: ZodObject exposes `.shape` directly as an object (not a function).
+  const shape = (schema as unknown as ZodObject<Record<string, ZodType>>).shape;
+  if (shape && typeof shape === "object" && "approved" in shape) {
+    return (d) => (d as { approved?: unknown }).approved === true;
+  }
+  throw new Error(
+    `defineHumanApprovalNode: decisionSchema has no "approved" field and no approvedPredicate was provided. ` +
+      `Either add { approved: z.boolean() } to the decision schema or supply approvedPredicate explicitly.`,
+  );
+}
+
+function buildSubject(title: string, item: Item, ctx: NodeExecutionContext<NodeConfigBase>): HumanTaskSubject {
+  return {
+    title,
+    summary: "",
+    attributes: {
+      workflowId: ctx.workflowId,
+      nodeId: ctx.nodeId,
+      item: item.json as JsonValue,
+    },
+  };
+}
+
+function mergeDecision(
+  item: Item,
+  decision: HumanApprovalDecisionResult,
+): { json: Record<string, unknown>; binary: Item["binary"]; meta: Item["meta"] } {
+  return {
+    json: { ...(item.json as Record<string, unknown>), decision },
+    // binary is passed by reference — no copy. See defineHumanApprovalNode JSDoc.
+    binary: item.binary,
+    meta: item.meta,
+  };
+}
+
+async function handleResume<TDecision extends Record<string, unknown>, TDelivery extends JsonValue>(
+  item: Item,
+  resumeContext: ResumeContext,
+  decisionSchema: ZodType<TDecision>,
+  resolvedPredicate: (d: TDecision) => boolean,
+  onDecision:
+    | ((
+        args: {
+          decision: TDecision;
+          actor: HumanTaskActor;
+          task: HumanTaskHandle;
+          delivery: TDelivery;
+          item: Item;
+        },
+        ctx: ExecutionContext,
+      ) => Promise<void>)
+    | undefined,
+  onTimeoutCb:
+    | ((
+        args: {
+          task: HumanTaskHandle;
+          delivery: TDelivery;
+          item: Item;
+          policy: "halt" | "auto-accept";
+        },
+        ctx: ExecutionContext,
+      ) => Promise<void>)
+    | undefined,
+  ctx: ExecutionContext,
+): Promise<{ json: Record<string, unknown>; binary: Item["binary"]; meta: Item["meta"] }> {
+  const { decision: dec, delivery, task } = resumeContext;
+
+  if (dec.kind === "timed_out" || dec.kind === "auto_accepted") {
+    const policy: "halt" | "auto-accept" = dec.kind === "auto_accepted" ? "auto-accept" : "halt";
+    await onTimeoutCb?.({ task, delivery: delivery as TDelivery, item, policy }, ctx);
+    const status = dec.kind === "auto_accepted" ? "auto-accepted" : "timed-out";
+    return mergeDecision(item, { status, decidedAt: dec.at });
+  }
+
+  // dec.kind === "decided"
+  const parsed = decisionSchema.parse(dec.value);
+  await onDecision?.(
+    {
+      decision: parsed,
+      actor: dec.actor,
+      task,
+      delivery: delivery as TDelivery,
+      item,
+    },
+    ctx,
+  );
+
+  const isApproved = resolvedPredicate(parsed);
+  return mergeDecision(item, {
+    status: isApproved ? "approved" : "rejected",
+    actor: dec.actor,
+    decidedAt: dec.decidedAt,
+    note: (parsed as { note?: string }).note,
+    payload: parsed,
+  });
+}

package/src/authoring/index.ts

@@ -11,6 +11,12 @@ export type {
   DefineNodeOptions,
 } from "./defineNode.types";
 export { defineBatchNode, defineNode } from "./defineNode.types";
+export type {
+  DefinedHumanApprovalNode,
+  HumanApprovalDecisionResult,
+  HumanApprovalOutputJson,
+} from "./defineHumanApprovalNode.types";
+export { defineHumanApprovalNode, isHumanApprovalNode } from "./defineHumanApprovalNode.types";
 export type { DefineCredentialOptions } from "./defineCredential.types";
 export { defineCredential } from "./defineCredential.types";
 export { callableTool } from "./callableTool.types";

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -13,6 +13,13 @@ import {
   NodeOutputNormalizer,
   RunnableOutputBehaviorResolver,
 } from "../../execution";
+import { NodeSuspensionHandler } from "../../execution/NodeSuspensionHandler";
+import { HumanTaskStoreToken } from "../../contracts/humanTaskStoreTypes";
+import {
+  HitlResumeTokenSignerToken,
+  HitlTimeoutJobSchedulerToken,
+  HitlWorkspaceIdToken,
+} from "../../contracts/hitlSeamTypes";
 import {
   EngineFactory,
   EngineWorkflowRunnerServiceFactory,
@@ -119,12 +126,34 @@ export class EngineRuntimeRegistrar {
         const retryRunner = dependencyContainer
           .resolve(InProcessRetryRunnerFactory)
           .create(dependencyContainer.resolve(DefaultAsyncSleeper));
+        const workflowExecutionRepository = dependencyContainer.resolve(CoreTokens.WorkflowExecutionRepository);
+        const humanTaskStore = dependencyContainer.isRegistered(HumanTaskStoreToken, true)
+          ? dependencyContainer.resolve(HumanTaskStoreToken)
+          : undefined;
+        const tokenSigner = dependencyContainer.isRegistered(HitlResumeTokenSignerToken, true)
+          ? dependencyContainer.resolve(HitlResumeTokenSignerToken)
+          : undefined;
+        const timeoutScheduler = dependencyContainer.isRegistered(HitlTimeoutJobSchedulerToken, true)
+          ? dependencyContainer.resolve(HitlTimeoutJobSchedulerToken)
+          : undefined;
+        const workspaceId = dependencyContainer.isRegistered(HitlWorkspaceIdToken, true)
+          ? dependencyContainer.resolve(HitlWorkspaceIdToken)
+          : undefined;
+        const suspensionHandler = new NodeSuspensionHandler(
+          workflowExecutionRepository,
+          humanTaskStore ?? undefined,
+          tokenSigner ?? undefined,
+          timeoutScheduler ?? undefined,
+          workspaceId ?? undefined,
+        );
         return dependencyContainer
           .resolve(NodeExecutorFactory)
           .create(
             dependencyContainer.resolve(CoreTokens.WorkflowNodeInstanceFactory),
             retryRunner,
             dependencyContainer.resolve(RunnableOutputBehaviorResolver),
+            suspensionHandler,
+            (runId) => workflowExecutionRepository.load(runId),
           );
       }),
     });

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -19,4 +19,14 @@ export class CodemationTelemetryAttributeNames {
   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/credentialTypes.ts

@@ -162,6 +162,16 @@ 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 }>;
 }>;
 
 /**

package/src/contracts/hitlSeamTypes.ts

@@ -0,0 +1,34 @@
+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>;
+}
+
+export const HitlResumeTokenSignerToken = Symbol.for("codemation.core.HitlResumeTokenSigner") as TypeToken<
+  HitlResumeTokenSignerSeam | undefined
+>;
+
+export const HitlTimeoutJobSchedulerToken = Symbol.for("codemation.core.HitlTimeoutJobScheduler") as TypeToken<
+  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

@@ -0,0 +1,48 @@
+import type { TypeToken } from "../di";
+import type { HumanTaskActor, HumanTaskSubject } from "./runtimeTypes";
+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;
+  readonly workflowId: string;
+  readonly workspaceId?: string;
+  readonly nodeId: string;
+  readonly activationId: string;
+  readonly itemIndex: number;
+  readonly status: HumanTaskStatus;
+  readonly channel: string;
+  readonly subject: HumanTaskSubject;
+  readonly metadata: Record<string, JsonValue>;
+  readonly decisionSchemaJson: string;
+  readonly decisionSchemaHash: string;
+  readonly onTimeout: "halt" | "auto-accept";
+  readonly deliveryRef?: JsonValue;
+  readonly decision?: JsonValue;
+  readonly decidedAt?: Date;
+  readonly decidedBy?: HumanTaskActor;
+  readonly resumeTokenHash: string;
+  readonly expiresAt: Date;
+  readonly createdAt: Date;
+}
+
+export interface HumanTaskStore {
+  create(record: HumanTaskRecord): Promise<void>;
+  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>;
+  markAutoAccepted(taskId: string): Promise<void>;
+  markCancelled(taskId: string): Promise<void>;
+  cancelPendingForRun(runId: string): Promise<void>;
+}
+
+export const HumanTaskStoreToken = Symbol.for("codemation.core.HumanTaskStore") as TypeToken<
+  HumanTaskStore | undefined
+>;

package/src/contracts/inboxChannelTypes.ts

@@ -0,0 +1,58 @@
+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>;
+  updateOnDecision?(args: InboxOnDecisionArgs): Promise<void>;
+  updateOnTimeout?(args: InboxOnTimeoutArgs): Promise<void>;
+}
+
+export type InboxDeliverArgs = Readonly<{
+  task: HumanTaskHandle;
+  subject: HumanTaskSubject;
+  priority: "low" | "normal" | "high";
+  item: Item;
+  /** Present in managed mode (from `PairingConfig.workspaceId`). */
+  workspaceId?: string;
+}>;
+
+export type InboxDelivery =
+  | { kind: "local"; inboxItemId: string }
+  | { kind: "cp"; inboxItemId: string; workspaceId: string };
+
+export type InboxOnDecisionArgs = Readonly<{
+  delivery: InboxDelivery;
+  decision: { approved: boolean; note?: string };
+  actor: HumanTaskActor;
+}>;
+
+export type InboxOnTimeoutArgs = Readonly<{
+  delivery: InboxDelivery;
+  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 };
+}
+
+export const InboxChannelResolverToken = Symbol.for("codemation.core.InboxChannelResolver") as TypeToken<
+  InboxChannelResolverSeam | undefined
+>;
+
+export const LocalInboxChannelToken = Symbol.for("codemation.core.LocalInboxChannel") as TypeToken<
+  InboxChannel | undefined
+>;
+
+export const ControlPlaneInboxChannelToken = Symbol.for("codemation.core.ControlPlaneInboxChannel") as TypeToken<
+  InboxChannel | undefined
+>;

package/src/contracts/index.ts

@@ -1,5 +1,8 @@
 export * from "./AgentBindError";
 export * from "./agentMcpTypes";
+export * from "./hitlSeamTypes";
+export * from "./humanTaskStoreTypes";
+export * from "./inboxChannelTypes";
 export * from "./NoOpAgentMcpIntegration";
 export * from "./baseTypes";
 export * from "./assertionTypes";