@xemahq/biome-sdk 0.1.1

package/src/agent-workspace/lib/resolvers/clients.ts

@@ -0,0 +1,297 @@
+import type { Readable } from 'node:stream';
+import type { AuthHeaders } from './utils/auth';
+
+// ─── Narrow client interfaces ────────────────────────────────────────────────
+//
+// The kernel SDK never imports a concrete Orval client; consumers
+// (workspace-proxy) provide implementations that delegate to the real
+// clients with per-call header forwarding.
+//
+// Each interface is intentionally minimal — only the calls the matching
+// resolver needs. Adding a method to satisfy a new resolver requires
+// extending both the interface AND the workspace-proxy implementation
+// in lockstep. CI boundary check (epoch 6) keeps the kernel free of
+// service imports.
+
+export interface ArtifactBlobMetadata {
+  /** Path the blob should land at, relative to the entry's slot+relPath. */
+  readonly relPath: string;
+  /** Optional content size hint; resolvers thread it as `sizeHint`. */
+  readonly sizeBytes: number | undefined;
+}
+
+export interface ArtifactCollectionStream {
+  readonly blobs: AsyncIterable<{
+    readonly metadata: ArtifactBlobMetadata;
+    readonly stream: Readable;
+  }>;
+}
+
+export interface ArtifactVersionContent {
+  /** Bytes for the resolver to write at the mount entry's path. */
+  readonly bytes: Uint8Array;
+  /** Resolved content type (from the artifact metadata when available). */
+  readonly contentType: string | undefined;
+}
+
+export interface ArtifactStoreClient {
+  /**
+   * Stream every blob in a collection. Implementations MUST forward
+   * `headers` verbatim to the upstream service so org-scoping is
+   * enforced at the upstream (not this layer).
+   */
+  streamCollection(
+    collectionId: string,
+    headers: AuthHeaders,
+  ): Promise<ArtifactCollectionStream>;
+  /**
+   * Fetch a single artifact version and materialise its content.
+   *
+   * If `payloadField` is set, the implementation extracts that field
+   * from the artifact's JSON payload and returns its bytes — the field
+   * value MUST be a string (`utf-8` is assumed). If unset, the entire
+   * payload is serialised as pretty-printed JSON.
+   *
+   * Fails fast on a missing/wrong-typed `payloadField` so an authoring
+   * mistake surfaces as a typed mount error rather than a stringified
+   * `[object Object]` landing on disk.
+   */
+  fetchVersionContent(
+    artifactId: string,
+    version: number,
+    payloadField: string | undefined,
+    headers: AuthHeaders,
+  ): Promise<ArtifactVersionContent>;
+}
+
+export interface KbPageBundle {
+  /** Combined, ordered markdown stream of every page in the space. */
+  readonly readable: Readable;
+  /** Optional total content size hint (sum of pages) when known. */
+  readonly sizeBytes: number | undefined;
+}
+
+/**
+ * Materialised content of a single KB page. Used by the `kb-pages`
+ * resolver to land individual pages as separate files under the
+ * `references/kb/<spaceId>/` slot — distinct from the bundled
+ * `kb-space` flow which produces a single `space.md`.
+ */
+export interface KbPageContent {
+  /** Page slug (kebab-case). Used as the on-disk filename stem. */
+  readonly slug: string;
+  /** Page title (informational; carried for diagnostics). */
+  readonly title: string;
+  /** Raw markdown bytes (utf-8). */
+  readonly body: string;
+}
+
+export interface KbClient {
+  streamSpaceAsMarkdown(spaceId: string, headers: AuthHeaders): Promise<KbPageBundle>;
+  /**
+   * Fetch the rendered markdown content of a single page within a
+   * space. Resolver fails fast on a 404 (the mount entry surfaces
+   * `MOUNT_SOURCE_NOT_FOUND`) so a stale page selection never lands as
+   * a silent empty file.
+   */
+  fetchPageMarkdown(
+    spaceId: string,
+    pageSlug: string,
+    headers: AuthHeaders,
+  ): Promise<KbPageContent>;
+}
+
+export interface ScmRepoCheckoutInstruction {
+  readonly cloneUrl: string;
+  readonly ref: string;
+  readonly depth: number;
+  readonly filter: string | undefined;
+}
+
+export interface ScmClient {
+  /**
+   * Returns the metadata needed for the writer phase to invoke
+   * `git clone` into the staging directory. Bytes are not transferred
+   * through the proxy itself; the proxy spawns `git` which streams
+   * directly to disk.
+   */
+  resolveCheckout(
+    repoRef: string,
+    ref: string,
+    headers: AuthHeaders,
+  ): Promise<ScmRepoCheckoutInstruction>;
+}
+
+export interface SessionAttachmentItem {
+  readonly relPath: string;
+  readonly sizeBytes: number | undefined;
+  readonly readable: Readable;
+}
+
+export interface SessionAttachmentClient {
+  streamSessionAttachments(
+    sessionId: string,
+    headers: AuthHeaders,
+  ): Promise<AsyncIterable<SessionAttachmentItem>>;
+}
+
+export interface DeliverableSpecBundle {
+  /**
+   * Files that compose the spec on disk: `manifest.json`, optional
+   * `schema.json` / `schema.zod.ts`, optional `template.{md,docx,...}`,
+   * optional `assets/*`. Each file is small enough to ship as bytes.
+   */
+  readonly files: ReadonlyArray<{
+    readonly relPath: string;
+    readonly bytes: Uint8Array;
+  }>;
+}
+
+export interface DeliverableSpecsClient {
+  fetchSpecBundle(
+    contractKey: string,
+    headers: AuthHeaders,
+  ): Promise<DeliverableSpecBundle>;
+}
+
+/**
+ * One bundled resource inside a skill — a reference doc, script, asset,
+ * or template that ships alongside `SKILL.md`. `contentBase64` carries
+ * the raw bytes so binary assets survive the JSON wire intact.
+ */
+export interface SkillBundleResource {
+  /** Path of the file relative to the skill directory. */
+  readonly relPath: string;
+  /** Resource classification surfaced by skill-registry-api. */
+  readonly type: string;
+  /** Decoded byte size; carried for diagnostics. */
+  readonly sizeBytes: number;
+  /** Base64-encoded raw bytes of the resource. */
+  readonly contentBase64: string;
+}
+
+/**
+ * A complete skill bundle: the raw `SKILL.md` text plus every bundled
+ * resource. The `skill-bundle` resolver materialises `SKILL.md` and one
+ * file per resource under `<skill-bundles slot>/<skillKey>/`.
+ */
+export interface SkillBundle {
+  /** Hierarchical skill slug requested. */
+  readonly slug: string;
+  /** Raw `SKILL.md` markdown text. */
+  readonly skillMarkdown: string;
+  /** Bundled resources shipped alongside `SKILL.md`. */
+  readonly resources: readonly SkillBundleResource[];
+}
+
+/**
+ * Narrow client for skill-registry-api's multi-file skill-bundle
+ * endpoint. The implementation lives in workspace-proxy and delegates to
+ * the generated Orval client with `headers` forwarded verbatim for
+ * tenant-scoped auth.
+ */
+export interface SkillRegistryClient {
+  /**
+   * `GET /skills/bundle?slug=<hierarchical-slug>`. Returns the raw
+   * `SKILL.md` text plus every bundled resource (base64-encoded bytes).
+   */
+  fetchSkillBundle(slug: string, headers: AuthHeaders): Promise<SkillBundle>;
+}
+
+/**
+ * Per-resource bundle response from llm-registry-api. Mirrors the shape
+ * of `BundleFileResponseDto` in the registry service. The kernel SDK
+ * does not import the DTO directly so this stays runtime-dep-free.
+ */
+export interface LlmRegistryBundleFile {
+  readonly key: string;
+  readonly content: string;
+  readonly contentHash: string;
+}
+
+/**
+ * Rendered AGENTS.md + context.json + system-overlay from llm-registry-
+ * api's `agent-run-context/render` endpoint. One render call serves
+ * three single-file slots — the resolvers split the response into one
+ * entry each. Resolvers cache the response by `{ applyId,
+ * renderEndpointVersion }` so a single mount-apply hits the upstream
+ * once for all three.
+ */
+export interface AgentRunContextRender {
+  readonly agentsMd: string;
+  readonly contextJson: Readonly<Record<string, unknown>>;
+  readonly systemOverlay: string;
+}
+
+/**
+ * Narrow client for llm-registry-api's per-resource bundle endpoints +
+ * the agent-run-context render. Implementations live in workspace-proxy
+ * and delegate to the generated Orval client with `headers` forwarded
+ * verbatim for tenant-scoped auth.
+ */
+export interface LlmRegistryClient {
+  /**
+   * `GET /agent-definitions/internal/agents/:slug/bundle`. Returns the
+   * `.opencode/agents/<slug>.md` bytes for the requested agent at the
+   * highest matching scope tier (project → org → biome → system).
+   */
+  fetchAgentBundleFile(
+    params: {
+      readonly slug: string;
+      readonly agentMode: 'primary' | 'subagent';
+    },
+    headers: AuthHeaders,
+  ): Promise<LlmRegistryBundleFile>;
+
+  /**
+   * `GET /agent-definitions/internal/instruction-sections/:sectionKey/bundle`.
+   * Returns the markdown for one instruction section. Mounted at
+   * `/workspace/.xema/instructions/<sectionKey>.md` and auto-discovered
+   * by OpenCode via the static `instructions` glob.
+   */
+  fetchInstructionSectionBundleFile(
+    params: { readonly sectionKey: string },
+    headers: AuthHeaders,
+  ): Promise<LlmRegistryBundleFile>;
+
+  /**
+   * `POST /agent-run-context/render`. Returns the rendered AGENTS.md +
+   * context.json + system-overlay for the invocation. Called by all
+   * three rendered-* resolvers (agents-md / context-json /
+   * system-overlay) — the resolver-shared cache coalesces the three
+   * calls into one upstream request per mount-apply by hashing the
+   * params consistently.
+   */
+  renderAgentRunContext(
+    params: {
+      readonly agentSlug: string;
+      readonly projectId: string;
+      readonly role: string;
+      readonly deliverableSpecRef?: string;
+      readonly workflowRunId?: string;
+      readonly jobRunId?: string;
+      readonly sessionId?: string;
+      readonly workflowInputs?: Readonly<Record<string, unknown>>;
+      readonly mounts?: ReadonlyArray<{
+        readonly mount: string;
+        readonly mode: 'read-only' | 'read-write';
+      }>;
+      readonly inputArtifacts?: ReadonlyArray<{
+        readonly path: string;
+        readonly contentType?: string;
+        readonly sourceArtifactId: string;
+        readonly sourceVersion: number;
+      }>;
+      readonly workingFiles?: ReadonlyArray<{
+        readonly slug: string;
+        readonly path: string;
+        readonly format: 'markdown' | 'html' | 'json' | 'yaml' | 'text';
+        readonly syncDirection: 'down-only' | 'up-only' | 'bidirectional';
+        readonly sourceKind: string;
+        readonly sourceRef: Readonly<Record<string, string>>;
+      }>;
+      readonly hasRetryContext?: boolean;
+    },
+    headers: AuthHeaders,
+  ): Promise<AgentRunContextRender>;
+}

