@xemahq/kernel-contracts 0.1.0

package/src/agent-workspace/lib/endpoint-fetch-spec.ts

@@ -0,0 +1,66 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── ENDPOINT_FETCH deliverable-spec payload ──
+//
+// Shape of the `fetchSpec` column on a DeliverableSpec row with
+// `kind = ENDPOINT_FETCH`. The new `xema/endpoint-fetch@v1` activity
+// (PR B) reads this object, performs one HTTP request per endpoint,
+// and uploads one artifact per response to artifact-store-api.
+//
+// Host allowlist enforcement happens in the activity (same policy
+// surface as `xema/http@v1`) — the spec itself just declares the
+// intended endpoints.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export enum HttpMethod {
+  GET = 'GET',
+  POST = 'POST',
+  PUT = 'PUT',
+  PATCH = 'PATCH',
+  DELETE = 'DELETE',
+  HEAD = 'HEAD',
+  OPTIONS = 'OPTIONS',
+}
+
+export enum FetchOutputKind {
+  /** Store the response body verbatim. */
+  Raw = 'raw',
+  /** Parse JSON + store the parsed value; fails the activity if the response isn't JSON. */
+  Json = 'json',
+  /** Compress + store as binary blob (for large payloads). */
+  Binary = 'binary',
+}
+
+export interface EndpointFetchEntry {
+  /** Human-readable key used as the artifact slug. Unique within the spec. */
+  readonly key: string;
+  /** Absolute URL or `${var}` template resolved from workflow `with:` inputs. */
+  readonly url: string;
+  readonly method: HttpMethod;
+  /**
+   * Optional header bag. Values may reference `${var}` from workflow
+   * inputs; the activity resolves them at dispatch time. Use for simple
+   * auth tokens; sensitive header values should come from a
+   * `headersRef` that points at a secret-manager entry.
+   */
+  readonly headers: Readonly<Record<string, string>> | null;
+  /** Optional pointer to a header-bag secret: `secret://<ref>`. */
+  readonly headersRef: string | null;
+  /** JSON body for POST/PUT/PATCH; `null` for GET/HEAD/OPTIONS. */
+  readonly body: unknown;
+  readonly outputKind: FetchOutputKind;
+  /** Max bytes to store; activity truncates and adds a warning label if exceeded. */
+  readonly maxResponseBytes: number;
+}
+
+export interface EndpointFetchSpec {
+  /** Schema version; bump on breaking changes. */
+  readonly schemaVersion: 1;
+  readonly entries: readonly EndpointFetchEntry[];
+  /**
+   * Maximum concurrency across entries. `null` = sequential; omitting is
+   * the safe default because many target endpoints rate-limit.
+   */
+  readonly maxConcurrency: number | null;
+  /** Per-entry timeout in milliseconds. */
+  readonly timeoutMs: number;
+}

package/src/agent-workspace/lib/manifest.ts

@@ -0,0 +1,53 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── /workspace/deliverables/manifest.json ──
+//
+// Written by unit-worker / coordinator at turn finalization; harvested by
+// the agent activity in PR B. Every page listed here MUST correspond to
+// a file under `/workspace/deliverables/pages/<slug>.md` (or the
+// appropriate extension for non-markdown specs). The orchestrator
+// verifies that correspondence before uploading the pages as artifacts.
+//
+// Extends `packages/platform-common/src/schemas/xema/manifest.json`
+// with: (a) per-page `kind`, (b) `deliverableSpecRef` for traceability,
+// (c) content hashes for retry-determinism checks.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export enum ManifestPageKind {
+  /** Markdown document page produced against a `DOCUMENT_TEMPLATE` spec. */
+  DocumentPage = 'document-page',
+  /** Structured JSON produced against a `ZOD_SCHEMA` or `JSON_SCHEMA` spec. */
+  StructuredJson = 'structured-json',
+  /** Binary asset (e.g. rendered docx, image). */
+  Asset = 'asset',
+  /** Output of a single endpoint fetch for `ENDPOINT_FETCH` specs. */
+  EndpointFetch = 'endpoint-fetch',
+}
+
+export enum ManifestStatus {
+  Complete = 'complete',
+  Partial = 'partial',
+}
+
+export interface ManifestPage {
+  readonly slug: string;
+  readonly title: string;
+  readonly parentSlug: string | null;
+  readonly kind: ManifestPageKind;
+  /** Relative path from `/workspace/deliverables/` to the page file. */
+  readonly path: string;
+  /** Sha256 of the page file contents at write time. */
+  readonly sha256: string;
+  readonly sizeBytes: number;
+}
+
+export interface DeliverableManifest {
+  /** Schema version. 1 = current. Bumping requires migrating the biome finalizer. */
+  readonly schemaVersion: 1;
+  /** Deliverable-spec this manifest satisfies; `null` for generic/custom flows. */
+  readonly deliverableSpecRef: string | null;
+  readonly deliverableSpecVersion: string | null;
+  readonly pages: readonly ManifestPage[];
+  readonly status: ManifestStatus;
+  /** ISO-8601 timestamp the agent wrote this file. */
+  readonly finalizedAt: string;
+}

