@xemahq/kernel-contracts 0.41.0 → 0.43.0

package/src/workflow/lib/enums.ts

@@ -263,6 +263,14 @@ export enum BuiltInActionId {
   HTTP = 'xema/http',
   WAIT = 'xema/wait',
   EMIT_ARTIFACT = 'xema/emit-artifact',
+  /**
+   * Pull a declared external ingestion source into its local catalog — the
+   * generic runtime counterpart of a `ContributionKind.IngestionSource`
+   * declaration. Any sub-app that materializes an external dataset on a cadence
+   * dispatches this action; the caller resolves which source to pull. The
+   * implementation ships later in workflow-runtime-worker.
+   */
+  INGEST_SOURCE = 'xema/ingest-source',
   ENDPOINT_FETCH = 'xema/endpoint-fetch',
   SCM_POST_REVIEW = 'software-dev/scm-post-review',
   DISPATCH_WORKFLOW = 'xema/dispatch-workflow',

package/src/workflow/lib/model-ref.ts

@@ -64,6 +64,51 @@ export const ModelClassSchema = z.enum(
   MODEL_CLASS_VALUES as readonly [ModelClass, ...ModelClass[]],
 );
 
+/**
+ * A model's INTRINSIC capability / modality — what a concrete model can do
+ * regardless of which routing tier ({@link ModelClass}) selected it. The
+ * SINGLE source of truth for the closed set
+ * `vision | long_context | reasoning | function_calling | audio | embedding`.
+ *
+ * Consumed as a first-class dimension by the Model Resolution Matrix
+ * (`ResolutionDimension.ModelCapability` in `@xemahq/kernel-contracts/agent-composition`),
+ * so an org can route "any invocation that needs vision" to a capable model
+ * without pinning a provider. Domain-agnostic: describes the model, never a
+ * business use-case.
+ */
+export enum ModelCapability {
+  /** Accepts image input (multimodal vision). */
+  VISION = 'vision',
+  /** Supports an extended context window beyond the baseline tier. */
+  LONG_CONTEXT = 'long_context',
+  /** Exposes explicit step-by-step / extended-thinking reasoning. */
+  REASONING = 'reasoning',
+  /** Supports structured tool / function calling. */
+  FUNCTION_CALLING = 'function_calling',
+  /** Accepts or produces audio. */
+  AUDIO = 'audio',
+  /** Produces embedding vectors (retrieval / similarity). */
+  EMBEDDING = 'embedding',
+}
+
+export const MODEL_CAPABILITY_VALUES: readonly ModelCapability[] = [
+  ModelCapability.VISION,
+  ModelCapability.LONG_CONTEXT,
+  ModelCapability.REASONING,
+  ModelCapability.FUNCTION_CALLING,
+  ModelCapability.AUDIO,
+  ModelCapability.EMBEDDING,
+];
+
+/**
+ * Zod schema for {@link ModelCapability}. Built from the enum so the literal
+ * list lives in exactly one place. Use this in any YAML/wire schema that
+ * needs to validate a model-capability field.
+ */
+export const ModelCapabilitySchema = z.enum(
+  MODEL_CAPABILITY_VALUES as readonly [ModelCapability, ...ModelCapability[]],
+);
+
 export enum ModelRefKind {
   CONCRETE = 'concrete',
   STRATEGY = 'strategy',

package/src/workflow/lib/workflow-control.ts

@@ -0,0 +1,234 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Governed Workflow-Control Contracts ──
+//
+// Wire contracts for the least-privilege "workflow-control" surface: an
+// in-session agent invoking its OWN governing workflow run's control signals
+// (decide a decision gate, answer a pending inquiry, change run status) as a
+// governed tool.
+//
+// The agent NEVER supplies the target run or org — those are server-derived
+// from the verified session/token and injected by the mcp-gateway bridge into
+// `runId` / `orgId`. This file carries the closed action set, the settable
+// run-status subset, the typed rejection codes, the engine-internal request
+// shape, and the first-class structured accepted/rejected RESULT.
+//
+// The RESULT is deliberately a structured discriminated union (never an opaque
+// 4xx) so the calling model reads a typed outcome rather than mis-parsing an
+// HTTP error. The engine-internal control endpoint returns HTTP 200 carrying
+// this shape for every BUSINESS outcome (accepted or rejected); only genuine
+// server faults surface as non-2xx.
+//
+// Shared between workflow-engine-api (the control surface) and mcp-gateway-api
+// (the governed tool). Runtime-framework-agnostic — no NestJS, no Prisma.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import { DecisionVerdict } from '../../decision-gate/lib/decision-gate';
+
+/**
+ * The closed set of control actions an agent may take against its own
+ * governing run. Reuses the platform's existing signal/gate/inquiry
+ * mechanisms — no second control path.
+ *
+ * - `DECIDE_GATE`    — submit a decision-gate verdict (approve/reject/abstain)
+ *                      on a `DECISION_GATE` inquiry belonging to the run.
+ * - `ANSWER_INQUIRY` — submit a reply to a pending non-gate inquiry
+ *                      (`AGENT_TOOL_INQUIRY` / `REVIEW`) belonging to the run.
+ * - `SET_RUN_STATUS` — request a run-status transition (pause / resume /
+ *                      cancel) via the existing run signal.
+ * - `REFINE_PHASE`    — re-run a completed phase of the run incorporating
+ *                      `feedback`, via the `controlPhase` run signal. A
+ *                      "phase" is addressed by its `phaseKey` (the run's
+ *                      job/stage key). Only a COMPLETED phase is refinable.
+ * - `RESTART_PHASE`   — re-run a completed phase from scratch (no feedback),
+ *                      via the same `controlPhase` run signal.
+ *
+ * REFINE/RESTART are a net-new engine+worker phase-control primitive (there
+ * was no server-side phase-refinement mechanism to reuse — the run-level
+ * "redo" affordance is UI-metadata only). They route through the SAME
+ * governed control surface + the SAME run-signal plumbing as the other
+ * actions — no second control path.
+ */
+export enum WorkflowControlAction {
+  DECIDE_GATE = 'decide_gate',
+  ANSWER_INQUIRY = 'answer_inquiry',
+  SET_RUN_STATUS = 'set_run_status',
+  REFINE_PHASE = 'refine_phase',
+  RESTART_PHASE = 'restart_phase',
+}
+
+/**
+ * The settable run-status transitions an agent may request. A closed subset of
+ * `WorkflowRunStatus` — only the values that map 1:1 onto an existing run
+ * signal. The engine translates each to the corresponding signal:
+ *
+ *   PAUSED    → `pauseRun`
+ *   RUNNING   → `resumeRun`
+ *   CANCELLED → `cancelRun`
+ *
+ * Terminal statuses (succeeded/failed/…) are NOT settable — a run reaches
+ * those only through its own execution, never an agent control signal.
+ */
+export enum WorkflowRunStatusTarget {
+  PAUSED = 'paused',
+  RUNNING = 'running',
+  CANCELLED = 'cancelled',
+}
+
+/**
+ * Typed rejection codes for the structured control RESULT. Closed set — the
+ * calling model branches on these, so free-form strings are forbidden. Each
+ * corresponds to a pre-validation against live run/gate/inquiry state.
+ */
+export enum WorkflowControlRejectionCode {
+  /** The calling session is not bound to any governing workflow run. */
+  NO_GOVERNING_RUN = 'NO_GOVERNING_RUN',
+  /** The request failed contract validation before any state was touched. */
+  INVALID_REQUEST = 'INVALID_REQUEST',
+  /** The bound run does not exist for the session's org (uniform anti-probe). */
+  RUN_NOT_FOUND = 'RUN_NOT_FOUND',
+  /** The run is in a terminal state and accepts no control signal. */
+  RUN_ALREADY_TERMINAL = 'RUN_ALREADY_TERMINAL',
+  /** The run's execution rejected the requested signal. */
+  RUN_SIGNAL_REJECTED = 'RUN_SIGNAL_REJECTED',
+  /** The referenced inquiry does not exist for the session's org. */
+  INQUIRY_NOT_FOUND = 'INQUIRY_NOT_FOUND',
+  /** The referenced inquiry does not belong to the session's governing run. */
+  INQUIRY_NOT_ON_RUN = 'INQUIRY_NOT_ON_RUN',
+  /** The inquiry kind does not match the action (gate vs non-gate). */
+  INQUIRY_WRONG_KIND = 'INQUIRY_WRONG_KIND',
+  /** The gate is no longer pending and accepts no further verdicts. */
+  GATE_NOT_PENDING = 'GATE_NOT_PENDING',
+  /** The inquiry is no longer pending and accepts no further replies. */
+  INQUIRY_NOT_PENDING = 'INQUIRY_NOT_PENDING',
+  /** No recipient with the given id exists on the inquiry. */
+  RECIPIENT_NOT_FOUND = 'RECIPIENT_NOT_FOUND',
+  /** The targeted recipient is not an AGENT recipient — an agent tool may
+   *  only reply as an agent recipient, never forge a human/endpoint verdict. */
+  RECIPIENT_NOT_AGENT = 'RECIPIENT_NOT_AGENT',
+  /** The targeted recipient has already replied (idempotent-safe rejection). */
+  RECIPIENT_ALREADY_REPLIED = 'RECIPIENT_ALREADY_REPLIED',
+  /** No phase with the given `phaseKey` exists on the run (a "phase" is a
+   *  run job/stage key). Uniform with a phase that never ran. */
+  PHASE_NOT_FOUND = 'PHASE_NOT_FOUND',
+  /** The phase exists but is not in a state that can be refined/restarted —
+   *  only a COMPLETED phase is refinable (a still-running or skipped phase
+   *  is not). */
+  PHASE_NOT_REFINABLE = 'PHASE_NOT_REFINABLE',
+}
+
+// ─── Request (engine-internal wire shape) ────────────────────────────────────
+//
+// `runId` + `orgId` are the SERVER-derived tenancy/subject binding injected by
+// the gateway from the verified session token — they are part of the wire
+// shape the engine validates, but the AGENT never supplies them.
+
+const RunBindingShape = {
+  /** The governing run, injected server-side from the session — not agent input. */
+  runId: z.string().min(1),
+  /** The session's org, injected server-side from the token — not agent input. */
+  orgId: z.string().min(1),
+} as const;
+
+const DecideGateRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.DECIDE_GATE),
+  /** The DECISION_GATE inquiry to decide (must belong to the governing run). */
+  inquiryId: z.string().min(1),
+  /** The agent recipient row on the inquiry the caller replies AS. */
+  recipientId: z.string().min(1),
+  verdict: z.nativeEnum(DecisionVerdict),
+  /** Required (non-empty) when verdict is REJECT — enforced downstream by the
+   *  reused `DecisionGateReplySchema`. */
+  reason: z.string().optional(),
+});
+
+const AnswerInquiryRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.ANSWER_INQUIRY),
+  /** The non-gate inquiry to answer (must belong to the governing run). */
+  inquiryId: z.string().min(1),
+  /** The agent recipient row on the inquiry the caller replies AS. */
+  recipientId: z.string().min(1),
+  /** Kind-specific reply payload — validated by the inquiry kind's own schema. */
+  payload: z.record(z.string(), z.unknown()),
+});
+
+const SetRunStatusRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.SET_RUN_STATUS),
+  status: z.nativeEnum(WorkflowRunStatusTarget),
+  reason: z.string().optional(),
+});
+
+const RefinePhaseRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.REFINE_PHASE),
+  /** The phase to re-run — the run's job/stage key. Must be a COMPLETED phase. */
+  phaseKey: z.string().min(1),
+  /** Optional refinement feedback folded into the re-run of the phase. */
+  feedback: z.string().optional(),
+});
+
+const RestartPhaseRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.RESTART_PHASE),
+  /** The phase to re-run from scratch — the run's job/stage key. Must be COMPLETED. */
+  phaseKey: z.string().min(1),
+});
+
+/**
+ * The engine-internal control request. Discriminated on `action`; every member
+ * carries the server-derived `runId` + `orgId` binding.
+ */
+export const WorkflowControlRequestSchema = z.discriminatedUnion('action', [
+  DecideGateRequestSchema,
+  AnswerInquiryRequestSchema,
+  SetRunStatusRequestSchema,
+  RefinePhaseRequestSchema,
+  RestartPhaseRequestSchema,
+]);
+export type WorkflowControlRequest = z.infer<typeof WorkflowControlRequestSchema>;
+
+export type DecideGateRequest = z.infer<typeof DecideGateRequestSchema>;
+export type AnswerInquiryRequest = z.infer<typeof AnswerInquiryRequestSchema>;
+export type SetRunStatusRequest = z.infer<typeof SetRunStatusRequestSchema>;
+export type RefinePhaseRequest = z.infer<typeof RefinePhaseRequestSchema>;
+export type RestartPhaseRequest = z.infer<typeof RestartPhaseRequestSchema>;
+
+// ─── Result (first-class structured accepted/rejected outcome) ───────────────
+
+export const WorkflowControlResultSchema = z.discriminatedUnion('ok', [
+  z.object({
+    ok: z.literal(true),
+    /** Optional human-readable note (e.g. which signal was sent). */
+    detail: z.string().optional(),
+  }),
+  z.object({
+    ok: z.literal(false),
+    code: z.nativeEnum(WorkflowControlRejectionCode),
+    message: z.string().min(1),
+  }),
+]);
+export type WorkflowControlResult = z.infer<typeof WorkflowControlResultSchema>;
+
+/** Construct an accepted result. */
+export function workflowControlAccepted(detail?: string): WorkflowControlResult {
+  return detail === undefined ? { ok: true } : { ok: true, detail };
+}
+
+/** Construct a typed rejection result. */
+export function workflowControlRejected(
+  code: WorkflowControlRejectionCode,
+  message: string,
+): WorkflowControlResult {
+  return { ok: false, code, message };
+}
+
+/**
+ * The canonical capability ref governing this surface. `workflow` is an
+ * existing first-party capability domain; the router dispatches this ref to the
+ * engine's internal control endpoint and authorization-api gates it by grant.
+ */
+export const WORKFLOW_CONTROL_CAPABILITY_REF = 'workflow:control@1';