@xemahq/kernel-contracts 0.1.0 → 0.2.0

package/src/provisioning/lib/provisioning.ts

@@ -0,0 +1,499 @@
+import { z } from 'zod';
+
+// ─── Closed enums ────────────────────────────────────────────────────────────
+
+/**
+ * Kind of provisioning step.
+ *
+ *  - `SCAFFOLD` — seed an empty target with a project skeleton (e.g.
+ *    `create-next-app`). Only runs at workspace boot, guard-gated on the
+ *    target being scaffold-safe-empty.
+ *  - `EQUIP` — install a reusable unit (a Project Kit) into an already
+ *    scaffolded repo. Idempotent: guard-gated on a marker being absent.
+ */
+export enum ProvisioningStepKind {
+  SCAFFOLD = 'scaffold',
+  EQUIP = 'equip',
+}
+
+/**
+ * Pre-condition the executor evaluates against the LIVE filesystem before
+ * running a step. A failing guard ⇒ the step is recorded `skipped` — this
+ * is what makes the `provision` phase self-idempotent with no mutable
+ * ledger.
+ *
+ *  - `REPO_EMPTY`    — `repos/<repoRef>/` holds only `SCAFFOLD_SAFE_NOISE`.
+ *  - `PATH_ABSENT`   — `targetDir` is absent, or holds only safe noise.
+ *  - `MARKER_ABSENT` — `guardArgs.markerJsonPointer` resolves to nothing
+ *                      (e.g. the kit package is not yet in `package.json`).
+ *  - `ALWAYS`        — no pre-condition; the step always runs.
+ */
+export enum ProvisioningGuard {
+  REPO_EMPTY = 'repo_empty',
+  PATH_ABSENT = 'path_absent',
+  MARKER_ABSENT = 'marker_absent',
+  ALWAYS = 'always',
+}
+
+/**
+ * When a scaffold declaration is allowed to run.
+ *
+ *  - `WORKSPACE_BOOT`   — during the `provision` phase of session launch.
+ *  - `RUNTIME_REQUEST`  — on an explicit later request (EQUIP only).
+ *
+ * A `SCAFFOLD` step may only declare `WORKSPACE_BOOT` — scaffolding a
+ * non-empty repo mid-session is never safe.
+ */
+export enum ProvisioningTrigger {
+  WORKSPACE_BOOT = 'workspace-boot',
+  RUNTIME_REQUEST = 'runtime-request',
+}
+
+/** Mutation a `fileOp` applies to a path under the workspace. */
+export enum ProvisioningFileOpKind {
+  WRITE = 'write',
+  MERGE_JSON = 'merge-json',
+  MERGE_YAML = 'merge-yaml',
+}
+
+/** Terminal per-step outcome the executor reports back. */
+export enum ProvisioningStepStatus {
+  /** The guard failed — the step was a no-op (already provisioned). */
+  SKIPPED = 'skipped',
+  /** The guard passed and the content-addressed cache served the result. */
+  CACHE_HIT = 'cache_hit',
+  /** The guard passed and the commands ran (then wrote through to cache). */
+  BUILT = 'built',
+}
+
+/**
+ * Filesystem entries that do NOT disqualify a directory from being
+ * "scaffold-safe-empty". A repo with a committed `README.md` is still
+ * safe to scaffold into. Closed allowlist — both `REPO_EMPTY` and
+ * `PATH_ABSENT` guards evaluate against exactly this set.
+ */
+export const SCAFFOLD_SAFE_NOISE: readonly string[] = [
+  '.git',
+  '.gitignore',
+  'README.md',
+  'LICENSE',
+  '.xema',
+];
+
+// ─── Enum schemas ────────────────────────────────────────────────────────────
+
+export const ProvisioningStepKindSchema = z.enum(ProvisioningStepKind);
+export const ProvisioningGuardSchema = z.enum(ProvisioningGuard);
+export const ProvisioningTriggerSchema = z.enum(ProvisioningTrigger);
+export const ProvisioningFileOpKindSchema = z.enum(ProvisioningFileOpKind);
+export const ProvisioningStepStatusSchema = z.enum(ProvisioningStepStatus);
+
+// ─── Wire shapes (resolver → executor) ───────────────────────────────────────
+
+/**
+ * One command the executor runs via `spawn(argv)`. **`argv` arrays only,
+ * never a shell string** — no shell interpolation, no injection surface.
+ * `cwd` is workspace-relative and the executor enforces it resolves under
+ * `/workspace/repos/` or `/workspace/.xema/`.
+ */
+export const ProvisioningCommandSpecSchema = z
+  .object({
+    argv: z.array(z.string().min(1)).min(1),
+    cwd: z.string().min(1),
+    env: z.record(z.string(), z.string()).optional(),
+    timeoutMs: z.number().int().positive(),
+  })
+  .strict();
+export type ProvisioningCommandSpec = z.infer<
+  typeof ProvisioningCommandSpecSchema
+>;
+
+/**
+ * A declarative file mutation applied after a step's commands run.
+ * `contentBase64` decodes to the file body (`write`) or the fragment to
+ * merge (`merge-json` / `merge-yaml`). `path` is workspace-relative and
+ * boundary-checked by the executor.
+ */
+export const ProvisioningFileOpSchema = z
+  .object({
+    kind: ProvisioningFileOpKindSchema,
+    path: z.string().min(1),
+    contentBase64: z.string().min(1),
+  })
+  .strict();
+export type ProvisioningFileOp = z.infer<typeof ProvisioningFileOpSchema>;
+
+/**
+ * An optional residue of judgement that no deterministic command can
+ * cover. The executor NEVER runs an agent — it returns the instruction to
+ * agent-session-api, which decides whether/how to surface it. Most steps
+ * carry none.
+ */
+export const ProvisioningAgentInstructionSchema = z
+  .object({
+    agentSlug: z.string().min(1),
+    promptBase64: z.string().min(1),
+  })
+  .strict();
+export type ProvisioningAgentInstruction = z.infer<
+  typeof ProvisioningAgentInstructionSchema
+>;
+
+/**
+ * Presigned-URL pair for the content-addressed scaffold cache (Epic A §A4).
+ * agent-session-api mints these from a step's `cacheKey`; workspace-proxy
+ * GETs `getUrl` to probe for a hit, and on a miss PUTs the built tar to
+ * `putUrl` (write-through). `getHeaders` / `putHeaders` are the headers the
+ * presigned URL requires sent verbatim (e.g. the signed `Content-Type`).
+ *
+ * Absent on a step that is not cacheable (`cacheKey === null` — e.g. an
+ * `EQUIP` of a private Project Kit) or when the cache backend could not be
+ * reached at resolve time. The executor then builds locally — the plan's
+ * declared, logged optimization-bypass, never a silent degradation.
+ */
+export const ProvisioningCacheRefSchema = z
+  .object({
+    getUrl: z.string().min(1),
+    getHeaders: z.record(z.string(), z.string()),
+    putUrl: z.string().min(1),
+    putHeaders: z.record(z.string(), z.string()),
+  })
+  .strict();
+export type ProvisioningCacheRef = z.infer<typeof ProvisioningCacheRefSchema>;
+
+/** Per-guard arguments. Only `MARKER_ABSENT` needs one today. */
+export const ProvisioningGuardArgsSchema = z
+  .object({
+    /**
+     * JSON Pointer (RFC 6901) into a file under `targetDir` — the
+     * `MARKER_ABSENT` guard passes when it resolves to nothing. For an
+     * `EQUIP` kit the marker is the kit package key in `package.json`.
+     */
+    markerJsonPointer: z.string().min(1).optional(),
+    /** File the `markerJsonPointer` is resolved against, relative to `targetDir`. */
+    markerFile: z.string().min(1).optional(),
+  })
+  .strict();
+export type ProvisioningGuardArgs = z.infer<typeof ProvisioningGuardArgsSchema>;
+
+/**
+ * One fully-resolved provisioning step. Every biome-specific fact is
+ * baked in here — the executor is generic and never special-cases a
+ * biome. `cacheKey` is the content-addressed scaffold-cache key, or
+ * `null` for a step that must not be cached (e.g. an `EQUIP` of a private
+ * Project Kit fetched from an authenticated source).
+ */
+export const ResolvedProvisioningStepSchema = z
+  .object({
+    id: z.string().min(1),
+    version: z.string().min(1),
+    kind: ProvisioningStepKindSchema,
+    guard: ProvisioningGuardSchema,
+    guardArgs: ProvisioningGuardArgsSchema.optional(),
+    /** Workspace-relative directory the step provisions. */
+    targetDir: z.string().min(1),
+    cacheKey: z.string().min(1).nullable(),
+    /**
+     * Presigned scaffold-cache URLs derived from `cacheKey` (Epic A §A4).
+     * Present only on a cacheable step whose URLs were minted at resolve
+     * time; absent ⇒ the executor builds locally with no cache.
+     */
+    cache: ProvisioningCacheRefSchema.optional(),
+    commands: z.array(ProvisioningCommandSpecSchema),
+    fileOps: z.array(ProvisioningFileOpSchema),
+    agentInstruction: ProvisioningAgentInstructionSchema.optional(),
+  })
+  .strict();
+export type ResolvedProvisioningStep = z.infer<
+  typeof ResolvedProvisioningStepSchema
+>;
+
+/**
+ * The full plan agent-session-api emits and workspace-proxy executes.
+ * Steps are ordered: every `SCAFFOLD` precedes every `EQUIP` (you cannot
+ * equip a repo that has not been scaffolded). `version` is a literal `1`
+ * so a future wire change fails fast instead of silently mis-parsing.
+ */
+export const ResolvedProvisioningPlanSchema = z
+  .object({
+    version: z.literal(1),
+    sessionId: z.string().min(1),
+    steps: z.array(ResolvedProvisioningStepSchema),
+  })
+  .strict();
+export type ResolvedProvisioningPlan = z.infer<
+  typeof ResolvedProvisioningPlanSchema
+>;
+
+// ─── Wire shapes (executor → resolver) ───────────────────────────────────────
+
+/**
+ * A `built` step that had a `cache` ref and is eligible for an out-of-band
+ * cache write. The executor no longer writes the cache inline; instead it
+ * surfaces the pending write here, and the caller (agent-session-api)
+ * dispatches `writeScaffoldCacheWorkflow` per entry (Phase J §J3).
+ *
+ * `cacheRef` is the SAME ref the plan carried in — re-passed to keep the
+ * activity stateless (workspace-proxy doesn't have to retain a presigned
+ * URL between the build and the workflow's callback).
+ */
+export const ProvisioningPendingCacheWriteSchema = z
+  .object({
+    sourceDir: z.string().min(1),
+    cacheRef: ProvisioningCacheRefSchema,
+  })
+  .strict();
+export type ProvisioningPendingCacheWrite = z.infer<
+  typeof ProvisioningPendingCacheWriteSchema
+>;
+
+/** Outcome of one executed step. */
+export const ProvisioningStepResultSchema = z
+  .object({
+    id: z.string().min(1),
+    status: ProvisioningStepStatusSchema,
+    /** Non-empty only on `built`/`cache_hit` steps that carried one. */
+    pendingAgentInstruction: ProvisioningAgentInstructionSchema.optional(),
+    /**
+     * Non-empty only on a `built` step whose plan carried a `cache` ref.
+     * The caller dispatches `writeScaffoldCacheWorkflow` per entry — the
+     * executor never writes the cache itself (Phase J §J3).
+     */
+    pendingCacheWrite: ProvisioningPendingCacheWriteSchema.optional(),
+  })
+  .strict();
+export type ProvisioningStepResult = z.infer<
+  typeof ProvisioningStepResultSchema
+>;
+
+/**
+ * The executor's reply. `pendingAgentInstructions` collects every step's
+ * `agentInstruction` (the proxy ran none) so agent-session-api can decide
+ * how to surface them.
+ */
+export const ProvisioningPlanResultSchema = z
+  .object({
+    version: z.literal(1),
+    sessionId: z.string().min(1),
+    steps: z.array(ProvisioningStepResultSchema),
+    pendingAgentInstructions: z.array(ProvisioningAgentInstructionSchema),
+  })
+  .strict();
+export type ProvisioningPlanResult = z.infer<
+  typeof ProvisioningPlanResultSchema
+>;
+
+// ─── Parse helpers ───────────────────────────────────────────────────────────
+
+/** Thrown when a provisioning wire payload fails schema validation. */
+export class ProvisioningContractParseError extends Error {
+  readonly issues: readonly z.core.$ZodIssue[];
+  constructor(what: string, issues: readonly z.core.$ZodIssue[]) {
+    super(
+      `Invalid ${what}: ${issues
+        .map((i) => `[${i.path.join('.')}] ${i.message}`)
+        .join('; ')}`,
+    );
+    this.name = 'ProvisioningContractParseError';
+    this.issues = issues;
+  }
+}
+
+/** Fail-fast parse of a `ResolvedProvisioningPlan` (executor entry point). */
+export function parseResolvedProvisioningPlan(
+  raw: unknown,
+): ResolvedProvisioningPlan {
+  const result = ResolvedProvisioningPlanSchema.safeParse(raw);
+  if (!result.success) {
+    throw new ProvisioningContractParseError(
+      'ResolvedProvisioningPlan',
+      result.error.issues,
+    );
+  }
+  return result.data;
+}
+
+/** Fail-fast parse of a `ProvisioningPlanResult` (resolver-side reply parse). */
+export function parseProvisioningPlanResult(
+  raw: unknown,
+): ProvisioningPlanResult {
+  const result = ProvisioningPlanResultSchema.safeParse(raw);
+  if (!result.success) {
+    throw new ProvisioningContractParseError(
+      'ProvisioningPlanResult',
+      result.error.issues,
+    );
+  }
+  return result.data;
+}
+
+// ─── Authoring schema — biome `provisioning/<id>.yaml` ──────────────────────
+//
+// The wire shapes above are what agent-session-api emits and workspace-proxy
+// executes. The shapes below are what a PLUGIN AUTHOR writes on disk. The
+// `provisioning-plan-resolver` (agent-session-api) reads an authored
+// `ProvisioningScaffoldDefinition` (served, with its template files
+// base64-inlined, by biome-host-api), expands it per the manifest selector
+// — one rendered step per matched element — interpolates `{{placeholder}}`
+// tokens against the match context, and emits the wire
+// `ResolvedProvisioningStep`s above.
+//
+// Only `SCAFFOLD` recipes are authored here. `EQUIP` steps are NOT: the
+// resolver synthesizes them from the session's resolved Project Kit set,
+// because a kit's install command is a function of its runtime-resolved
+// source (git URL / npm package + version + auth), not authorable static
+// content.
+
+/**
+ * Variant key used when a scaffold declares no `variantField`. The single
+ * `variants` entry MUST then be authored under exactly this key — the
+ * `ProvisioningScaffoldDefinition` `superRefine` enforces it.
+ */
+export const DEFAULT_PROVISIONING_VARIANT = 'default';
+
+/**
+ * One command in an authored recipe. Identical in shape to the wire
+ * `ProvisioningCommandSpec`, except every `argv` / `cwd` / `env` value MAY
+ * carry `{{placeholder}}` tokens the resolver substitutes from the match
+ * context (matched-element fields + session context such as `repoRef`)
+ * before emitting the resolved step.
+ */
+export const ProvisioningCommandTemplateSchema = z
+  .object({
+    argv: z.array(z.string().min(1)).min(1),
+    cwd: z.string().min(1),
+    env: z.record(z.string(), z.string()).optional(),
+    timeoutMs: z.number().int().positive(),
+  })
+  .strict();
+export type ProvisioningCommandTemplate = z.infer<
+  typeof ProvisioningCommandTemplateSchema
+>;
+
+/**
+ * One file mutation in an authored recipe. `templateRef` is a path —
+ * relative to the scaffold's sibling template directory
+ * `provisioning/<scaffoldId>/` — to the file whose bytes are this op's
+ * content. biome-host-api reads + base64-encodes every referenced
+ * template when it serves the definition, so the resolver never touches
+ * the biome filesystem. `{{placeholder}}` tokens are interpolated in
+ * `path` only — never in the file body.
+ */
+export const ProvisioningFileOpTemplateSchema = z
+  .object({
+    kind: ProvisioningFileOpKindSchema,
+    path: z.string().min(1),
+    templateRef: z.string().min(1),
+  })
+  .strict();
+export type ProvisioningFileOpTemplate = z.infer<
+  typeof ProvisioningFileOpTemplateSchema
+>;
+
+/**
+ * The residue-of-judgement instruction an authored recipe may carry. The
+ * executor never runs an agent — `promptTemplateRef` points at a template
+ * file the resolver base64-encodes into the wire
+ * `ProvisioningAgentInstruction`.
+ */
+export const ProvisioningAgentInstructionTemplateSchema = z
+  .object({
+    agentSlug: z.string().min(1),
+    promptTemplateRef: z.string().min(1),
+  })
+  .strict();
+export type ProvisioningAgentInstructionTemplate = z.infer<
+  typeof ProvisioningAgentInstructionTemplateSchema
+>;
+
+/**
+ * The recipe applied to one matched element — the commands + file ops +
+ * optional agent instruction. A scaffold that sets `variantField` declares
+ * one recipe per discriminator value; a single-variant scaffold declares
+ * exactly one recipe under the `DEFAULT_PROVISIONING_VARIANT` key.
+ */
+export const ProvisioningRecipeSchema = z
+  .object({
+    commands: z.array(ProvisioningCommandTemplateSchema),
+    // Optional in authored YAML — many scaffolds (e.g. Next.js, Vite) ship
+    // no template `fileOps` because all file shaping happens at runtime in
+    // workspace-proxy. Defaults to `[]` so downstream code always sees an
+    // array without each biome author having to write `fileOps: []`.
+    fileOps: z.array(ProvisioningFileOpTemplateSchema).default([]),
+    agentInstruction: ProvisioningAgentInstructionTemplateSchema.optional(),
+  })
+  .strict();
+export type ProvisioningRecipe = z.infer<typeof ProvisioningRecipeSchema>;
+
+/**
+ * The parsed `provisioning/<id>.yaml` authoring document — a biome's
+ * deterministic `SCAFFOLD` recipe.
+ */
+export const ProvisioningScaffoldDefinitionSchema = z
+  .object({
+    /** MUST equal the file basename AND the manifest `provisioning[].id`. */
+    id: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9-]*$/,
+        'scaffold id must be lowercase kebab-case and match the provisioning/<id>.yaml basename',
+      ),
+    /**
+     * Author-bumped recipe version. Folds into every emitted step's
+     * content-addressed `cacheKey` — bump it to invalidate the cache.
+     */
+    scaffoldVersion: z.string().min(1),
+    /**
+     * Workspace-relative directory the scaffold provisions — e.g.
+     * `repos/{{repoRef}}/{{workingDir}}`. Carries `{{placeholder}}` tokens.
+     */
+    targetDir: z.string().min(1),
+    /**
+     * Field on each matched element whose value selects the variant. Omit
+     * for a single-variant scaffold (then `variants` MUST hold exactly the
+     * `DEFAULT_PROVISIONING_VARIANT` key).
+     */
+    variantField: z.string().min(1).optional(),
+    variants: z.record(z.string().min(1), ProvisioningRecipeSchema),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const variantKeys = Object.keys(value.variants);
+    if (variantKeys.length === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['variants'],
+        message: 'a scaffold must declare at least one variant',
+      });
+      return;
+    }
+    if (
+      !value.variantField &&
+      (variantKeys.length !== 1 ||
+        variantKeys[0] !== DEFAULT_PROVISIONING_VARIANT)
+    ) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['variants'],
+        message: `a scaffold with no \`variantField\` must declare exactly one variant under the "${DEFAULT_PROVISIONING_VARIANT}" key`,
+      });
+    }
+  });
+export type ProvisioningScaffoldDefinition = z.infer<
+  typeof ProvisioningScaffoldDefinitionSchema
+>;
+
+/** Fail-fast parse of an authored `provisioning/<id>.yaml` document. */
+export function parseProvisioningScaffoldDefinition(
+  raw: unknown,
+): ProvisioningScaffoldDefinition {
+  const result = ProvisioningScaffoldDefinitionSchema.safeParse(raw);
+  if (!result.success) {
+    throw new ProvisioningContractParseError(
+      'ProvisioningScaffoldDefinition',
+      result.error.issues,
+    );
+  }
+  return result.data;
+}