package/src/agent-workspace/lib/mount-apply.ts

@@ -0,0 +1,79 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Mount apply contract ──
+//
+// Wire types for `POST /workspace/mounts/apply` on `workspace-proxy`. The
+// `OrchestratorAdapter.invoke()` boundary is the only call site; the worker
+// never POSTs directly. See docs/architecture/workspace-proxy-mount-api.md
+// for endpoint contract + lease + staging semantics.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { WorkspaceMount, WorkspaceMountMode, WorkspaceMountPlan } from './workspace-layout';
+
+/**
+ * Actor identity propagated from the dispatching API call all the way
+ * to the resolvers. `workspace-proxy` validates the JWT signature and
+ * matches its claims against `orgId` + `projectId` before invoking any
+ * resolver.
+ *
+ * Resolvers MUST forward `Authorization: Bearer <jwt>` + `X-Org-Id` +
+ * `X-Project-Id` to upstream Orval clients. Cross-tenant access is
+ * impossible without a forged JWT.
+ */
+export interface ActorContext {
+  /** Bearer JWT issued by Keycloak for the workflow-triggering user. */
+  readonly jwt: string;
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly userId: string;
+  /** Correlation id threaded through logs + audit + downstream service calls. */
+  readonly correlationId: string;
+}
+
+export enum MountApplyOutcome {
+  /** Plan was newly applied; bytes written to disk. */
+  Applied = 'applied',
+  /** Lease for this apply key already existed; no work performed. */
+  Idempotent = 'idempotent',
+}
+
+export enum MountApplyEntryStatus {
+  Resolved = 'resolved',
+  Applied = 'applied',
+  Failed = 'failed',
+}
+
+/**
+ * Per-entry result — surfaced to the worker so it can render the
+ * declared/resolved/applied diagnostic view in agent-run-context.
+ *
+ * `identity` is an opaque, scrubbed identifier (e.g. collection id,
+ * spec slug, repo ref) — NEVER a JWT, signed URL, or upstream payload.
+ */
+export interface MountApplyEntryResult {
+  readonly mountKey: string;
+  readonly slot: WorkspaceMount;
+  readonly relPath: string;
+  readonly mode: WorkspaceMountMode;
+  readonly sourceKind: string;
+  readonly identity: string;
+  readonly status: MountApplyEntryStatus;
+  readonly bytesWritten: number;
+  readonly latencyMs: number;
+  /** Present only when `status === Failed`. Closed-enum error code. */
+  readonly errorCode?: string;
+  /** Present only when `status === Failed`. Human-readable, no upstream payload. */
+  readonly errorMessage?: string;
+}
+
+export interface MountApplyRequest {
+  readonly plan: WorkspaceMountPlan;
+  readonly actorContext: ActorContext;
+}
+
+export interface MountApplyResponse {
+  readonly applyId: string;
+  readonly outcome: MountApplyOutcome;
+  readonly entries: readonly MountApplyEntryResult[];
+  readonly totalLatencyMs: number;
+  readonly totalBytesWritten: number;
+}

package/src/agent-workspace/lib/working-file.ts

