@xemahq/biome-sdk 0.1.1

package/src/agent-workspace/lib/errors/mount-resolver-error.ts

@@ -0,0 +1,56 @@
+import { MountResolverErrorCode } from './error-codes';
+
+/**
+ * Resolver / proxy faults — surfaced during apply. Distinct hierarchy
+ * from `MountPlanError` so the proxy can map them to different HTTP
+ * statuses without sniffing message strings.
+ *
+ * Subclass per error code. `details` is a structured, scrubbable bag —
+ * NEVER includes JWTs, signed URLs, or upstream payload bodies.
+ */
+export abstract class MountResolverError extends Error {
+  abstract readonly code: MountResolverErrorCode;
+  readonly details: Readonly<Record<string, unknown>>;
+
+  constructor(message: string, details: Readonly<Record<string, unknown>> = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.details = details;
+  }
+}
+
+export class MountActorUnauthorizedError extends MountResolverError {
+  readonly code = MountResolverErrorCode.ActorUnauthorized;
+}
+
+export class MountActorForbiddenError extends MountResolverError {
+  readonly code = MountResolverErrorCode.ActorForbidden;
+}
+
+export class MountSourceNotFoundError extends MountResolverError {
+  readonly code = MountResolverErrorCode.SourceNotFound;
+}
+
+export class MountSourcePayloadTooLargeError extends MountResolverError {
+  readonly code = MountResolverErrorCode.PayloadTooLarge;
+}
+
+export class MountSourceUpstreamError extends MountResolverError {
+  readonly code = MountResolverErrorCode.UpstreamBadGateway;
+}
+
+export class MountSourceUpstreamUnavailableError extends MountResolverError {
+  readonly code = MountResolverErrorCode.UpstreamUnavailable;
+}
+
+export class MountSourceUpstreamTimeoutError extends MountResolverError {
+  readonly code = MountResolverErrorCode.UpstreamTimeout;
+}
+
+export class MountInsufficientStorageError extends MountResolverError {
+  readonly code = MountResolverErrorCode.InsufficientStorage;
+}
+
+export class MountInternalError extends MountResolverError {
+  readonly code = MountResolverErrorCode.Internal;
+}

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

