@xemahq/kernel-contracts 0.1.0

package/src/agent-workspace/lib/agent-tool-defaults.ts

@@ -0,0 +1,252 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent permission defaults — single source of truth ──
+//
+// OpenCode unified the legacy `tools: { name: boolean }` and `permission:
+// { name: 'allow' | 'ask' | 'deny' }` surfaces into a single `permission`
+// surface (see opencode `packages/opencode/src/config/permission.ts` and
+// the deprecation notice in `packages/opencode/src/config/agent.ts`).
+//
+// Every agent's effective permission map is the union of:
+//
+//   1. SYSTEM_REQUIRED_PERMISSIONS — pinned to `allow`; the manifest
+//      cannot deny them. The bare minimum any agent needs to read the
+//      workspace, plan its work, and grep through context.
+//   2. SYSTEM_DEFAULT_PERMISSIONS — `allow` unless the manifest
+//      explicitly downgrades. Cover edit (which subsumes write/patch in
+//      OpenCode), bash, task delegation, and skill invocation.
+//   3. SYSTEM_OPT_IN_PERMISSIONS — `deny` unless the manifest explicitly
+//      opts in. Surfaces with cost / network / interactive blast radius
+//      (webfetch, websearch, doom_loop) plus the `question` tool (which
+//      only works when there's a UI surface to answer).
+//
+// `resolveAgentPermissions` merges a manifest's permission declaration
+// with the three tiers, returning the closed map the agent runtime
+// should expose. `assertNoRequiredPermissionsDenied` is the validator
+// the registry layer runs at write time so a malformed manifest fails
+// fast.
+//
+// This module is the single source of truth — bundle services, render
+// pipelines, and authoring previews all merge through this function.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Permission keys that take a `Rule` shape — either a scalar action or
+ * a per-target map (e.g. `bash: { '*': 'allow', 'rm -rf *': 'deny' }`,
+ * `task: { 'html-builder': 'allow' }`, `external_directory: { '/**':
+ * 'allow' }`). Mirrors OpenCode's `permission.ts` `InputObject`.
+ */
+const KNOWN_RULE_PERMISSION_KEYS = [
+  'read',
+  'edit',
+  'glob',
+  'grep',
+  'list',
+  'bash',
+  'task',
+  'external_directory',
+  'lsp',
+  'skill',
+] as const;
+
+/**
+ * Permission keys that take a scalar `Action` only (no per-target map).
+ * Mirrors OpenCode's `permission.ts` `InputObject`.
+ */
+const KNOWN_ACTION_PERMISSION_KEYS = [
+  'todowrite',
+  'question',
+  'webfetch',
+  'websearch',
+  'doom_loop',
+] as const;
+
+export const KNOWN_PERMISSION_KEYS = [
+  ...KNOWN_RULE_PERMISSION_KEYS,
+  ...KNOWN_ACTION_PERMISSION_KEYS,
+] as const;
+
+export type PermissionKey = (typeof KNOWN_PERMISSION_KEYS)[number];
+
+export type PermissionAction = 'allow' | 'ask' | 'deny';
+
+/**
+ * A permission entry is either a scalar action or a per-target map. The
+ * map form is supported only for the keys in `KNOWN_RULE_PERMISSION_KEYS`
+ * — the action-only keys reject map shapes at the OpenCode schema layer.
+ * Catch-all entries (MCP tool names, biome-emitted globs) live alongside
+ * the closed set; their shape is validated by OpenCode at config load.
+ */
+export type PermissionRule = PermissionAction | Readonly<Record<string, PermissionAction>>;
+
+/**
+ * Full permission map. Closed-set keys carry typed rules; the index
+ * signature accommodates MCP tool names and biome-emitted glob patterns
+ * (e.g. `xema_*`, `emit*`) that OpenCode resolves via its catch-all
+ * `Schema.Record(Schema.String, Rule)` in `permission.ts`.
+ */
+export type PermissionMap = Readonly<Record<string, PermissionRule>>;
+
+/**
+ * Permissions every agent gets — manifests cannot deny them. Removing
+ * one here makes the agent unable to perform a fundamental observation
+ * / planning operation, so the validator rejects manifests that try.
+ */
+export const SYSTEM_REQUIRED_PERMISSIONS: Readonly<Partial<Record<PermissionKey, PermissionAction>>> = {
+  read: 'allow',
+  list: 'allow',
+  glob: 'allow',
+  grep: 'allow',
+  todowrite: 'allow',
+};
+
+/**
+ * Permissions enabled by default. A manifest can downgrade any of these
+ * to `ask` or `deny` by setting the matching key. They're "system-
+ * suggested defaults", not invariants.
+ */
+export const SYSTEM_DEFAULT_PERMISSIONS: Readonly<Partial<Record<PermissionKey, PermissionAction>>> = {
+  edit: 'allow',
+  bash: 'allow',
+  task: 'allow',
+  skill: 'allow',
+};
+
+/**
+ * Permissions denied by default. A manifest must explicitly set the key
+ * to `allow` (or a per-target map) to enable them. These are surfaces
+ * with non-trivial blast radius — billing (network calls), interactivity
+ * (questions to a UI that may not exist in pipeline runs), filesystem
+ * escape (external_directory), unbounded execution (doom_loop), and
+ * editor protocol I/O (lsp).
+ */
+export const SYSTEM_OPT_IN_PERMISSIONS: Readonly<Partial<Record<PermissionKey, PermissionAction>>> = {
+  question: 'deny',
+  webfetch: 'deny',
+  websearch: 'deny',
+  doom_loop: 'deny',
+  external_directory: 'deny',
+  lsp: 'deny',
+};
+
+/**
+ * Manifest-supplied permission declaration. Optional — a manifest with
+ * no `permission:` block at all is valid (it just inherits defaults).
+ */
+export interface AgentPermissionDeclaration {
+  readonly permission?: PermissionMap;
+}
+
+/**
+ * Resolved permission map the runtime should expose to the agent. Every
+ * known closed-set key has an explicit entry; additional catch-all keys
+ * (MCP tool names, biome globs) the manifest declared are preserved
+ * verbatim.
+ */
+export interface ResolvedAgentPermissions {
+  readonly permission: Readonly<Record<string, PermissionRule>>;
+}
+
+/**
+ * Merge a manifest's permission declaration with the system tiers.
+ *
+ * Precedence (highest to lowest):
+ *   1. SYSTEM_REQUIRED_PERMISSIONS — always `allow`, override anything below.
+ *   2. Manifest declaration — when the manifest names a key, that wins.
+ *   3. SYSTEM_DEFAULT_PERMISSIONS / SYSTEM_OPT_IN_PERMISSIONS — fill gaps.
+ *
+ * `assertNoRequiredPermissionsDenied` should be called separately at
+ * registration time — `resolveAgentPermissions` *silently* upgrades
+ * denied required keys back to `allow` so a misconfigured manifest still
+ * produces a runnable workspace.
+ *
+ * Catch-all keys the manifest authored (e.g. `xema_*`, MCP tool names)
+ * are preserved verbatim — they live alongside the closed set in the
+ * resolved map.
+ */
+export function resolveAgentPermissions(
+  manifest: AgentPermissionDeclaration | undefined,
+): ResolvedAgentPermissions {
+  const out: Record<string, PermissionRule> = {};
+  for (const key of KNOWN_PERMISSION_KEYS) {
+    out[key] = resolveClosedSetPermission(key, manifest?.permission?.[key]);
+  }
+  // Layer catch-all entries the manifest declared (MCP tool names,
+  // biome glob patterns). Closed-set keys were merged above; required
+  // keys are pinned and can't be overridden by a catch-all entry of the
+  // same name.
+  if (manifest?.permission) {
+    for (const [key, value] of Object.entries(manifest.permission)) {
+      if (key in SYSTEM_REQUIRED_PERMISSIONS) {continue;}
+      if ((KNOWN_PERMISSION_KEYS as readonly string[]).includes(key)) {continue;}
+      out[key] = value;
+    }
+  }
+  return { permission: out };
+}
+
+/**
+ * Resolve a single closed-set permission key by walking the three tiers
+ * — required → manifest → default → opt-in. Extracted so
+ * `resolveAgentPermissions` stays under the cognitive-complexity ceiling.
+ */
+function resolveClosedSetPermission(
+  key: PermissionKey,
+  fromManifest: PermissionRule | undefined,
+): PermissionRule {
+  if (key in SYSTEM_REQUIRED_PERMISSIONS) {
+    return SYSTEM_REQUIRED_PERMISSIONS[key]!;
+  }
+  if (fromManifest !== undefined) {
+    return fromManifest;
+  }
+  if (key in SYSTEM_DEFAULT_PERMISSIONS) {
+    return SYSTEM_DEFAULT_PERMISSIONS[key]!;
+  }
+  return SYSTEM_OPT_IN_PERMISSIONS[key] ?? 'deny';
+}
+
+/**
+ * Validation guard for the registry layer. Throws when a manifest tries
+ * to deny a `SYSTEM_REQUIRED_PERMISSIONS` entry — fail-fast at
+ * registration so a misconfigured manifest never reaches the renderer.
+ *
+ * A Rule-shaped value (per-target map) for a required key counts as
+ * denied only when every entry is `deny` — partial denials (e.g.
+ * `read: { '/etc/**': 'deny', '*': 'allow' }`) are allowed because the
+ * agent retains at least one allow path.
+ */
+export function assertNoRequiredPermissionsDenied(
+  declaration: AgentPermissionDeclaration | undefined,
+): void {
+  if (!declaration?.permission) {return;}
+  const denied: PermissionKey[] = [];
+  for (const key of Object.keys(SYSTEM_REQUIRED_PERMISSIONS) as PermissionKey[]) {
+    const v = declaration.permission[key];
+    if (v === 'deny') {
+      denied.push(key);
+      continue;
+    }
+    if (v !== undefined && typeof v === 'object') {
+      const entries = Object.values(v);
+      if (entries.length > 0 && entries.every((a) => a === 'deny')) {
+        denied.push(key);
+      }
+    }
+  }
+  if (denied.length > 0) {
+    throw new AgentPermissionsValidationError(
+      `agent manifest denies system-required permission(s) [${denied.join(', ')}]; these must remain 'allow'`,
+      denied,
+    );
+  }
+}
+
+export class AgentPermissionsValidationError extends Error {
+  constructor(
+    message: string,
+    readonly deniedRequiredPermissions: ReadonlyArray<PermissionKey>,
+  ) {
+    super(message);
+    this.name = 'AgentPermissionsValidationError';
+  }
+}