package/src/worker-runtime/index.ts

@@ -0,0 +1,14 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Worker Runtime Contracts — Barrel Export ──
+//
+// Kernel (Layer 1) contracts for the WorkerRuntime abstraction — the
+// pluggable seam that lets Xema host multiple agent-runtime implementations
+// (Opencode in v1; ClaudeCode, CopilotCLI, OpenHands as forward-compat
+// targets). Pure types + closed enums + zod schemas. Zero NestJS.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/enums';
+export * from './lib/capabilities';
+export * from './lib/messages';
+export * from './lib/runtime';
+export * from './lib/schemas';

package/src/worker-runtime/lib/capabilities.ts

@@ -0,0 +1,58 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Worker runtime — capability bits & scheduler contract ──
+//
+// Capability bits describe which optional runtime features a concrete
+// `WorkerRuntime` implementation supports. The composer reads these to
+// decide which platform features are available for a given runtime; a
+// runtime that does NOT support `hotModelSwap` for instance forces the
+// composer to fall back to re-launching the worker on a model change.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { HookKind } from './enums';
+
+/**
+ * Capability bits a worker-runtime implementation exposes. All fields are
+ * required so a runtime cannot accidentally silently mis-declare a feature
+ * by omission.
+ */
+export interface WorkerRuntimeCapabilityBits {
+  /** Can dynamically add/remove MCP services without a restart. */
+  readonly hotMcp: boolean;
+  /** Can swap the active model mid-session without a restart. */
+  readonly hotModelSwap: boolean;
+  /** Can fork an existing session into a sibling. */
+  readonly sessionFork: boolean;
+  /** Supports CRUD on sub-agent bindings during a live session. */
+  readonly subAgentCrud: boolean;
+  /** Lifecycle hooks supported. Empty = no hooks. */
+  readonly hooks: readonly HookKind[];
+  /** Has an in-runtime preview supervisor (long-running dev servers). */
+  readonly previewSupervisor: boolean;
+  /** Tags outbound LLM calls with attribution headers. */
+  readonly gatewayAttributedCalls: boolean;
+  /** Honors a runtime-supplied LLM endpoint override. */
+  readonly llmEndpointOverride: boolean;
+}
+
+/**
+ * Scheduler-side capability bits. The runtime declares which scheduler
+ * features it depends on; the scheduler advertises which it provides. The
+ * composer matches the two — a required capability missing on the
+ * scheduler is a fail-fast error (per plan §D18: no silent degradation).
+ */
+export interface SchedulerCapabilityBits {
+  readonly autoRestart: boolean;
+  readonly healthCheck: boolean;
+  readonly hpa: boolean;
+  readonly networkPolicy: boolean;
+}
+
+/**
+ * A single scheduler capability the runtime asks for. `optional: true`
+ * means the runtime can function without it (degraded path is the
+ * runtime's responsibility, not the scheduler's silent fallback).
+ */
+export interface SchedulerCapabilityRequest {
+  readonly kind: keyof SchedulerCapabilityBits;
+  readonly optional: boolean;
+}

