@xemahq/kernel-contracts 0.1.0

package/src/workflow/lib/platform-task-queue.ts

@@ -0,0 +1,83 @@
+/**
+ * Internal-workflow task-queue naming — Epic T (Temporal internal-workflow
+ * platform).
+ *
+ * Every internal/platform workflow runs in the `xema` namespace
+ * (`PLATFORM_TEMPORAL_NAMESPACE`) on a task queue named for its domain. One
+ * queue per domain is the unit of worker assignment + concurrency budget: a
+ * worker may poll any subset, so a dedicated internal worker can later be
+ * split out as a deployment choice — not a code change.
+ *
+ * Distinct from `TaskQueueName` (the pipeline-engine's `xema_default` /
+ * `xema_agent` / `xema_human` queues, polled by `workflow-runtime-worker`).
+ * Internal/platform workflows never share those queues.
+ */
+
+/**
+ * Closed set of internal-workflow domains. Each domain owns exactly one
+ * Temporal task queue (`platformTaskQueue(domain)`) and is the
+ * `WorkflowDomain` search-attribute value for its runs. Adding a domain is a
+ * one-line extension here.
+ */
+export enum PlatformWorkflowDomain {
+  /** Session launch / resume / hibernate. */
+  SESSION_LIFECYCLE = 'session-lifecycle',
+  /** Session checkpoint + the lifecycle reconciler. */
+  SESSION_MAINTENANCE = 'session-maintenance',
+  /** webapp-studio provisioning. */
+  STUDIO = 'studio',
+  /** Document / PDF export + render jobs. */
+  DOCUMENTS = 'documents',
+  /** SCM repo ingestion + project analysis. */
+  SCM_INGESTION = 'scm-ingestion',
+  /** workload-runtime-api K8s reconcile. */
+  WORKLOAD = 'workload',
+  /** Integration provider sync scheduling. */
+  INTEGRATION_SYNC = 'integration-sync',
+  /**
+   * Integration connection lifecycle — OAuth / App-install finalize sagas,
+   * credential rotation, integration deletion cascades. Distinct from
+   * `INTEGRATION_SYNC` (scheduled provider polling).
+   */
+  INTEGRATION_LIFECYCLE = 'integration-lifecycle',
+  /** Biome-installation cleanup cascade. */
+  BIOME_LIFECYCLE = 'biome-lifecycle',
+  /**
+   * Integration-ingress webhook-outbox forward dispatch (Phase J). One
+   * workflow per outbox row; Temporal owns retries + DLQ semantics.
+   */
+  INTEGRATION_INGRESS = 'integration-ingress',
+  /**
+   * Knowledge-base enrichment and file ingestion workflows (T1 entity
+   * extraction, T2 file ingestion).
+   */
+  KNOWLEDGE_BASE = 'knowledge-base',
+}
+
+/** Prefix shared by every internal-workflow task queue. */
+export const PLATFORM_TASK_QUEUE_PREFIX = 'xema-platform.';
+
+/**
+ * The Temporal task queue for an internal-workflow domain —
+ * `xema-platform.<domain>`. Single source of truth: callers derive the queue
+ * from the domain enum, never hard-code the string.
+ */
+export function platformTaskQueue(domain: PlatformWorkflowDomain): string {
+  return `${PLATFORM_TASK_QUEUE_PREFIX}${domain}`;
+}
+
+/**
+ * Inverse of `platformTaskQueue` — the domain a `xema-platform.*` queue
+ * serves, or `null` if the string is not an internal-workflow queue.
+ */
+export function platformWorkflowDomainOfQueue(
+  taskQueue: string,
+): PlatformWorkflowDomain | null {
+  if (!taskQueue.startsWith(PLATFORM_TASK_QUEUE_PREFIX)) {
+    return null;
+  }
+  const domain = taskQueue.slice(PLATFORM_TASK_QUEUE_PREFIX.length);
+  return (Object.values(PlatformWorkflowDomain) as string[]).includes(domain)
+    ? (domain as PlatformWorkflowDomain)
+    : null;
+}

package/src/workflow/lib/review-subject/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Public surface of the review-subject narrower. Consumers import from
+ * `@xemahq/workflow-contracts`; the FE consumes the synced mirror.
+ *
+ * Re-exports:
+ *   • `ReviewSubjectKind` — closed-set discriminator (`ARTIFACT_REF` | `STRING`)
+ *   • `narrowReviewableContent` + `ReviewableSubject` — orchestrator + union
+ *   • Per-producer subject interfaces (for FE switch typing)
+ */
+
+export { ReviewSubjectKind } from './kinds';
+export { narrowReviewableContent, type ReviewableSubject } from './narrow';
+
+export { type ArtifactRefReviewSubject } from './producers/artifact-ref';
+export { type StringReviewSubject } from './producers/string';