package/src/agent-workspace/lib/awp-v1.ts

@@ -0,0 +1,289 @@
+import {
+  GitPushBranchSuffix,
+  GitPushConcurrencyMode,
+  SlotMode,
+  type WorkspaceSpec,
+} from './workspace-spec';
+
+/**
+ * Canonical AWP v1 spec — the seed every Xema workspace starts from.
+ * Biomes may overlay additive slots/sub-slots at platform boot through
+ * `WorkspaceSpecRegistry` (Epoch 3+); the base set declared here cannot
+ * be dropped or modified.
+ *
+ * Platform-owned slots — `agents-md`, `context-json`, `agent-bundles`,
+ * `skill-bundles`, `instructions` — are populated from platform-rendered
+ * sources (llm-registry-api). They land in the same mount-apply pipeline
+ * as user-data slots, so every byte under `/workspace/` flows through one
+ * typed substrate. `.opencode/opencode.jsonc` and `.opencode/biomes/`
+ * remain adapter-generated by `@xemahq/agent-workspace-opencode` and
+ * are NOT slots.
+ */
+export const AWP_V1_SPEC: WorkspaceSpec = {
+  id: 'awp/v1',
+  version: '1.2.0',
+  slots: [
+    {
+      key: 'inputs',
+      path: '/workspace/inputs',
+      presence: 'always',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'user',
+      humanDescription:
+        "Read-only inputs supplied at session/run start (the workflow's `with:` block or the session's customConfig). The DSL input bag lands at `inputs.json`.",
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // Scratch / working memory area for the agent. Persisted via tarball
+      // so retries can read prior drafts. Never harvested as deliverable
+      // output. Never written by the platform.
+      key: 'tmp',
+      path: '/workspace/tmp',
+      presence: 'always',
+      allowedModes: [SlotMode.ReadWrite],
+      defaultMode: SlotMode.ReadWrite,
+      ownership: 'user',
+      humanDescription:
+        'Your scratch space — drafts, intermediate computation, working notes. Snapshot-persisted so retries see prior state. Never harvested.',
+      persistencePolicy: { kind: 'tarball' },
+    },
+    {
+      key: 'uploads',
+      path: '/workspace/uploads',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'user',
+      humanDescription:
+        'User-uploaded files (briefs, screenshots, sketches). Read-only — never write here.',
+      persistencePolicy: { kind: 'tarball' },
+    },
+    {
+      key: 'references',
+      path: '/workspace/references',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'user',
+      humanDescription:
+        'Curated evidence library (knowledge-base spaces, prior artifacts, external project mounts). Read-only.',
+      persistencePolicy: { kind: 'none' },
+      subSlots: [
+        {
+          key: 'kb',
+          path: '/workspace/references/kb',
+          allowedModes: [SlotMode.ReadOnly],
+          defaultMode: SlotMode.ReadOnly,
+          ownership: 'user',
+        },
+        {
+          key: 'external-projects',
+          path: '/workspace/references/external-projects',
+          allowedModes: [SlotMode.ReadOnly],
+          defaultMode: SlotMode.ReadOnly,
+          ownership: 'user',
+        },
+      ],
+    },
+    {
+      key: 'deliverable-specs',
+      path: '/workspace/deliverable-specs',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'user',
+      humanDescription:
+        'Schemas + metadata for the deliverable spec(s) this run targets. Read-only — consult before writing under deliverables/.',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      key: 'deliverables',
+      path: '/workspace/deliverables',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly, SlotMode.ReadWrite],
+      defaultMode: SlotMode.ReadWrite,
+      ownership: 'user',
+      humanDescription:
+        "Your writable output area. Files written here are harvested by the runtime per the deliverable spec's contract.",
+      persistencePolicy: { kind: 'tarball' },
+    },
+    {
+      // Top-level read-write SCM checkout(s). Defaults to ReadOnly so
+      // non-engineering roles get the codebase as reference; the workflow
+      // grants ReadWrite explicitly when an engineer-style action needs
+      // to author commits.
+      key: 'repos',
+      path: '/workspace/repos',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly, SlotMode.ReadWrite],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'user',
+      humanDescription:
+        'Project repositories. Read-only unless the workflow explicitly granted write authority (engineer roles only).',
+      persistencePolicy: { kind: 'git-push', branchPrefix: 'xema/session/' },
+    },
+    // ── Platform-rendered slots (composer auto-emits from agent slug) ──
+    {
+      // `/workspace/AGENTS.md` — root agent definition + rules. Single
+      // file, OpenCode-discovered at session start. Renderer in
+      // llm-registry-api `agent-run-context/render`.
+      key: 'agents-md',
+      path: '/workspace/AGENTS.md',
+      presence: 'always',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      singleFile: true,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // `/workspace/context.json` — invocation identity + pointers
+      // (orgId, projectId, runId/sessionId, role, deliverable spec).
+      // Single file, consumed by xema biome tools at runtime.
+      key: 'context-json',
+      path: '/workspace/context.json',
+      presence: 'always',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      singleFile: true,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // `/workspace/.xema/system-overlay.md` — the LLM-readable Xema
+      // platform contract for this run (AWP base + deliverable contract +
+      // authority + retry). Consumed by the xema biome's
+      // `experimental.chat.system.transform` hook, appended to the
+      // OpenCode system layer. Hidden from agent tools by the authority
+      // guard; agents see its content via the system prompt, not the
+      // filesystem.
+      key: 'system-overlay',
+      path: '/workspace/.xema/system-overlay.md',
+      presence: 'always',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      singleFile: true,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // `/workspace/.opencode/agents/` — primary agent + delegated
+      // sub-agents. OpenCode discovers <slug>.md files here. Sub-agents
+      // share this directory; frontmatter `mode: subagent` differentiates
+      // them. https://opencode.ai/docs/agents/
+      key: 'agent-bundles',
+      path: '/workspace/.opencode/agents',
+      presence: 'always',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // `/workspace/.opencode/skills/<key>/SKILL.md` — folder-per-skill
+      // layout per OpenCode convention. https://opencode.ai/docs/skills/
+      key: 'skill-bundles',
+      path: '/workspace/.opencode/skills',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // `/workspace/.opencode/command/<skill>.md` — one slash-command
+      // file per scoped skill, so `/<skill>` works natively in OpenCode.
+      // The composer emits these as static-literal entries from the
+      // agent's resolved skill set. https://opencode.ai/docs/commands/
+      key: 'commands',
+      path: '/workspace/.opencode/command',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+    {
+      // `/workspace/.xema/instructions/` — instruction sections. Auto-
+      // discovered by OpenCode via the static `instructions` glob in
+      // base `opencode.jsonc`. Lives outside `.opencode/` since
+      // OpenCode's `instructions` field accepts arbitrary globs and
+      // `.opencode/` is its own namespace.
+      key: 'instructions',
+      path: '/workspace/.xema/instructions',
+      presence: 'optional',
+      allowedModes: [SlotMode.ReadOnly],
+      defaultMode: SlotMode.ReadOnly,
+      ownership: 'platform',
+      persistencePolicy: { kind: 'none' },
+    },
+  ],
+};
+
+/**
+ * Lookup helpers — kept on the spec module so consumers don't reinvent
+ * them per-package.
+ */
+export function findSlot(spec: WorkspaceSpec, key: string) {
+  return spec.slots.find((s) => s.key === key);
+}
+
+export function isKnownSlotKey(spec: WorkspaceSpec, key: string): boolean {
+  return spec.slots.some((s) => s.key === key);
+}
+
+export function listAlwaysOnSlotKeys(spec: WorkspaceSpec): readonly string[] {
+  return spec.slots.filter((s) => s.presence === 'always').map((s) => s.key);
+}
+
+/**
+ * Slots that the snapshot pipeline captures as per-path tarballs in MinIO.
+ * Returned as the relPath segment under `/workspace/` (e.g. `'deliverables'`)
+ * so callers can pass the list directly as `workspaceInclude=` query
+ * params on `GET /session/snapshot`.
+ */
+export function listTarballPersistedRelPaths(spec: WorkspaceSpec): readonly string[] {
+  return spec.slots
+    .filter((s) => s.persistencePolicy?.kind === 'tarball')
+    .map((s) => s.path.replace(/^\/workspace\//, ''));
+}
+
+/**
+ * Resolved view of a `git-push` slot policy. `branchSuffix` and
+ * `concurrencyMode` are always present here (resolved to enum defaults
+ * when the policy left them implicit) so downstream callers never have
+ * to repeat the default-resolution logic.
+ */
+export interface ResolvedGitPushSlot {
+  readonly key: string;
+  readonly path: string;
+  readonly branchPrefix: string;
+  readonly branchSuffix: GitPushBranchSuffix;
+  readonly concurrencyMode: GitPushConcurrencyMode;
+}
+
+/**
+ * Slots persisted via `git push` to a branch on the SCM remote. Used by
+ * the workspace-proxy `/workspace/repos/*-session-branch` endpoints to
+ * know which slots to walk and how to shape the branch name.
+ */
+export function listGitPushPersistedSlots(
+  spec: WorkspaceSpec,
+): readonly ResolvedGitPushSlot[] {
+  const out: ResolvedGitPushSlot[] = [];
+  for (const slot of spec.slots) {
+    if (slot.persistencePolicy?.kind === 'git-push') {
+      out.push({
+        key: slot.key,
+        path: slot.path,
+        branchPrefix: slot.persistencePolicy.branchPrefix,
+        branchSuffix:
+          slot.persistencePolicy.branchSuffix ?? GitPushBranchSuffix.SessionId,
+        concurrencyMode:
+          slot.persistencePolicy.concurrencyMode ?? GitPushConcurrencyMode.Force,
+      });
+    }
+  }
+  return out;
+}

package/src/agent-workspace/lib/context-json.ts

@@ -0,0 +1,92 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── /workspace/context.json ──
+//
+// Authored once per session by llm-registry-api's agent-run-context
+// renderer. Read by the opencode-xema-plugin at hook time and by the
+// agent at session start. Its shape is normative: the biome validates
+// it with a Zod schema; validation failure causes the hook to skip.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { AgentRunRole, InvocationSurface, WritePolicy } from '../../workflow';
+
+import type { WorkingFileBinding } from './working-file';
+
+// Re-export so consumers reading `context.json` need only this module.
+export type { WorkingFileBinding };
+
+/**
+ * Re-exports for downstream consumers — `InvocationRole` is the
+ * runtime/agent-side alias for `AgentRunRole`.
+ */
+export type InvocationRole = AgentRunRole;
+export type { InvocationSurface, WritePolicy };
+
+/**
+ * Per-invocation identity carried inside the `invocation` top-level key.
+ */
+export interface ContextInvocation {
+  readonly role: InvocationRole;
+  readonly surface: InvocationSurface;
+  readonly attempt: number;
+  readonly runId: string | null;
+  readonly groupKey: string | null;
+  readonly sessionId: string | null;
+}
+
+/**
+ * `authority` carries the biome-enforced write capabilities. The xema
+ * biome reads these at tool invocation time and rejects any write
+ * outside the declared paths / slugs.
+ */
+export interface ContextAuthority {
+  /** Absolute paths inside `/workspace/` the agent may write to. */
+  readonly mayWriteWorkspace: readonly string[];
+  /** Deliverable slugs the agent may create pages under. */
+  readonly mayWriteSlugs: readonly string[];
+  /** Whether the agent may publish pages into the project KB space. */
+  readonly mayWriteKnowledgeBase: boolean;
+  /** Whether the agent may edit files under `/workspace/repos/`. */
+  readonly mayEditRepos: boolean;
+  /** Closed-enum write-policy from the role's capability profile. */
+  readonly writePolicy: WritePolicy;
+  /**
+   * Xema-namespaced tool names this invocation may call. Sourced from
+   * the role's `RoleCapabilityProfile` (resolved by llm-registry-api
+   * from `biomes/kernel/runtime/role-capabilities/<role>.role-capability.yaml`).
+   * The opencode-xema-plugin's `ensureRoleAllowed` check rejects any
+   * Xema tool call whose name is not in this list.
+   */
+  readonly allowedXemaTools: readonly string[];
+}
+
+export interface ContextProjectIdentity {
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly pipelineBranch: string | null;
+}
+
+/**
+ * Working-file declaration projected onto `context.json` for agent
+ * introspection. The opencode-xema biome reads this list at hook time
+ * so the agent's tool-call layer can resolve `$XEMA_WORKING_FILE_PATH`
+ * back to the declarative source (which `slug`, which `sourceKind`)
+ * without re-reading the env. Empty array when the composition declared
+ * no working files.
+ */
+export type ContextWorkingFile = WorkingFileBinding;
+
+export interface ContextJson {
+  readonly invocation: ContextInvocation;
+  readonly project: ContextProjectIdentity;
+  readonly authority: ContextAuthority;
+  readonly resolvedAgentSnapshotHash: string;
+  /**
+   * Working files materialised by the platform for this session.
+   * `authority.mayWriteWorkspace` already narrows write authority to
+   * each binding's `path`; this list lets the agent + biome layer see
+   * the structured metadata (slug, format, sourceKind) the platform
+   * resolved from the composition's declarative `workspace.workingFiles`
+   * block.
+   */
+  readonly workingFiles: readonly ContextWorkingFile[];
+}

package/src/agent-workspace/lib/deliverable-spec-ref.ts

@@ -0,0 +1,60 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Deliverable-spec ref parsing ──
+//
+// Workflow YAMLs reference specs by `<slug>[@<version>]` strings
+// (examples: `requirements-standard`, `architecture-standard@1.2.0`).
+// The parser is strict: invalid refs fail at compile time, never at
+// runtime. This is a shared utility so every consumer (compiler,
+// activities, llm-registry-api's renderer) parses refs the same way.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ParsedDeliverableSpecRef {
+  readonly slug: string;
+  /** `null` means "latest active version"; the spec service resolves it. */
+  readonly version: string | null;
+}
+
+const SLUG_PATTERN = /^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+
+export class DeliverableSpecRefError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DeliverableSpecRefError';
+  }
+}
+
+/**
+ * Parses a `slug` or `slug@version` string. Throws
+ * `DeliverableSpecRefError` when either side fails the format check. The
+ * slug allows `category/name` shapes (e.g. `microservice-design/standard`)
+ * so we can group specs without a separate Prisma column.
+ */
+export function parseDeliverableSpecRef(raw: string): ParsedDeliverableSpecRef {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    throw new DeliverableSpecRefError(
+      `Deliverable-spec ref must be a non-empty string; got ${JSON.stringify(raw)}.`,
+    );
+  }
+  const atIndex = raw.indexOf('@');
+  const slug = atIndex === -1 ? raw : raw.slice(0, atIndex);
+  const version = atIndex === -1 ? null : raw.slice(atIndex + 1);
+
+  if (!SLUG_PATTERN.test(slug)) {
+    throw new DeliverableSpecRefError(
+      `Deliverable-spec slug '${slug}' is not a valid kebab/path slug.`,
+    );
+  }
+  if (version !== null && !SEMVER_PATTERN.test(version)) {
+    throw new DeliverableSpecRefError(
+      `Deliverable-spec version '${version}' must be semver (MAJOR.MINOR.PATCH).`,
+    );
+  }
+  return { slug, version };
+}
+
+export function formatDeliverableSpecRef(
+  parsed: ParsedDeliverableSpecRef,
+): string {
+  return parsed.version === null ? parsed.slug : `${parsed.slug}@${parsed.version}`;
+}