package/src/worker-runtime/lib/enums.ts

@@ -0,0 +1,33 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Worker runtime — closed-domain enums ──
+//
+// Identifiers for worker-runtime implementations and the closed sets of
+// capabilities they may expose. Future runtimes (Claude Code, Copilot CLI,
+// OpenHands, …) will join `WorkerRuntimeKind` here; v1 ships Opencode only.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Identifier of a concrete worker-runtime implementation. v1 ships
+ * Opencode only — additional kinds are reserved for forward compatibility:
+ *
+ *   ClaudeCode  = 'claude-code'
+ *   CopilotCli  = 'copilot-cli'
+ *   OpenHands   = 'open-hands'
+ *
+ * They are intentionally NOT exported yet. The enum is the single source
+ * of truth and consumers must `switch` exhaustively on it.
+ */
+export enum WorkerRuntimeKind {
+  Opencode = 'opencode',
+}
+
+/**
+ * Lifecycle hook surfaces that a runtime may support. The set is closed —
+ * adding a new hook is a kernel change.
+ */
+export enum HookKind {
+  ToolExecuteBefore = 'tool.execute.before',
+  ToolExecuteAfter = 'tool.execute.after',
+  SessionIdle = 'session.idle',
+  SessionStart = 'session.start',
+}

package/src/worker-runtime/lib/messages.ts