package/src/workflow/lib/review-subject/kinds.ts

@@ -0,0 +1,31 @@
+/**
+ * Closed set of review-subject kinds under the unified
+ * outputs/deliverables/artifacts model.
+ *
+ * After the unification refactor every reviewable byte flows through
+ * artifact-store, so the framework only needs two kinds: a pointer to an
+ * artifact (the universal review path) and a literal string (used when the
+ * workflow author wrote `subject: "..."` directly). Anything that doesn't
+ * match either shape is a bug — the narrower throws (fail-fast).
+ *
+ * Lives in its own file so producer modules and the FE renderer can both
+ * import the enum without pulling in the full narrower orchestration.
+ */
+export enum ReviewSubjectKind {
+  /**
+   * Universal review path: the subject IS an `ArtifactRef` (one artifact at
+   * a specific version). The FE renders via `OutputCard` with full review
+   * tooling — anchors, comments, version compare, per-OutputKind renderer.
+   *
+   * Every activity output that carries reviewable content is promoted to an
+   * `ArtifactRef` by the kernel's `finalizeOutputs` wrapper; downstream
+   * review steps receive refs, not raw envelopes.
+   */
+  ARTIFACT_REF = 'artifact-ref',
+  /**
+   * Bare string subject — the workflow author wrote `subject: "..."` as a
+   * literal or an expression that resolved to a primitive string. Rendered
+   * as inline literal text on the FE.
+   */
+  STRING = 'string',
+}

package/src/workflow/lib/review-subject/narrow.ts

@@ -0,0 +1,123 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Review subject — framework-aware narrowing of `subject:` content ──
+//
+// `xema/review@v3` resolves `subject:` to whatever the workflow author wrote.
+// Under the unified outputs/deliverables/artifacts model the only two
+// reviewable shapes are `ArtifactRef` (every activity output is one) and a
+// literal `string` (used when the author hard-coded a value). Anything else
+// is a bug — the narrower throws so the offending step fails fast instead of
+// silently degrading.
+//
+// `narrowReviewableContent` is the single deterministic boundary that tags
+// the value with a closed `ReviewSubjectKind` so both producer
+// (review.workflow) and consumer (FE renderer) dispatch on the same
+// discriminator.
+//
+// Synchronous by contract — many callers (workflow code, FE) cannot await.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  type ArtifactRefReviewSubject,
+  looksLikeArtifactRef,
+  narrowArtifactRef,
+} from './producers/artifact-ref';
+import type { ArtifactRef } from '../artifact-ref';
+import { ReviewSubjectKind } from './kinds';
+import { type StringReviewSubject, narrowString } from './producers/string';
+
+export type ReviewableSubject =
+  | ArtifactRefReviewSubject
+  | StringReviewSubject;
+
+/**
+ * Convert a raw `subject:` value resolved by the workflow engine into a
+ * tagged `ReviewableSubject`. Deterministic — strings become `STRING`,
+ * values matching the `ArtifactRef` shape become `ARTIFACT_REF`, and
+ * anything else throws. No silent fallback (`feedback_failfast_no_workarounds`).
+ */
+export function narrowReviewableContent(subject: unknown): ReviewableSubject {
+  if (typeof subject === 'string') {
+    return narrowString(subject);
+  }
+  if (looksLikeArtifactRef(subject)) {
+    return narrowArtifactRef(subject);
+  }
+  if (looksLikeArtifactRefReviewSubject(subject)) {
+    return narrowArtifactRef(coerceWrappedArtifactRef(subject.ref));
+  }
+  if (looksLikeStringReviewSubject(subject)) {
+    return narrowString(subject.value);
+  }
+  throw new Error(
+    `narrowReviewableContent: unrecognized subject shape (expected string or ArtifactRef). ` +
+      `Activities must promote reviewable content to an artifact via finalizeOutputs before review. ` +
+      `Received: ${describeSubject(subject)}`,
+  );
+}
+
+function looksLikeArtifactRefReviewSubject(
+  value: unknown,
+): value is ArtifactRefReviewSubject {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const rec = value as Record<string, unknown>;
+  return (
+    rec.kind === ReviewSubjectKind.ARTIFACT_REF &&
+    (looksLikeArtifactRef(rec.ref) || looksLikePinnedSubjectArtifact(rec.ref))
+  );
+}
+
+function looksLikePinnedSubjectArtifact(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const rec = value as Record<string, unknown>;
+  return (
+    typeof rec.artifactId === 'string' &&
+    typeof rec.versionId === 'string' &&
+    typeof rec.version === 'number' &&
+    Number.isInteger(rec.version) &&
+    typeof rec.hash === 'string'
+  );
+}
+
+function coerceWrappedArtifactRef(value: unknown): ArtifactRef {
+  if (looksLikeArtifactRef(value)) {
+    return value;
+  }
+  if (looksLikePinnedSubjectArtifact(value)) {
+    const rec = value as Record<string, unknown>;
+    return {
+      artifactId: rec.artifactId as string,
+      versionId: rec.versionId as string,
+      version: rec.version as number,
+      hash: rec.hash as string,
+      type: 'unknown',
+    };
+  }
+  throw new Error(
+    `narrowReviewableContent: wrapped artifact-ref subject contains invalid ref shape. Received: ${describeSubject(value)}`,
+  );
+}
+
+function looksLikeStringReviewSubject(value: unknown): value is StringReviewSubject {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const rec = value as Record<string, unknown>;
+  return (
+    rec.kind === ReviewSubjectKind.STRING && typeof rec.value === 'string'
+  );
+}
+
+function describeSubject(subject: unknown): string {
+  if (subject === null) return 'null';
+  if (subject === undefined) return 'undefined';
+  if (Array.isArray(subject)) return `Array(${subject.length})`;
+  if (typeof subject === 'object') {
+    const keys = Object.keys(subject).slice(0, 8);
+    return `object{${keys.join(',')}}`;
+  }
+  return typeof subject;
+}