package/src/agent-workspace/lib/resolvers/deliverable-specs.resolver.ts

@@ -0,0 +1,33 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import type { DeliverableSpecsClient } from './clients';
+import { assertAuthHeaders } from './utils/auth';
+
+/**
+ * `deliverable-specs` mount kind — fetches the rendered spec bundle
+ * (manifest.json + schema files + template + assets) and emits each
+ * file as a literal MountEntry. Bundle files are typically small (KB,
+ * not MB) so literal bytes are appropriate.
+ */
+export class DeliverableSpecsResolver implements MountResolver<'deliverable-specs'> {
+  readonly kind = 'deliverable-specs' as const;
+
+  constructor(private readonly client: DeliverableSpecsClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'deliverable-specs' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const bundle = await this.client.fetchSpecBundle(source.contractKey, headers);
+    for (const file of bundle.files) {
+      yield {
+        relPath: file.relPath,
+        mode: slotCtx.mode,
+        body: { kind: 'literal', bytes: file.bytes },
+      };
+    }
+  }
+}

package/src/agent-workspace/lib/resolvers/deliverables.resolver.ts

@@ -0,0 +1,41 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import type { ArtifactStoreClient } from './clients';
+import { assertAuthHeaders } from './utils/auth';
+
+/**
+ * `deliverables` mount kind — agent-authored outputs from an upstream
+ * pipeline phase. Backed by the same artifact-store substrate as
+ * `artifact-store-collection`; the caller-supplied `contractKey`
+ * resolves to the collection holding that phase's deliverables.
+ *
+ * Mode flows from the plan entry through `slotCtx.mode` — the
+ * composer is the single source of truth for whether the slot is
+ * read-only or read-write per the manifest.
+ */
+export class DeliverablesResolver implements MountResolver<'deliverables'> {
+  readonly kind = 'deliverables' as const;
+
+  constructor(private readonly client: ArtifactStoreClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'deliverables' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const collection = await this.client.streamCollection(source.contractKey, headers);
+    for await (const blob of collection.blobs) {
+      yield {
+        relPath: blob.metadata.relPath,
+        mode: slotCtx.mode,
+        body: {
+          kind: 'stream',
+          readable: blob.stream,
+          sizeHint: blob.metadata.sizeBytes,
+        },
+      };
+    }
+  }
+}