@@ -0,0 +1,173 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── WorkingFile primitive ──
+//
+// First-class AWP primitive for the "agent edits a single materialised
+// file" pattern. The platform materialises each declared file at the
+// composition-resolved path BEFORE the agent's first turn, surfaces the
+// list on `context.json.workingFiles[]` (introspection) and as env vars
+// (`XEMA_WORKING_FILE_PATH` for the first entry; full JSON in
+// `XEMA_WORKING_FILES_JSON`), and narrows `authority.mayWriteWorkspace`
+// to exactly these paths — write authority becomes a contract, not
+// prompt prose.
+//
+// Source-kind is an OPEN enum: the kernel ships `kb-page` (knowledge-
+// base-api page); biomes extend by registering a new source-kind +
+// shipping a worker-side adapter. The worker's working-file engine
+// dispatches by `sourceKind` — adding "git-file" or "blob" is a new
+// adapter, not a refactor.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wire-format the materialised file is written in. Open list so biomes
+ * may add new formats (e.g. `xlsx`, `mermaid`) — the kernel ships only
+ * the universally-supported text shapes. The agent's edit tool reads the
+ * file as bytes regardless of `format`; the value is informational +
+ * drives the worker's content-type / file-extension projection.
+ */
+export const WORKING_FILE_FORMATS = [
+  'markdown',
+  'html',
+  'json',
+  'yaml',
+  'text',
+] as const;
+export type WorkingFileFormat = (typeof WORKING_FILE_FORMATS)[number];
+
+/**
+ * Closed set of companion-binary formats a working-file binding can
+ * declare via `sourceRef.binaryFormat`. The kb-page adapter reads a
+ * sibling binary at `<dirname(path)>/<slug>.<ext>` after every settle
+ * and pushes it alongside the synopsis so the durable XLSX/PPTX/DOCX/PDF lives
+ * outside the worker container. Closed enum so a new format = adapter +
+ * server enum + this constant; no free-form strings.
+ *
+ * Synopsis-canonical kinds (MD/RICH) MUST NOT declare `binaryFormat` —
+ * the DSL compiler rejects unknown values.
+ */
+export const WORKING_FILE_BINARY_FORMATS = ['xlsx', 'pptx', 'docx', 'pdf'] as const;
+export type WorkingFileBinaryFormat =
+  (typeof WORKING_FILE_BINARY_FORMATS)[number];
+
+const BINARY_FORMAT_EXTENSIONS: Readonly<
+  Record<WorkingFileBinaryFormat, string>
+> = {
+  xlsx: 'xlsx',
+  pptx: 'pptx',
+  docx: 'docx',
+  pdf: 'pdf',
+};
+
+export function workingFileBinaryExtension(
+  format: WorkingFileBinaryFormat,
+): string {
+  return BINARY_FORMAT_EXTENSIONS[format];
+}
+
+export function isWorkingFileBinaryFormat(
+  value: string,
+): value is WorkingFileBinaryFormat {
+  return (WORKING_FILE_BINARY_FORMATS as readonly string[]).includes(value);
+}
+
+/**
+ * File extension projected from `WorkingFileFormat`. Total over the
+ * closed kernel set so a new format addition is a compile-time error.
+ * The worker uses this to pick `<slug>.<ext>` when the composition's
+ * path template omits an explicit extension.
+ */
+const FORMAT_EXTENSIONS: Readonly<Record<WorkingFileFormat, string>> = {
+  markdown: 'md',
+  html: 'html',
+  json: 'json',
+  yaml: 'yaml',
+  text: 'txt',
+};
+
+export function workingFileExtension(format: WorkingFileFormat): string {
+  return FORMAT_EXTENSIONS[format];
+}
+
+/**
+ * Direction the platform syncs the materialised file in.
+ *
+ * - `down-only` — the platform writes the file (from the source); the
+ *   agent may edit but the changes are pushed FROM agent TO source only.
+ *   This is the default; rich documents use it (agent authors, user
+ *   reviews tracked changes, no user co-edit).
+ * - `up-only` — read-only mount of the source content. The agent
+ *   observes but does not write. Reserved for reference materials.
+ * - `bidirectional` — co-edit. Either side may write; the platform's
+ *   adapter merges concurrent edits. Markdown documents use it (user
+ *   types in the editor, agent edits the working file, the merge falls
+ *   out of the document-sync loop).
+ */
+export const WORKING_FILE_SYNC_DIRECTIONS = [
+  'down-only',
+  'up-only',
+  'bidirectional',
+] as const;
+export type WorkingFileSyncDirection =
+  (typeof WORKING_FILE_SYNC_DIRECTIONS)[number];
+
+/**
+ * Source the working file is materialised from. Open list — the kernel
+ * ships only `kb-page`; biomes may register additional kinds + ship a
+ * matching worker-side adapter. The platform validates that the string
+ * is non-empty and snake_case so new kinds cannot accidentally collide.
+ *
+ * Kernel-shipped kinds:
+ *   - `kb-page` — knowledge-base-api page. `sourceRef` carries
+ *     `{ pageId, versionId }` (versionId pins the base content).
+ */
+export type WorkingFileSourceKind = string;
+
+/**
+ * Resolved working-file declaration projected onto the WorkspaceSpec and
+ * carried into the session bundle. Composition authors declare the
+ * authored shape (with `${input.x}` templating); resolution produces this
+ * concrete form with the bind inputs interpolated.
+ *
+ * INVARIANTS the worker engine relies on:
+ *   - `path` is `/workspace/`-relative (no leading `/`, no `..` segments).
+ *     The DSL schema enforces this at compile time.
+ *   - `slug` is the human-stable identifier the agent sees; it MUST
+ *     match the file's basename (sans extension) so the agent's mental
+ *     model of `<slug>` and the on-disk file path stay aligned.
+ *   - `sourceKind` is a non-empty snake_case string registered with the
+ *     worker's working-file engine. Unknown kinds fail-fast at bundle
+ *     apply — silent skip would let the agent boot without its file.
+ *   - `sourceRef` is the kind-specific reference bag. Adapters re-
+ *     validate their own required keys; the kernel only enforces that
+ *     the bag is a string→string map.
+ */
+export interface WorkingFileBinding {
+  /** Human-stable identifier the agent sees (matches file basename). */
+  readonly slug: string;
+  /**
+   * Workspace-relative path the file is materialised at. Combined with
+   * `/workspace/` to form the on-disk absolute path inside the worker
+   * container.
+   */
+  readonly path: string;
+  readonly format: WorkingFileFormat;
+  readonly syncDirection: WorkingFileSyncDirection;
+  readonly sourceKind: WorkingFileSourceKind;
+  /**
+   * Kind-specific reference bag. The worker's adapter for `sourceKind`
+   * reads the required keys (e.g. `pageId`, `versionId` for `kb-page`).
+   * Values are stringified at the composition layer so the wire shape is
+   * uniform — adapters parse / coerce as needed.
+   */
+  readonly sourceRef: Readonly<Record<string, string>>;
+}
+
+/**
+ * Authored shape — same as the resolved binding but path / sourceRef
+ * values may carry `${input.x}` interpolation tokens. The composition
+ * resolution pass (in `agent-session-runtime` / `workflow-runtime-worker`)
+ * produces the resolved form by walking the strings with `interpolate`.
+ *
+ * Re-uses the resolved interface because the difference is purely
+ * lexical: the field set + types are identical.
+ */
+export type WorkingFileBindingInput = WorkingFileBinding;