@@ -0,0 +1,49 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Worker runtime — user message & event shapes ──
+//
+// Wire-side shapes the composer hands to a runtime's `sendUserMessage`
+// and what the runtime yields back. Discriminated unions are closed —
+// adding a new event kind is a kernel change.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Who is sending a message — a logged-in org member or an external guest
+ * (e.g. anonymous brainstorm participant). Subject ref disambiguates.
+ */
+export interface ActorRef {
+  readonly subjectKind: 'org_user' | 'external_guest';
+  readonly subjectRef: string;
+  readonly displayName: string;
+}
+
+/**
+ * An attachment carried alongside a user message. `value` is the
+ * kind-specific payload: a file/asset URI, an inline image URL/dataurl,
+ * or a plain URL. The runtime decides how to materialize it.
+ */
+export interface Attachment {
+  readonly kind: 'file' | 'image' | 'url';
+  readonly value: string;
+}
+
+/**
+ * A single message handed to the runtime via `sendUserMessage`. The
+ * runtime streams `RuntimeEvent`s back as the model processes the turn.
+ */
+export interface UserMessage {
+  readonly actor: ActorRef;
+  readonly content: string;
+  readonly attachments?: readonly Attachment[];
+}
+
+/**
+ * Closed, discriminated union of events a runtime emits during a turn.
+ * `error.retryable` is REQUIRED so consumers cannot silently retry on a
+ * permanent failure or give up on a transient one.
+ */
+export type RuntimeEvent =
+  | { readonly kind: 'text-delta'; readonly text: string }
+  | { readonly kind: 'tool-use'; readonly tool: string; readonly input: unknown }
+  | { readonly kind: 'tool-result'; readonly tool: string; readonly output: unknown }
+  | { readonly kind: 'turn-end' }
+  | { readonly kind: 'error'; readonly message: string; readonly retryable: boolean };