package/src/agent-workspace/lib/resolvers/index.ts

@@ -0,0 +1,19 @@
+export * from './types';
+export * from './clients';
+export * from './utils/auth';
+export * from './utils/size-cap';
+export * from './utils/streaming';
+export * from './static-literal.resolver';
+export * from './artifact-store-collection.resolver';
+export * from './kb-space.resolver';
+export * from './scm-repo.resolver';
+export * from './session-attachment.resolver';
+export * from './deliverable-specs.resolver';
+export * from './deliverables.resolver';
+export * from './agent-definition.resolver';
+export * from './skill-bundle.resolver';
+export * from './instruction-section.resolver';
+export * from './rendered-agents-md.resolver';
+export * from './rendered-context-json.resolver';
+export * from './rendered-system-overlay.resolver';
+export * from './utils/agent-run-context-cache';

package/src/agent-workspace/lib/resolvers/instruction-section.resolver.ts

@@ -0,0 +1,36 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { LlmRegistryClient } from './clients';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import { assertAuthHeaders } from './utils/auth';
+
+/**
+ * `instruction-section` mount kind — emits one `<sectionKey>.md` file
+ * under the `instructions` slot (`/workspace/.xema/instructions/`).
+ * Auto-discovered by OpenCode at session start via the static
+ * `instructions` glob declared in base `opencode.jsonc`.
+ */
+export class InstructionSectionResolver implements MountResolver<'instruction-section'> {
+  readonly kind = 'instruction-section' as const;
+
+  constructor(private readonly client: LlmRegistryClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'instruction-section' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const file = await this.client.fetchInstructionSectionBundleFile(
+      { sectionKey: source.sectionKey },
+      headers,
+    );
+    yield {
+      // Writer composes slot + entryRelPath + relPath. The mount plan
+      // already sets entryRelPath to "<sectionKey>.md".
+      relPath: '',
+      mode: slotCtx.mode,
+      body: { kind: 'literal', bytes: Buffer.from(file.content, 'utf8') },
+    };
+  }
+}