package/src/workflow/lib/review-subject/producers/artifact-ref.ts

@@ -0,0 +1,33 @@
+/**
+ * Producer narrower for the unified `ArtifactRef` review path.
+ *
+ * Under the unified outputs/deliverables/artifacts model, every named
+ * activity output is an `ArtifactRef` — the bytes live in artifact-store,
+ * the envelope carries pointers. Review subjects that match the
+ * `ArtifactRef` shape route through this producer and render via
+ * `OutputCard` on the FE, getting the full review tooling (anchors,
+ * comments, version compare, per-OutputKind renderer) for free.
+ *
+ * Probe is intentionally strict — all five identity fields must be
+ * present (artifactId/versionId/version/hash/type). This is the same
+ * shape `isArtifactRef` checks in `../../artifact-ref.ts`.
+ */
+
+import { isArtifactRef, type ArtifactRef } from '../../artifact-ref';
+import { ReviewSubjectKind } from '../kinds';
+
+export interface ArtifactRefReviewSubject {
+  readonly kind: ReviewSubjectKind.ARTIFACT_REF;
+  readonly ref: ArtifactRef;
+}
+
+export function looksLikeArtifactRef(value: unknown): value is ArtifactRef {
+  return isArtifactRef(value);
+}
+
+export function narrowArtifactRef(ref: ArtifactRef): ArtifactRefReviewSubject {
+  return {
+    kind: ReviewSubjectKind.ARTIFACT_REF,
+    ref,
+  };
+}

package/src/workflow/lib/review-subject/producers/string.ts

@@ -0,0 +1,24 @@
+/**
+ * Producer narrower for bare string subjects — the workflow author wrote
+ * `subject: "..."` or an expression that resolved to a primitive string.
+ *
+ * Under the unified review model strings render as inline literal text on
+ * the FE; per-format dispatch (markdown/yaml/json/url/code/plain-text) has
+ * retired alongside the legacy per-shape kinds. If a workflow needs richer
+ * rendering, it must promote the content to an artifact via
+ * `finalizeOutputs` and pass an `ArtifactRef` instead.
+ */
+
+import { ReviewSubjectKind } from '../kinds';
+
+export interface StringReviewSubject {
+  readonly kind: ReviewSubjectKind.STRING;
+  readonly value: string;
+}
+
+export function narrowString(value: string): StringReviewSubject {
+  return {
+    kind: ReviewSubjectKind.STRING,
+    value,
+  };
+}

package/src/workflow/lib/role-capability.ts