package/src/agent-workspace/lib/workspace-layout.ts

@@ -0,0 +1,106 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Unified Xema workspace layout ──
+//
+// Every agent session runs inside a `/workspace/` tree with a fixed set of
+// top-level mounts. Enforced at mount time by `workspace-proxy` and
+// surfaced to the agent through `/workspace/AGENTS.md` +
+// `/workspace/context.json`. These types are the TypeScript mirror of the
+// runtime contract documented at
+// `opencode-worker-config/runtime/AGENTS.md` §Workspace layout — the
+// prose and the enum must stay in sync. Any new top-level mount goes in
+// BOTH places in the same PR.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { MountSource } from '../../workflow';
+
+/**
+ * Top-level workspace mounts. Closed set — workspace-proxy rejects any
+ * mount request that isn't one of these keys. The values are the
+ * absolute paths inside the agent's container.
+ */
+export enum WorkspaceMount {
+  AgentsMd = '/workspace/AGENTS.md',
+  ContextJson = '/workspace/context.json',
+  SystemOverlay = '/workspace/.xema/system-overlay.md',
+  Inputs = '/workspace/inputs',
+  Tmp = '/workspace/tmp',
+  Deliverables = '/workspace/deliverables',
+  DeliverableSpecs = '/workspace/deliverable-specs',
+  References = '/workspace/references',
+  Repos = '/workspace/repos',
+  Uploads = '/workspace/uploads',
+  AgentBundles = '/workspace/.opencode/agents',
+  SkillBundles = '/workspace/.opencode/skills',
+  Commands = '/workspace/.opencode/command',
+  Instructions = '/workspace/.xema/instructions',
+}
+
+// `WorkspaceRole` is the role the running session takes. The canonical
+// values + helpers live in `@xemahq/workflow-contracts:agent-role` —
+// re-exported here as `WorkspaceRole` for back-compat with consumers
+// that imported from this module. New code should import `AgentRunRole`
+// directly from `@xemahq/workflow-contracts`.
+export {
+  AGENT_RUN_ROLES as WORKSPACE_ROLES,
+  AGENT_RUN_ROLES_INTERACTIVE as WORKSPACE_ROLES_INTERACTIVE,
+  AGENT_RUN_ROLES_PIPELINE as WORKSPACE_ROLES_PIPELINE,
+  isAgentRunRole as isWorkspaceRole,
+  type AgentRunRole as WorkspaceRole,
+} from '../../workflow';
+
+/**
+ * Mount mode the worker requests. Read-only mounts are `chmod a-w` at
+ * attach-time so the kernel enforces immutability; writable mounts
+ * accept agent writes (off-manifest writes are simply ignored by the
+ * deliverable harvester).
+ */
+export enum WorkspaceMountMode {
+  ReadOnly = 'read-only',
+  ReadWrite = 'read-write',
+}
+
+/**
+ * Single mount-plan entry. The worker emits one of these per logical
+ * mount declared in the workflow YAML; `workspace-proxy` resolves
+ * `source` against the registered `MountResolver` and writes bytes onto
+ * disk under `${slot}/${relPath}` with the requested mode.
+ *
+ * `source` is a typed discriminator (see `MountSource` in
+ * `@xemahq/workflow-contracts`) — never an opaque URI string.
+ * Unknown discriminator values fail-fast at the proxy.
+ */
+export interface WorkspaceMountPlanEntry {
+  /**
+   * Opaque key the worker assigned to this mount, used for diagnostics
+   * + idempotency-aware deduplication of identical entries within an
+   * apply. e.g. `references.kb`, `repos.<repoName>`, `inputs`.
+   */
+  readonly mountKey: string;
+  /** Top-level workspace slot. Closed enum. */
+  readonly slot: WorkspaceMount;
+  /**
+   * Relative path within the slot (no leading `/`, no `..`). Empty
+   * string means "the slot root". Validated against the slot's allowed
+   * sub-slots from `WorkspaceSpec` at the proxy.
+   */
+  readonly relPath: string;
+  readonly mode: WorkspaceMountMode;
+  readonly source: MountSource;
+}
+
+/**
+ * The full mount plan delivered to workspace-proxy ahead of the session
+ * start. `workspace-proxy` materializes the tree atomically per slot;
+ * partial failures roll back staging so the agent never sees a
+ * half-mounted workspace.
+ */
+export interface WorkspaceMountPlan {
+  /**
+   * Stable identifier for this apply attempt. Used by `workspace-proxy`
+   * to scope the staging directory + lease key. Must be unique per
+   * `(orgId, projectId, runId, stepId, logicalAttempt)` tuple — typically
+   * a sha256 of those.
+   */
+  readonly applyId: string;
+  readonly entries: readonly WorkspaceMountPlanEntry[];
+}