package/src/agent-workspace/lib/resolvers/kb-pages.resolver.ts

@@ -0,0 +1,62 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import type { KbClient } from './clients';
+import { assertAuthHeaders } from './utils/auth';
+import { MountSourceUpstreamError } from '../errors';
+
+/**
+ * `kb-pages` mount kind — materialises a curated set of pages from a
+ * single KB space as individual markdown files under the entry's
+ * slot+relPath. Each page lands at `<pageSlug>.md`.
+ *
+ * Distinct from `kb-space` (which concatenates an entire space into one
+ * `space.md` bundle). The `kb-pages` flow is the building block for
+ * runtime KB mounting on Interactive Sessions / Brainstorming — the
+ * user picks individual pages to attach to a live session.
+ *
+ * Fail-fast contract:
+ *   - empty `pageSlugs` is a programming error (the caller is expected
+ *     to drop empty mount entries before composing the plan); we throw
+ *     so a stale composer state cannot land a zero-byte mount.
+ *   - per-page 404 / upstream errors propagate as
+ *     `MountSourceUpstreamError` (mapped by workspace-proxy to
+ *     `MOUNT_SOURCE_NOT_FOUND` / `MOUNT_UPSTREAM_BAD_GATEWAY`).
+ */
+export class KbPagesResolver implements MountResolver<'kb-pages'> {
+  readonly kind = 'kb-pages' as const;
+
+  constructor(private readonly client: KbClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'kb-pages' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    // De-duplicate slugs preserving first-occurrence order so the
+    // on-disk layout is deterministic regardless of caller-side
+    // accidental duplicates.
+    const seen = new Set<string>();
+    const slugs = source.pageSlugs.filter((s) => {
+      if (seen.has(s)) return false;
+      seen.add(s);
+      return true;
+    });
+    if (slugs.length === 0) {
+      throw new MountSourceUpstreamError(
+        `kb-pages mount for space '${source.spaceId}' has an empty pageSlugs[] selection`,
+        { spaceId: source.spaceId },
+      );
+    }
+    for (const pageSlug of slugs) {
+      const page = await this.client.fetchPageMarkdown(source.spaceId, pageSlug, headers);
+      const bytes = Buffer.from(page.body, 'utf8');
+      yield {
+        relPath: `${pageSlug}.md`,
+        mode: slotCtx.mode,
+        body: { kind: 'literal', bytes },
+      };
+    }
+  }
+}