@@ -0,0 +1,80 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── RoleCapabilityProfile types + closed-domain enums ──
+//
+// The DATA (one profile per `AgentRunRole`) lives in biome contributions
+// at `biomes/kernel/runtime/role-capabilities/<role>.role-capability.yaml`.
+// llm-registry-api's `RoleCapabilityRegistryService` loads + serves them
+// in-process, exposes them via `GET /role-capabilities/:role`, and writes
+// the resolved `allowedXemaTools` array into each invocation's
+// `context.json` (`authority.allowedXemaTools`).
+//
+// This module exports ONLY the closed-domain enum values + the typed
+// shape every consumer agrees on. Adding a new role = (1) append to
+// `AGENT_RUN_ROLES`, (2) drop a new YAML in the kernel runtime biome.
+// No platform code change is required.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { AgentRunRole } from './agent-role';
+
+/**
+ * Closed surface taxonomy. The renderer's surface-vs-role guard rejects
+ * role/surface combinations that don't match the declared profile.
+ */
+export const INVOCATION_SURFACES = [
+  'pipeline-run',
+  'agent-session',
+  'design-system-builder',
+  'gate-review',
+] as const;
+export type InvocationSurface = (typeof INVOCATION_SURFACES)[number];
+
+/**
+ * Closed write-policy taxonomy.
+ *
+ * - `read-only`: the role does not mutate the workspace; output flows
+ *   out-of-band via a dedicated activity (e.g. `xema/review@v3`).
+ * - `own-pages-only`: the role may only write the deliverable files
+ *   declared on `outputContract.files[]` / `outputContract.multiPage`.
+ * - `full-write`: the role may write anywhere `mayWriteWorkspace`
+ *   permits (typically `/workspace/deliverables/`).
+ */
+export const WRITE_POLICIES = [
+  'read-only',
+  'own-pages-only',
+  'full-write',
+] as const;
+export type WritePolicy = (typeof WRITE_POLICIES)[number];
+
+/**
+ * Universal read-only Xema-namespaced tools every role gets. Adding a
+ * tool here grants it to every role implicitly — gate-keep with care.
+ *
+ * Kept as an exported constant so biome authors can compose role YAMLs
+ * (`allowedXemaTools: [...XEMA_TOOL_READ_ONLY]`) without re-typing the
+ * literal. Loaded role profiles are still validated against this list
+ * at boot to catch typos.
+ */
+export const XEMA_TOOL_READ_ONLY = [
+  'xema_memory_get',
+] as const;
+
+/**
+ * Memory-write capability. Granted to most roles; withheld from
+ * read-only roles whose output is delivered out-of-band.
+ */
+export const XEMA_TOOL_MEMORY_WRITE = ['xema_memory_set'] as const;
+
+export interface RoleCapabilityProfile {
+  readonly role: AgentRunRole;
+  readonly surface: InvocationSurface;
+  readonly writePolicy: WritePolicy;
+  /**
+   * `'never'` = blanket deny repo writes.
+   * `'when-granted'` = repo writes are allowed iff the dispatch supplied
+   * `workflowInputs.repoSlugs[]`. Today only the `engineer` role is
+   * `'when-granted'`.
+   */
+  readonly mayEditRepos: 'never' | 'when-granted';
+  readonly mayWriteKnowledgeBase: boolean;
+  readonly allowedXemaTools: readonly string[];
+}

package/src/workflow/lib/run-progress.ts