@@ -0,0 +1,35 @@
+import type { MountSource, MountSourceKind } from './mount-source';
+import type {
+  ResolveContext,
+  ResolveSlotContext,
+  ResolvedMountEntries,
+} from './resolvers/types';
+
+/**
+ * One adapter per `MountSource.kind`. Resolvers stream files into the
+ * writer phase, which writes them through `workspace-proxy` into the
+ * agent's `/workspace/` tree.
+ *
+ * Biomes ship their own `MountResolver` and register it with the
+ * `MountSourceKindRegistry` at platform boot. No core code changes when
+ * a new mount-source kind lands.
+ *
+ * Implementations MUST:
+ *   - Forward `ctx.authHeaders` verbatim to upstream Orval clients.
+ *     Cross-tenant access depends on the upstream service's
+ *     `RequestContextMiddleware` enforcing org-scoping; the resolver
+ *     must not silently strip headers.
+ *   - Yield streamed bodies for any payload that may exceed ~1 MB.
+ *   - Throw a `MountResolverError` subclass on any upstream failure —
+ *     never swallow errors or return partial results.
+ */
+export interface MountResolver<K extends MountSourceKind = MountSourceKind> {
+  readonly kind: K;
+  resolve(
+    source: Extract<MountSource, { kind: K }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries;
+}
+
+export type { ResolveContext, ResolveSlotContext, ResolvedMountEntries } from './resolvers/types';

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

@@ -0,0 +1,11 @@
+/**
+ * `MountSource` is the canonical contract owned by `@xemahq/kernel-contracts/workflow`.
+ * Re-exported here so SDK consumers have a single import surface.
+ *
+ * Biomes extend the closed set via TS module augmentation +
+ * `MountSourceKindRegistry.register`.
+ */
+export type { MountSource } from '@xemahq/kernel-contracts/workflow';
+
+import type { MountSource } from '@xemahq/kernel-contracts/workflow';
+export type MountSourceKind = MountSource['kind'];

package/src/agent-workspace/lib/refid-resolver.ts

@@ -0,0 +1,135 @@
+import type { MountSource } from './mount-source';
+
+/**
+ * Closed prefix table — every refId carried in DSL outputs has exactly
+ * one matching entry. Adding a new prefix requires extending both this
+ * enum AND `PREFIX_PARSERS`; an unmatched prefix throws fail-fast.
+ */
+export enum RefIdPrefix {
+  ArtifactStoreCollection = 'art',
+  KnowledgeBaseSpace = 'kb',
+  ScmRepo = 'scm',
+  SessionAttachment = 'att',
+  Deliverables = 'dlv',
+  DeliverableSpecs = 'dlv-spec',
+  StaticLiteral = 'lit',
+}
+
+/**
+ * Converts the short refId form carried in DSL outputs (`art:<id>`,
+ * `kb:<id>`, `scm:<repo>@<ref>`, `att:<sessionId>`,
+ * `dlv:<contractKey>`, `dlv-spec:<contractKey>`, `lit:<inline>`) into a
+ * concrete `MountSource` the renderer can dispatch to a `MountResolver`.
+ *
+ * Short prefixes are the wire form (DSL author + agent visible); full
+ * URIs stay internal to resolvers and `workspace-proxy`.
+ */
+export interface RefIdResolver {
+  resolve(refId: string): MountSource;
+  canResolve(refId: string): boolean;
+}
+
+export class RefIdSchemeError extends Error {
+  readonly refId: string;
+
+  constructor(refId: string, message: string) {
+    super(`[refId "${refId}"] ${message}`);
+    this.name = 'RefIdSchemeError';
+    this.refId = refId;
+  }
+}
+
+type PrefixParser = (refId: string, body: string) => MountSource;
+
+const PREFIX_PARSERS: Readonly<Record<RefIdPrefix, PrefixParser>> = {
+  [RefIdPrefix.ArtifactStoreCollection]: (refId, body) => {
+    if (body.length === 0) {
+      throw new RefIdSchemeError(refId, 'artifact-store collection id is empty');
+    }
+    return { kind: 'artifact-store-collection', collectionId: body };
+  },
+  [RefIdPrefix.KnowledgeBaseSpace]: (refId, body) => {
+    if (body.length === 0) {
+      throw new RefIdSchemeError(refId, 'kb space id is empty');
+    }
+    return { kind: 'kb-space', spaceId: body };
+  },
+  [RefIdPrefix.ScmRepo]: (refId, body) => {
+    const at = body.indexOf('@');
+    if (at < 1 || at === body.length - 1) {
+      throw new RefIdSchemeError(
+        refId,
+        "scm refId must be of the form 'scm:<repoRef>@<ref>'",
+      );
+    }
+    const repoRef = body.slice(0, at);
+    const ref = body.slice(at + 1);
+    return { kind: 'scm-repo', repoRef, ref };
+  },
+  [RefIdPrefix.SessionAttachment]: (refId, body) => {
+    if (body.length === 0) {
+      throw new RefIdSchemeError(refId, 'session id is empty');
+    }
+    return { kind: 'session-attachment', sessionId: body };
+  },
+  [RefIdPrefix.Deliverables]: (refId, body) => {
+    if (body.length === 0) {
+      throw new RefIdSchemeError(refId, 'deliverable contract key is empty');
+    }
+    return { kind: 'deliverables', contractKey: body };
+  },
+  [RefIdPrefix.DeliverableSpecs]: (refId, body) => {
+    if (body.length === 0) {
+      throw new RefIdSchemeError(refId, 'deliverable-spec contract key is empty');
+    }
+    return { kind: 'deliverable-specs', contractKey: body };
+  },
+  [RefIdPrefix.StaticLiteral]: (refId, body) => {
+    // `lit:<pathWithinWorkspace>=<base64-bytes>` — both segments required.
+    const eq = body.indexOf('=');
+    if (eq < 1 || eq === body.length - 1) {
+      throw new RefIdSchemeError(
+        refId,
+        "literal refId must be of the form 'lit:<pathWithinWorkspace>=<base64-bytes>'",
+      );
+    }
+    const pathWithinWorkspace = body.slice(0, eq);
+    const bytes = body.slice(eq + 1);
+    return { kind: 'static-literal', pathWithinWorkspace, bytes };
+  },
+};
+
+const KNOWN_PREFIXES: ReadonlySet<string> = new Set(Object.values(RefIdPrefix));
+
+function splitPrefix(refId: string): { prefix: string; body: string } {
+  // dlv-spec contains a dash; we still split on the FIRST `:` only.
+  const colon = refId.indexOf(':');
+  if (colon < 1) {
+    throw new RefIdSchemeError(refId, 'expected `<prefix>:<body>` form');
+  }
+  return { prefix: refId.slice(0, colon), body: refId.slice(colon + 1) };
+}
+
+export class RefIdResolverImpl implements RefIdResolver {
+  canResolve(refId: string): boolean {
+    if (typeof refId !== 'string' || refId.length === 0) return false;
+    const colon = refId.indexOf(':');
+    if (colon < 1) return false;
+    return KNOWN_PREFIXES.has(refId.slice(0, colon));
+  }
+
+  resolve(refId: string): MountSource {
+    if (typeof refId !== 'string' || refId.length === 0) {
+      throw new RefIdSchemeError(String(refId), 'refId must be a non-empty string');
+    }
+    const { prefix, body } = splitPrefix(refId);
+    if (!KNOWN_PREFIXES.has(prefix)) {
+      throw new RefIdSchemeError(
+        refId,
+        `unknown refId prefix '${prefix}' — expected one of: ${Object.values(RefIdPrefix).join(', ')}`,
+      );
+    }
+    const parser = PREFIX_PARSERS[prefix as RefIdPrefix];
+    return parser(refId, body);
+  }
+}

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

@@ -0,0 +1,150 @@
+import { Registry } from '@xemahq/registry';
+import type { MountResolver } from './mount-resolver';
+import type { MountSourceKind } from './mount-source';
+import type {
+  ArtifactStoreClient,
+  KbClient,
+  LlmRegistryClient,
+  ScmClient,
+  SessionAttachmentClient,
+  DeliverableSpecsClient,
+  SkillRegistryClient,
+} from './resolvers/clients';
+import { AgentDefinitionResolver } from './resolvers/agent-definition.resolver';
+import { ArtifactStoreCollectionResolver } from './resolvers/artifact-store-collection.resolver';
+import { ArtifactVersionResolver } from './resolvers/artifact-version.resolver';
+import { DeliverablesResolver } from './resolvers/deliverables.resolver';
+import { DeliverableSpecsResolver } from './resolvers/deliverable-specs.resolver';
+import { InstructionSectionResolver } from './resolvers/instruction-section.resolver';
+import { KbSpaceResolver } from './resolvers/kb-space.resolver';
+import { KbPagesResolver } from './resolvers/kb-pages.resolver';
+import { RenderedAgentsMdResolver } from './resolvers/rendered-agents-md.resolver';
+import { RenderedContextJsonResolver } from './resolvers/rendered-context-json.resolver';
+import { RenderedSystemOverlayResolver } from './resolvers/rendered-system-overlay.resolver';
+import { RenderedAgentRunContextCache } from './resolvers/utils/agent-run-context-cache';
+import { ScmRepoResolver } from './resolvers/scm-repo.resolver';
+import { SessionAttachmentResolver } from './resolvers/session-attachment.resolver';
+import { SkillBundleResolver } from './resolvers/skill-bundle.resolver';
+import { StaticLiteralResolver } from './resolvers/static-literal.resolver';
+
+export interface MountSourceKindRegistration {
+  readonly key: MountSourceKind;
+  readonly resolver: MountResolver;
+}
+
+/**
+ * Runtime dispatch table for `MountSource.kind` → `MountResolver`. Built-in
+ * kinds register at platform boot; biomes extend it via the same API.
+ */
+export class MountSourceKindRegistry extends Registry<MountSourceKind, MountSourceKindRegistration> {
+  constructor(seed?: readonly MountSourceKindRegistration[]) {
+    super(seed ? { name: 'MountSourceKindRegistry', seed } : { name: 'MountSourceKindRegistry' });
+  }
+}
+
+/**
+ * Constructor deps for the built-in resolver set. Each client is
+ * **per-call auth aware** — workspace-proxy threads the actor's
+ * `authHeaders` into every call, so a single client instance services
+ * many actors safely. Static service-token clients MUST NOT be used.
+ *
+ * The interface is kept narrow on purpose: each resolver claims exactly
+ * the upstream client it needs, no global "platform clients" bag.
+ */
+export interface MountSourceKindResolverDeps {
+  readonly artifactStoreClient: ArtifactStoreClient;
+  readonly kbClient: KbClient;
+  readonly scmClient: ScmClient;
+  readonly sessionAttachmentClient: SessionAttachmentClient;
+  readonly deliverableSpecsClient: DeliverableSpecsClient;
+  readonly llmRegistryClient: LlmRegistryClient;
+  readonly skillRegistryClient: SkillRegistryClient;
+}
+
+/**
+ * Boot-time factory: returns a fully-populated registry containing the
+ * seven built-in resolvers. Biomes register their own kinds via
+ * `registry.register()` after this is built.
+ *
+ * Each resolver is a constructor-injected pure class — no I/O at
+ * construction time, no global singletons. Adding a new built-in kind
+ * = extending `MountSource` + appending a registration here.
+ */
+export function buildBuiltinMountSourceKindRegistry(
+  deps: MountSourceKindResolverDeps,
+): MountSourceKindRegistry {
+  const registry = new MountSourceKindRegistry();
+  registry.registerMany([
+    {
+      key: 'artifact-store-collection',
+      resolver: new ArtifactStoreCollectionResolver(deps.artifactStoreClient),
+    },
+    {
+      key: 'artifact-version',
+      resolver: new ArtifactVersionResolver(deps.artifactStoreClient),
+    },
+    { key: 'kb-space', resolver: new KbSpaceResolver(deps.kbClient) },
+    { key: 'kb-pages', resolver: new KbPagesResolver(deps.kbClient) },
+    { key: 'scm-repo', resolver: new ScmRepoResolver(deps.scmClient) },
+    {
+      key: 'session-attachment',
+      resolver: new SessionAttachmentResolver(deps.sessionAttachmentClient),
+    },
+    {
+      key: 'deliverable-specs',
+      resolver: new DeliverableSpecsResolver(deps.deliverableSpecsClient),
+    },
+    { key: 'deliverables', resolver: new DeliverablesResolver(deps.artifactStoreClient) },
+    { key: 'static-literal', resolver: new StaticLiteralResolver() },
+    // ── Platform-rendered (mount-apply pipeline for `.opencode/` and
+    //    AGENTS.md / context.json) ──
+    {
+      key: 'agent-definition',
+      resolver: new AgentDefinitionResolver(deps.llmRegistryClient),
+    },
+    {
+      key: 'skill-bundle',
+      resolver: new SkillBundleResolver(deps.skillRegistryClient),
+    },
+    {
+      key: 'instruction-section',
+      resolver: new InstructionSectionResolver(deps.llmRegistryClient),
+    },
+  ]);
+  // Three rendered-* resolvers share one cache so a single mount-apply
+  // hits `agent-run-context/render` once for AGENTS.md + context.json +
+  // system-overlay.
+  const renderCache = new RenderedAgentRunContextCache(deps.llmRegistryClient);
+  registry.registerMany([
+    {
+      key: 'rendered-agents-md',
+      resolver: new RenderedAgentsMdResolver(renderCache),
+    },
+    {
+      key: 'rendered-context-json',
+      resolver: new RenderedContextJsonResolver(renderCache),
+    },
+    {
+      key: 'rendered-system-overlay',
+      resolver: new RenderedSystemOverlayResolver(renderCache),
+    },
+  ]);
+  return registry;
+}
+
+export interface RuntimeMountKindRegistration {
+  readonly key: string;
+  readonly displayName: string;
+  readonly apply: (ctx: unknown) => Promise<void>;
+}
+
+/**
+ * Replaces the hardcoded `RuntimeMountKind` switch in
+ * `agent-session-api`. Each agent-session profile (and any
+ * biome-defined profile) registers its mount strategy here.
+ */
+export class RuntimeMountKindRegistry extends Registry<string, RuntimeMountKindRegistration> {
+  constructor(seed?: readonly RuntimeMountKindRegistration[]) {
+    super(seed ? { name: 'RuntimeMountKindRegistry', seed } : { name: 'RuntimeMountKindRegistry' });
+  }
+}

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

@@ -0,0 +1,45 @@
+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';
+
+/**
+ * `agent-definition` mount kind — emits one `<slug>.md` file under the
+ * `agent-bundles` slot (`/workspace/.opencode/agents/`). Per OpenCode
+ * convention, primary agents and sub-agents share the same directory
+ * and are differentiated by frontmatter `mode`.
+ *
+ * Source data lives in llm-registry-api's `AgentDefinition` table and
+ * is rendered with frontmatter by the `BundleFileService`. This
+ * resolver simply forwards the actor's auth headers and writes the
+ * bytes into the slot.
+ */
+export class AgentDefinitionResolver implements MountResolver<'agent-definition'> {
+  readonly kind = 'agent-definition' as const;
+
+  constructor(private readonly client: LlmRegistryClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'agent-definition' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const file = await this.client.fetchAgentBundleFile(
+      {
+        slug: source.agentSlug,
+        agentMode: source.agentMode,
+      },
+      headers,
+    );
+    yield {
+      // Writer composes slot + entryRelPath + relPath. The mount plan
+      // already sets entryRelPath to "<slug>.md", so resolver relPath
+      // must stay empty to avoid duplicate nesting.
+      relPath: '',
+      mode: slotCtx.mode,
+      body: { kind: 'literal', bytes: Buffer.from(file.content, 'utf8') },
+    };
+  }
+}

package/src/agent-workspace/lib/resolvers/artifact-store-collection.resolver.ts

@@ -0,0 +1,43 @@
+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';
+
+/**
+ * `artifact-store-collection` mount kind — streams every blob in a
+ * collection into the slot. Each blob lands at the path the upstream
+ * service declares in its metadata (typically the relative path the
+ * blob was emitted with).
+ *
+ * Bytes are streamed end-to-end: the resolver yields `MountEntry`
+ * objects with `body.kind = 'stream'`, never buffering blob contents
+ * in memory.
+ */
+export class ArtifactStoreCollectionResolver
+  implements MountResolver<'artifact-store-collection'>
+{
+  readonly kind = 'artifact-store-collection' as const;
+
+  constructor(private readonly client: ArtifactStoreClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'artifact-store-collection' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const collection = await this.client.streamCollection(source.collectionId, 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/artifact-version.resolver.ts

@@ -0,0 +1,52 @@
+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';
+
+/**
+ * `artifact-version` mount kind — materialises one artifact-store version
+ * as a single file at the entry's path.
+ *
+ * Powers the "produce-then-mount" hand-off pattern: an upstream activity
+ * (e.g. `xema/http@v1` with `outputMode: artifact`) emits a versioned
+ * artifact; the downstream agent declares an `inputArtifacts` entry that
+ * lands the bytes inside `/workspace/<slot>/<fileName>`. The agent reads
+ * the file via its tool surface instead of receiving the bytes inline
+ * through the agent-run-context prompt, avoiding the 1.2 MB blow-up that
+ * killed demo-06.
+ *
+ * The resolver intentionally yields a `literal` body (full bytes in
+ * memory) rather than a `stream`: artifact-store inline payloads are
+ * already memory-resident on the upstream and capped by the platform
+ * 10 MB body limit, so streaming would add complexity without saving
+ * RSS. Larger artifacts should use the blob storage path with a
+ * dedicated streaming kind — not retrofitted onto this resolver.
+ */
+export class ArtifactVersionResolver implements MountResolver<'artifact-version'> {
+  readonly kind = 'artifact-version' as const;
+
+  constructor(private readonly client: ArtifactStoreClient) {}
+
+  async *resolve(
+    source: Extract<MountSource, { kind: 'artifact-version' }>,
+    slotCtx: ResolveSlotContext,
+    ctx: ResolveContext,
+  ): ResolvedMountEntries {
+    const headers = assertAuthHeaders(ctx);
+    const content = await this.client.fetchVersionContent(
+      source.artifactId,
+      source.version,
+      source.payloadField,
+      headers,
+    );
+    yield {
+      relPath: source.fileName,
+      mode: slotCtx.mode,
+      body: {
+        kind: 'literal',
+        bytes: content.bytes,
+      },
+    };
+  }
+}