package/src/agent-workspace/lib/resolvers/kb-space.resolver.ts

@@ -0,0 +1,34 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import type { KbClient } from './clients';
+import { assertAuthHeaders } from './utils/auth';
+
+/**
+ * `kb-space` mount kind — streams the rendered markdown of every page
+ * in a knowledge-base space into a single bundle file. The bundle is
+ * landed at `space.md` within the entry's slot+relPath.
+ */
+export class KbSpaceResolver implements MountResolver<'kb-space'> {
+  readonly kind = 'kb-space' as const;
+
+  constructor(private readonly client: KbClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'kb-space' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const bundle = await this.client.streamSpaceAsMarkdown(source.spaceId, headers);
+    yield {
+      relPath: 'space.md',
+      mode: slotCtx.mode,
+      body: {
+        kind: 'stream',
+        readable: bundle.readable,
+        sizeHint: bundle.sizeBytes,
+      },
+    };
+  }
+}

package/src/agent-workspace/lib/resolvers/rendered-agents-md.resolver.ts

@@ -0,0 +1,40 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import { assertAuthHeaders } from './utils/auth';
+import {
+  renderParamsFromSource,
+  type RenderedAgentRunContextCache,
+} from './utils/agent-run-context-cache';
+
+/**
+ * `rendered-agents-md` mount kind — emits the rendered `AGENTS.md`
+ * bytes for the `agents-md` single-file slot (`/workspace/AGENTS.md`).
+ *
+ * Single-file slots require `relPath === ''` (validated upstream by
+ * `plan-validator`). Shares the `agent-run-context/render` call with
+ * `rendered-context-json` + `rendered-system-overlay`. The composer
+ * fills the same `RenderedAgentRunContextParams` superset on all three
+ * sources and `renderParamsFromSource` projects them identically — so
+ * the cache coalesces the three resolvers onto one upstream call per
+ * mount-apply.
+ */
+export class RenderedAgentsMdResolver implements MountResolver<'rendered-agents-md'> {
+  readonly kind = 'rendered-agents-md' as const;
+
+  constructor(private readonly cache: RenderedAgentRunContextCache) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'rendered-agents-md' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const rendered = await this.cache.render(renderParamsFromSource(source), headers);
+    yield {
+      relPath: '',
+      mode: slotCtx.mode,
+      body: { kind: 'literal', bytes: Buffer.from(rendered.agentsMd, 'utf8') },
+    };
+  }
+}