@@ -0,0 +1,254 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Run Progress Contracts ──
+//
+// Shared shapes for the in-flight progress + milestone surface. The
+// runtime worker emits these; the engine fans micro-progress out via the
+// per-run SSE channel and milestones via the unified realtime stream.
+//
+// Contracts here are activity-agnostic: every activity that wants to
+// contribute to the run-detail UI publishes the same DTOs. Adding a new
+// activity does not introduce new wire shapes — extend the closed enums
+// instead.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * What the agent (or activity) is doing right now. Closed enum so the
+ * frontend has a deterministic icon/label set and producers cannot leak
+ * free-form strings.
+ */
+export enum RunStepKind {
+  THINKING = 'thinking',
+  EDITING_FILE = 'editing_file',
+  RUNNING_COMMAND = 'running_command',
+  READING_FILE = 'reading_file',
+  SEARCHING = 'searching',
+  FETCHING = 'fetching',
+  VALIDATING = 'validating',
+  WAITING_INPUT = 'waiting_input',
+  SUMMARIZING = 'summarizing',
+  POSTING_REVIEW = 'posting_review',
+  PUBLISHING = 'publishing',
+  OTHER = 'other',
+}
+
+/**
+ * Coarse activity bucket used for milestones — what kind of work the
+ * job is doing at the activity level, not the step level. Stays stable
+ * across the closed list of runtime activities.
+ */
+export enum RunActivityKind {
+  AGENT_WORK = 'agent_work',
+  DELIVERABLE_VALIDATION = 'deliverable_validation',
+  REVIEW_POSTING = 'review_posting',
+  SCM_MERGE = 'scm_merge',
+  SCM_CHECKOUT = 'scm_checkout',
+  KB_PUBLISH = 'kb_publish',
+  WEBHOOK = 'webhook',
+  HTTP = 'http',
+  DISPATCH = 'dispatch',
+  ARTIFACT_EMIT = 'artifact_emit',
+  RECONCILE = 'reconcile',
+  ENDPOINT_FETCH = 'endpoint_fetch',
+  SCHEDULED_DISPATCH = 'scheduled_dispatch',
+  REVIEW = 'review',
+  BACKLOG_SYNC = 'backlog_sync',
+  /**
+   * Org-database migration dispatched via `xema/run-migrations@v1`
+   * (Phase G of the org-managed-databases plan). The activity calls
+   * org-database-pool-api to start a migration workflow and polls
+   * the per-database migration listing until the run reaches a
+   * terminal state.
+   */
+  RUN_MIGRATIONS = 'run_migrations',
+  /**
+   * Child-workflow execution dispatched from the root run via Temporal
+   * `executeChild` (e.g. `xema/decision-gate`, `xema/wait`). Emitted by
+   * `rootRunWorkflow` around each `executeChild` call so the JobRun
+   * lifecycle reflects child completion / failure / cancellation —
+   * activities-only milestones miss these jobs entirely.
+   */
+  CHILD_WORKFLOW = 'child_workflow',
+}
+
+/** Phase of a milestone's lifecycle. */
+export enum RunMilestonePhase {
+  STARTED = 'started',
+  PROGRESSING = 'progressing',
+  COMPLETED = 'completed',
+  AWAITING_INPUT = 'awaiting_input',
+  FAILED = 'failed',
+}
+
+/**
+ * Display profile of the agent that owns a step. Resolved by the engine
+ * from the agent registry; producers (worker activities) only carry the
+ * slug and the engine enriches.
+ */
+export interface RunStepAgentProfile {
+  readonly slug: string;
+  readonly displayName: string;
+  readonly avatarSeed: string;
+  readonly avatarStyle: string;
+}
+
+/**
+ * Lifecycle status of a tool invocation, mirrored end-to-end from the
+ * agent runtime to the FE timeline. `started` ⇒ tool was invoked, args
+ * may still be partially streamed; `completed` ⇒ args complete and tool
+ * has run; `error` ⇒ tool failed. Non-tool steps leave this undefined.
+ */
+export type RunStepToolStatus = 'started' | 'completed' | 'error';
+
+/**
+ * Tool-related enrichment carried on every step that originates from a
+ * `SessionFrame` `tool-call` or `tool-result`. Optional because pure
+ * THINKING / WAITING_INPUT / etc. steps don't have tool context.
+ *
+ * Consumers — notably the FE timeline — collapse step rows by
+ * `toolCallId` so a single tool invocation surfaces as one row that
+ * transitions through the lifecycle instead of three sequential rows.
+ */
+export interface RunStepToolDetails {
+  readonly status?: RunStepToolStatus;
+  /** Raw tool name (e.g. `read`, `bash`, `task`). */
+  readonly tool?: string;
+  /** Stable correlation id across started/completed/result events. */
+  readonly toolCallId?: string;
+  /** Tool input as produced by the model. */
+  readonly args?: unknown;
+  /** Tool output (tool-result frames only). */
+  readonly output?: unknown;
+  /** Failure message (mutually exclusive with `output`). */
+  readonly errorMessage?: string;
+}
+
+/** Body the worker POSTs for a single micro-progress event. */
+export interface RunStepProgressInput extends RunStepToolDetails {
+  readonly jobKey: string;
+  readonly jobRunId: string;
+  readonly agentSlug?: string;
+  readonly kind: RunStepKind;
+  readonly summary: string;
+  readonly target?: string;
+  readonly at: string;
+}
+
+/** Wire shape the engine SSE / clients consume. `runId` and `seq` are added by the engine on receive. */
+export interface RunStepProgress extends RunStepToolDetails {
+  readonly runId: string;
+  readonly jobKey: string;
+  readonly jobRunId: string;
+  readonly agent: RunStepAgentProfile | null;
+  readonly kind: RunStepKind;
+  readonly summary: string;
+  readonly target: string | null;
+  readonly at: string;
+  /** Monotonic per `(runId, jobRunId)`; assigned by the engine on receive. */
+  readonly seq: number;
+}
+
+/** Body the worker POSTs for a milestone. */
+export interface RunMilestoneInput {
+  readonly jobKey: string;
+  readonly jobRunId: string;
+  readonly activity: RunActivityKind;
+  readonly phase: RunMilestonePhase;
+  readonly summary: string;
+  readonly at: string;
+  readonly agentSlug?: string;
+}
+
+/** CloudEvent payload shape the engine publishes for `xema.workflow.run.milestone`. */
+export interface RunMilestone {
+  readonly runId: string;
+  readonly jobKey: string;
+  readonly jobRunId: string;
+  readonly agent: RunStepAgentProfile | null;
+  readonly activity: RunActivityKind;
+  readonly phase: RunMilestonePhase;
+  readonly summary: string;
+  readonly at: string;
+}
+
+// ─── SessionFrame → RunStepKind mapping ────────────────────────────────────
+
+/**
+ * Discriminator the worker passes to the mapper. Mirrors the kinds
+ * surfaced by `@xemahq/agent-session-runtime`'s `SessionFrame` — kept
+ * as a string literal union here so this contracts package stays free
+ * of a runtime dependency on the session runtime.
+ */
+export type AgentSessionFrameKind =
+  | 'token'
+  | 'tool-call'
+  | 'tool-result'
+  | 'progress'
+  | 'error'
+  | 'question'
+  | 'done';
+
+/**
+ * Coarse mapping from agent-session frame kind to public `RunStepKind`.
+ * Tool-name-specific refinement (e.g. `edit` → `EDITING_FILE`) happens
+ * via {@link mapToolNameToStepKind} below; this function is the
+ * activity-kind-agnostic default.
+ */
+export function mapSessionFrameKindToStepKind(kind: AgentSessionFrameKind): RunStepKind {
+  switch (kind) {
+    case 'token':
+      return RunStepKind.SUMMARIZING;
+    case 'tool-call':
+      return RunStepKind.OTHER;
+    case 'tool-result':
+      return RunStepKind.OTHER;
+    case 'progress':
+      return RunStepKind.THINKING;
+    case 'question':
+      return RunStepKind.WAITING_INPUT;
+    case 'error':
+      return RunStepKind.OTHER;
+    case 'done':
+      return RunStepKind.SUMMARIZING;
+    default:
+      return assertNever(kind);
+  }
+}
+
+/**
+ * Maps a raw OpenCode tool name (the worker sees these on `tool-call`
+ * frames) to a `RunStepKind`. Unknown tool names fall through to
+ * `OTHER` rather than throwing — the tool surface is open-ended at the
+ * OpenCode layer (biomes can introduce tools), so the mapper is
+ * intentionally lenient where the wire shape stays closed.
+ */
+export function mapToolNameToStepKind(toolName: string): RunStepKind {
+  const normalized = toolName.toLowerCase();
+  if (normalized === 'edit' || normalized === 'write' || normalized === 'multiedit') {
+    return RunStepKind.EDITING_FILE;
+  }
+  if (normalized === 'bash' || normalized === 'shell') {
+    return RunStepKind.RUNNING_COMMAND;
+  }
+  if (normalized === 'read' || normalized === 'view' || normalized === 'cat') {
+    return RunStepKind.READING_FILE;
+  }
+  if (normalized === 'grep' || normalized === 'glob' || normalized === 'search' || normalized === 'find') {
+    return RunStepKind.SEARCHING;
+  }
+  if (normalized === 'webfetch' || normalized === 'fetch' || normalized === 'http') {
+    return RunStepKind.FETCHING;
+  }
+  if (normalized === 'structuredoutput' || normalized === 'summarize') {
+    return RunStepKind.SUMMARIZING;
+  }
+  return RunStepKind.OTHER;
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled AgentSessionFrameKind: ${String(value)}`);
+}
+
+/** Maximum length the engine accepts for a `summary` field; producers should clamp before send. */
+export const RUN_STEP_SUMMARY_MAX = 140;
+/** Maximum length the engine accepts for a `target` field; producers should clamp before send. */
+export const RUN_STEP_TARGET_MAX = 240;