package/src/agent-workspace/lib/resolvers/rendered-context-json.resolver.ts

@@ -0,0 +1,41 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import { assertAuthHeaders } from './utils/auth';
+import {
+  renderParamsFromSource,
+  type RenderedAgentRunContextCache,
+} from './utils/agent-run-context-cache';
+
+/**
+ * `rendered-context-json` mount kind — emits the rendered
+ * `context.json` bytes for the `context-json` single-file slot
+ * (`/workspace/context.json`).
+ *
+ * Shares the `agent-run-context/render` call with `rendered-agents-md`
+ * + `rendered-system-overlay` via the resolver-bound cache. See
+ * `renderParamsFromSource` for why all three resolvers MUST project
+ * the source through the same helper.
+ */
+export class RenderedContextJsonResolver
+  implements MountResolver<'rendered-context-json'>
+{
+  readonly kind = 'rendered-context-json' as const;
+
+  constructor(private readonly cache: RenderedAgentRunContextCache) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'rendered-context-json' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const rendered = await this.cache.render(renderParamsFromSource(source), headers);
+    const json = JSON.stringify(rendered.contextJson, null, 2);
+    yield {
+      relPath: '',
+      mode: slotCtx.mode,
+      body: { kind: 'literal', bytes: Buffer.from(json, 'utf8') },
+    };
+  }
+}

package/src/agent-workspace/lib/resolvers/rendered-system-overlay.resolver.ts

@@ -0,0 +1,39 @@
+import type { MountResolver } from '../mount-resolver';
+import type { MountSource } from '../mount-source';
+import type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './types';
+import { assertAuthHeaders } from './utils/auth';
+import {
+  renderParamsFromSource,
+  type RenderedAgentRunContextCache,
+} from './utils/agent-run-context-cache';
+
+/**
+ * `rendered-system-overlay` mount kind — emits the rendered Xema
+ * platform overlay for the `system-overlay` single-file slot
+ * (`/workspace/.xema/system-overlay.md`).
+ *
+ * Same `agent-run-context/render` call as `rendered-agents-md` and
+ * `rendered-context-json`. See `renderParamsFromSource` for the
+ * shared-cache contract that makes the three calls coalesce into one.
+ */
+export class RenderedSystemOverlayResolver
+  implements MountResolver<'rendered-system-overlay'>
+{
+  readonly kind = 'rendered-system-overlay' as const;
+
+  constructor(private readonly cache: RenderedAgentRunContextCache) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'rendered-system-overlay' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const rendered = await this.cache.render(renderParamsFromSource(source), headers);
+    yield {
+      relPath: '',
+      mode: slotCtx.mode,
+      body: { kind: 'literal', bytes: Buffer.from(rendered.systemOverlay, 'utf8') },
+    };
+  }
+}