@xemahq/agent-session-runtime 0.11.0 → 0.11.2

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

@@ -1,632 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── Agent → CompiledWorkspaceManifest reconstruction ──
-//
-// The composer turns a
-// `CompiledWorkspaceManifest` into a `WorkspaceMountPlan`; before this
-// module the only way to obtain that compiled manifest was to fetch the
-// `WorkspaceManifest` row from `workspace-manifests-api` and run
-// `compileManifest` on it.
-//
-// The Agent primitive now carries the user-data MOUNT LAYOUT
-// on its `workspace.mountLayout` block: the boot-seeder in `llm-registry-api`
-// projects each biome manifest's `extends:`-flattened RAW `spec.mounts` /
-// `spec.seedFiles` / `spec.inputs` there. This module reconstructs a
-// `WorkspaceManifest` envelope from a resolved composition + its
-// `mountLayout`, then runs the SAME `compileManifest` the legacy path used
-// — with the REAL run/session bind inputs, so `${input.x}` tokens in
-// seed-file vars resolve against the caller's inputs, never against a
-// seed-time placeholder.
-//
-// The result is a `CompiledWorkspaceManifest` indistinguishable from the
-// legacy `workspace-manifests-api`-sourced one — the composer interface is
-// unchanged.
-//
-// This module is RUNTIME-AGNOSTIC: it does not import a generated API
-// client. The caller (`agent-session-api` today, `workflow-runtime-worker`
-// next) maps its resolved-composition shape onto the small input
-// interfaces declared here and supplies the bind-input bag.
-// ═══════════════════════════════════════════════════════════════════════════
-
-import {
-  ManifestSurface,
-  OutputSurfaceKind,
-  type AgentRunRole,
-  type CompiledManifestCredential,
-  type CompiledManifestPermissions,
-  type ModelRef,
-} from '@xemahq/kernel-contracts/workflow';
-import type { PermissionMap } from '@xemahq/kernel-contracts/agent-permission';
-import {
-  compileManifest,
-  type CompiledWorkspaceManifest,
-  type ManifestCredential,
-  type ManifestInputDeclaration,
-  type ManifestMountsBlock,
-  type ManifestOutputSurface,
-  type ManifestPermissions,
-  type ManifestSeedFile,
-  type ManifestSubAgent,
-  type ManifestWorkingFile,
-  type AgentWorkspaceSpec as DslWorkspaceManifest,
-  type WorkspaceManifestSpec,
-} from '@xemahq/dsl/workspace-manifest';
-
-/**
- * Re-export so callers that consume this module's `compile…` result do not
- * need a second import from `@xemahq/dsl/workspace-manifest`.
- */
-export type { CompiledWorkspaceManifest };
-
-/**
- * Raised when a resolved composition cannot be reconstructed into a
- * compilable workspace manifest — a missing `mountLayout`, a malformed
- * composition ref, or a `compileManifest` failure. Fail-fast: a session /
- * run cannot bootstrap a `/workspace/` tree without a valid mount layout.
- */
-export class AgentMountLayoutError extends Error {
-  constructor(agentRef: string, detail: string) {
-    super(
-      `Cannot derive a workspace mount layout from Agent ` +
-        `"${agentRef}": ${detail}`,
-    );
-    this.name = 'AgentMountLayoutError';
-  }
-}
-
-/**
- * The agent run-config the seeder projects from the source manifest's
- * `spec.agent` block. Mirrors `AgentRunConfigDto` without
- * importing the generated client.
- */
-export interface AgentRunConfigInput {
-  /** Stage key. */
-  readonly stage: string;
-  /** Canonical `AgentRunRole` — drives renderer + system-overlay framing. */
-  readonly role: string;
-  /**
-   * Deliverable-spec ref. May carry a `${input.x}` token — resolved
-   * downstream against the bind inputs.
-   */
-  readonly deliverableSpecRef?: string;
-}
-
-/**
- * The `extends:`-flattened RAW user-data mount layout carried on a
- * composition's `workspace.mountLayout` block. The seeder owns the wire
- * shape; `compileManifest`'s Zod schema re-validates `mounts` / `seedFiles`
- * / `inputs` against the manifest DSL's authoritative schema, so the loose
- * typing here is checked downstream, not silently trusted.
- */
-export interface AgentMountLayoutInput {
-  /** Raw `spec.mounts` block — manifest DSL mount-declaration map. */
-  readonly mounts: Readonly<Record<string, unknown>>;
-  /** Projected `spec.agent` run-config. */
-  readonly agentRunConfig: AgentRunConfigInput;
-  /** Raw `spec.seedFiles` array — manifest DSL seed-file entries. */
-  readonly seedFiles: readonly unknown[];
-  /** Raw `spec.inputs` block — manifest DSL input-declaration map. */
-  readonly inputs: Readonly<Record<string, unknown>>;
-}
-
-/**
- * A single manifest-declared sub-agent binding the composition resolved.
- * Mirrors the binding subset the manifest DSL's `ManifestSubAgent` needs.
- *
- * Carries the {@link NodeOverlayFragment} overlay trio (`modelOverride` /
- * `instructions` / `permission`) so a resolved sub-agent's per-node
- * specialization survives the manifest reconstruction. Without these the
- * worker silently DROPPED a delegate's `modelOverride` (the root fix for the
- * worker drift). All optional ⇒ backward-compatible with callers that only
- * supply `slug` / `alias`.
- */
-export interface AgentSubAgentBindingInput {
-  readonly slug: string;
-  readonly alias?: string;
-  /** Per-delegate model override — OVERRIDE on the referenced agent's model. */
-  readonly modelOverride?: ModelRef;
-  /** Per-delegate instructions — APPENDED to the referenced agent's prompt. */
-  readonly instructions?: string;
-  /** Per-delegate permission — RESTRICT-merged over the agent's permission. */
-  readonly permission?: PermissionMap;
-}
-
-/**
- * The composition's `workspace.outputSurface` block projected onto the
- * shape the manifest DSL accepts. Mirrors `ManifestOutputSurface` from
- * `@xemahq/dsl/workspace-manifest` but restated here so callers do not
- * need a second import.
- *
- * Carried through the reconstructed manifest's `spec.outputSurface` so
- * the compiled output's `CompiledManifestOutputSurface` matches the
- * authoritative source — drift detection and runtime defaults read the
- * same kind/root/port the bundle-apply path reads from
- * `composition.workspace.outputSurface`.
- */
-export interface AgentOutputSurfaceInput {
-  readonly kind: 'none' | 'web' | 'static' | 'app' | 'tunnel';
-  readonly port?: number;
-  readonly healthPath?: string;
-  readonly autoOpen?: boolean;
-  readonly mode?: 'single' | 'multi';
-  readonly root?: string;
-  readonly defaultDocument?: string;
-}
-
-/**
- * The minimal resolved-composition projection this module reconstructs a
- * `WorkspaceManifest` from. The caller maps its richer resolved-composition
- * shape onto this — keeping the runtime package free of any API client.
- */
-export interface AgentManifestSource {
-  /** Version-pinned `slug@version` of the resolved composition. */
-  readonly agentRef: string;
-  /** Root node's agent slug — the manifest's primary agent. */
-  readonly primaryAgentSlug: string;
-  /** Manifest-declared sub-agent bindings (descendant nodes). */
-  readonly subAgentBindings: readonly AgentSubAgentBindingInput[];
-  /**
-   * The composition's `workspace.mountLayout` block. `undefined` when the
-   * composition declared no `workspace` block or the seeder did not project
-   * a layout — a fail-fast condition.
-   */
-  readonly mountLayout: AgentMountLayoutInput | undefined;
-  /**
-   * The composition's `workspace.outputSurface` block. Threaded into the
-   * reconstructed manifest's `spec.outputSurface` so the compiled
-   * manifest's `outputSurface` matches the source-of-truth (drift
-   * detection + non-bundle consumers like `workflow-runtime-worker` read
-   * the same value the bundle-apply path reads). `undefined` when the
-   * composition declared no surface — the DSL compile then yields the
-   * `{ kind: 'none' }` default.
-   */
-  readonly outputSurface?: AgentOutputSurfaceInput;
-  /**
-   * The composition's `workspace.credentials` block. Threaded into the
-   * reconstructed manifest's `spec.credentials` so the compiled manifest's
-   * `credentials` matches the source-of-truth — the EnvironmentResolver
-   * reads the same `{name, kind, sourceRef, required}` entries the
-   * authored composition declared (BUG-1 carry-through: authored
-   * `spec.credentials` were silently dropped on reconstruction). Carried
-   * as the kernel `CompiledManifestCredential[]` because that is the shape
-   * `composition.workspace.credentials` holds (the seeder projects the
-   * authored entries through the manifest compiler). `undefined` when the
-   * composition declared none — the DSL compile then yields `[]`.
-   */
-  readonly credentials?: readonly CompiledManifestCredential[];
-  /**
-   * The composition's `workspace.permissions` block. Threaded into the
-   * reconstructed manifest's `spec.permissions` so the compiled manifest's
-   * `permissions` matches the source-of-truth — the EnvironmentResolver
-   * reads the same `{tools: {allow, deny}}` the authored composition
-   * declared (BUG-1 carry-through: authored `spec.permissions` were
-   * silently dropped on reconstruction). Carried as the kernel
-   * `CompiledManifestPermissions` because that is the shape
-   * `composition.workspace.permissions` holds. `undefined` when the
-   * composition declared none — the DSL compile then yields
-   * `{ tools: { allow: [], deny: [] } }`.
-   */
-  readonly permissions?: CompiledManifestPermissions;
-  /**
-   * The composition's `workspace.workingFiles` block. Threaded into the
-   * reconstructed manifest's `spec.workingFiles` so the compiled manifest —
-   * and therefore `context.json.workingFiles` + the write authority on
-   * `context.json.authority.mayWriteWorkspace[]` — matches the
-   * source-of-truth. Carried as the DSL `ManifestWorkingFile[]` (raw, with
-   * `${input.x}` tokens intact); `compileManifest` interpolates them against
-   * the bind inputs, exactly like the bundle-apply path's `toBundleWorkingFiles`.
-   * `undefined` when the composition declared none — the DSL compile then
-   * yields `[]`. (BUG-2 carry-through: authored `spec.workingFiles` were
-   * silently dropped on reconstruction, so a Document Buddy session came up
-   * with NO bound working file — the agent read `context.json`, saw an empty
-   * `workingFiles[]`, and asked the user where to write instead of editing the
-   * bound page. Symmetric with the credentials/permissions BUG-1 fix above.)
-   */
-  readonly workingFiles?: readonly ManifestWorkingFile[];
-}
-
-/**
- * The implicit inputs every reconstructed manifest is bound against, on top
- * of the caller-supplied explicit inputs.
- *
- * `sessionId` is the run-scoped execution identity. The agent-session-api
- * caller supplies the `Session.id`; the workflow-runtime-worker caller —
- * which has no session — supplies the workflow run id. Both are
- * run-scoped; only manifests that declare a `sessionId` input ever read
- * it, and no first-party manifest does today. Optional so a caller with
- * no run-scoped id at all can omit it.
- */
-export interface AgentManifestImplicitInputs {
-  readonly orgId: string;
-  readonly projectId: string;
-  readonly sessionId?: string;
-}
-
-/** Manifest input value primitives accepted by the manifest DSL. */
-type ManifestInputValue =
-  | string
-  | number
-  | boolean
-  | readonly string[]
-  | readonly Readonly<Record<string, unknown>>[];
-
-/**
- * Reconstruct a `WorkspaceManifest` envelope from a resolved composition
- * and run `compileManifest` against the supplied bind inputs.
- *
- * The reconstructed envelope carries NO `extends:` — the boot-seeder
- * already flattened the source manifest's `extends:` chain before
- * projecting `mountLayout`, so the layout is the effective post-merge
- * shape.
- *
- * `bindInputs` is the resolved manifest input bag (explicit inputs ∪
- * implicit inputs), built by {@link buildAgentManifestBindInputs}.
- * The compile fails fast on an unresolved required input or an enum
- * violation — exactly the legacy behaviour.
- */
-export function compileAgentWorkspaceManifest(
-  source: AgentManifestSource,
-  bindInputs: Readonly<Record<string, unknown>>,
-): CompiledWorkspaceManifest {
-  const mountLayout = source.mountLayout;
-  if (!mountLayout) {
-    throw new AgentMountLayoutError(
-      source.agentRef,
-      'the composition declares no `workspace.mountLayout` block — its ' +
-        'source workspace manifest was not projected by the llm-registry-api ' +
-        'composition seeder. Re-seed compositions (boot llm-registry-api) or ' +
-        'fix the source manifest.',
-    );
-  }
-
-  const [slug, version] = splitAgentRef(source.agentRef);
-
-  // Sub-agents the composition resolved become the manifest agent block's
-  // `subAgents[]`. The composer + EnvironmentResolver surface these on the
-  // resolved environment snapshot (drift detection). The intrinsic floor
-  // is still merged separately downstream — this is the manifest-declared
-  // layer only, exactly as a legacy manifest's `agent.subAgents` was.
-  const subAgents: ManifestSubAgent[] = source.subAgentBindings.map(
-    (binding) => ({
-      slug: binding.slug,
-      ...(binding.alias !== undefined ? { alias: binding.alias } : {}),
-      // Pass the overlay trio through to the manifest agent block so a
-      // resolved delegate's per-node `modelOverride` / `instructions` /
-      // `permission` are NOT dropped on reconstruction (the worker bug).
-      // `ManifestSubAgent.defaultModel` is the manifest DSL's name for the
-      // kernel `modelOverride` slot.
-      ...(binding.modelOverride !== undefined
-        ? { defaultModel: binding.modelOverride }
-        : {}),
-      ...(binding.instructions !== undefined
-        ? { instructions: binding.instructions }
-        : {}),
-      ...(binding.permission !== undefined
-        ? { permission: binding.permission }
-        : {}),
-    }),
-  );
-
-  // Raw fragments carried verbatim by the seeder. They are typed loosely
-  // on the wire (the seeder owns the shape); `compileManifest`'s Zod schema
-  // below re-validates them against the manifest DSL's authoritative
-  // `WorkspaceManifestSchema`, so the casts here are checked downstream,
-  // not silently trusted.
-  const outputSurface = projectOutputSurface(source.outputSurface);
-  const credentials = projectCredentials(source.credentials);
-  const permissions = projectPermissions(source.permissions);
-  const spec: WorkspaceManifestSpec = {
-    mounts: mountLayout.mounts as unknown as ManifestMountsBlock,
-    agent: {
-      slug: source.primaryAgentSlug,
-      stage: mountLayout.agentRunConfig.stage,
-      role: mountLayout.agentRunConfig.role as AgentRunRole,
-      ...(mountLayout.agentRunConfig.deliverableSpecRef !== undefined
-        ? { deliverableSpecRef: mountLayout.agentRunConfig.deliverableSpecRef }
-        : {}),
-      ...(subAgents.length > 0 ? { subAgents } : {}),
-    },
-    ...(Object.keys(mountLayout.inputs).length > 0
-      ? {
-          inputs: mountLayout.inputs as unknown as Record<
-            string,
-            ManifestInputDeclaration
-          >,
-        }
-      : {}),
-    ...(mountLayout.seedFiles.length > 0
-      ? {
-          seedFiles:
-            mountLayout.seedFiles as unknown as readonly ManifestSeedFile[],
-        }
-      : {}),
-    ...(outputSurface === undefined ? {} : { outputSurface }),
-    ...(credentials === undefined ? {} : { credentials }),
-    ...(permissions === undefined ? {} : { permissions }),
-    // Carry the authored working files through to `spec.workingFiles` so the
-    // compiled manifest the composer reads (`req.manifest.workingFiles`) binds
-    // the document file into `context.json.workingFiles` + narrows write
-    // authority. Without this the reconstruction path silently drops them and
-    // the agent sees no bound working file. `compileManifest`'s Zod schema
-    // re-validates the entries (and interpolates `${input.x}`).
-    ...(source.workingFiles && source.workingFiles.length > 0
-      ? { workingFiles: source.workingFiles }
-      : {}),
-  };
-
-  const envelope: DslWorkspaceManifest = {
-    apiVersion: 'xema.dev/workspace/v1',
-    kind: 'WorkspaceManifest',
-    metadata: {
-      slug,
-      version: toManifestVersion(source.agentRef, version),
-      // A manifest RECONSTRUCTED from a bare `agentRef` carries no inherent
-      // surface restriction — the SAME agent (e.g. `demo-runner`,
-      // `requirements-coordinator`) is legitimately driven on BOTH the
-      // agent-session surface (interactive bootstrap) AND the workflow surface
-      // (pipeline `xema/agent@v1` jobs). Defaulting to AGENT_SESSION only made
-      // every workflow agent run fail `assertSurfaceCompat` with
-      // "surfaceCompat=[agent-session] but was resolved on 'workflow'". Mirror
-      // the DSL compiler's permissive `DEFAULT_SURFACE_COMPAT` ([workflow,
-      // agent-session]); the runtime EnvironmentResolver still re-asserts the
-      // ACTUAL surface, so widening the reconstructed set cannot let an agent
-      // run somewhere its real manifest forbids — an authored manifest that
-      // explicitly narrows `surfaceCompat` is parsed via the DSL path, not here.
-      surfaceCompat: [ManifestSurface.WORKFLOW, ManifestSurface.AGENT_SESSION],
-    },
-    spec,
-  };
-
-  const result = compileManifest(envelope, bindInputs);
-  if (!result.ok) {
-    throw new AgentMountLayoutError(
-      source.agentRef,
-      `reconstructed manifest failed to compile: ${result.errors
-        .map((e) => `${e.path}: ${e.message}`)
-        .join('; ')}`,
-    );
-  }
-  return result.compiled;
-}
-
-/**
- * Project the composition's `workspace.outputSurface` block (carried on
- * the runtime-agnostic `AgentManifestSource`) into the manifest DSL's
- * `ManifestOutputSurface` shape so the reconstructed envelope's
- * `spec.outputSurface` carries the same kind/root/port as the source. The
- * `kind` value strings match the DSL enum 1:1 (`none` / `web` / `static` /
- * `app` / `tunnel`) so the cast is exact, not coerced.
- *
- * Returns `undefined` when the composition declared no surface — the DSL
- * `compileManifest` then defaults the compiled `outputSurface` to
- * `{ kind: 'none', autoOpen: false, mode: 'single' }`.
- */
-function projectOutputSurface(
-  surface: AgentOutputSurfaceInput | undefined,
-): ManifestOutputSurface | undefined {
-  if (!surface) return undefined;
-  return {
-    kind: surface.kind as OutputSurfaceKind,
-    ...(surface.port === undefined ? {} : { port: surface.port }),
-    ...(surface.healthPath === undefined
-      ? {}
-      : { healthPath: surface.healthPath }),
-    ...(surface.autoOpen === undefined ? {} : { autoOpen: surface.autoOpen }),
-    ...(surface.mode === undefined ? {} : { mode: surface.mode }),
-    ...(surface.root === undefined ? {} : { root: surface.root }),
-    ...(surface.defaultDocument === undefined
-      ? {}
-      : { defaultDocument: surface.defaultDocument }),
-  };
-}
-
-/**
- * Project the composition's `workspace.credentials` block (carried on the
- * runtime-agnostic `AgentManifestSource` as the kernel
- * `CompiledManifestCredential[]`) into the manifest DSL's authored
- * `ManifestCredential[]` shape so the reconstructed envelope's
- * `spec.credentials` carries the same entries as the source.
- *
- * The compiled shape is a structural superset of the authored shape
- * (`{name, kind, sourceRef}` plus a now-required `required` boolean), so the
- * projection is a 1:1 field copy — `compileManifest`'s Zod schema below
- * re-validates each entry and re-defaults `required` idempotently. The map
- * is explicit (not a pass-through cast) so a malformed entry fails fast at
- * the manifest compile boundary, mirroring {@link projectOutputSurface}.
- *
- * Returns `undefined` when the composition declared no credentials — the DSL
- * `compileManifest` then defaults the compiled `credentials` to `[]`.
- */
-function projectCredentials(
-  credentials: readonly CompiledManifestCredential[] | undefined,
-): readonly ManifestCredential[] | undefined {
-  if (credentials === undefined) return undefined;
-  return credentials.map((credential) => ({
-    name: credential.name,
-    kind: credential.kind,
-    sourceRef: credential.sourceRef,
-    required: credential.required,
-  }));
-}
-
-/**
- * Project the composition's `workspace.permissions` block (carried on the
- * runtime-agnostic `AgentManifestSource` as the kernel
- * `CompiledManifestPermissions`) into the manifest DSL's authored
- * `ManifestPermissions` shape so the reconstructed envelope's
- * `spec.permissions` carries the same tool allow/deny lists as the source.
- *
- * The compiled shape is a structural superset of the authored shape (the
- * compiled `tools.allow` / `tools.deny` are always present; the authored
- * ones are optional), so the projection is a 1:1 field copy —
- * `compileManifest`'s Zod schema below re-validates and re-defaults the
- * lists idempotently. Explicit (not a pass-through cast) so a malformed
- * block fails fast at the manifest compile boundary, mirroring
- * {@link projectOutputSurface}.
- *
- * Returns `undefined` when the composition declared no permissions — the DSL
- * `compileManifest` then defaults the compiled `permissions` to
- * `{ tools: { allow: [], deny: [] } }`.
- */
-function projectPermissions(
-  permissions: CompiledManifestPermissions | undefined,
-): ManifestPermissions | undefined {
-  if (permissions === undefined) return undefined;
-  return {
-    tools: {
-      allow: permissions.tools.allow,
-      deny: permissions.tools.deny,
-    },
-  };
-}
-
-/**
- * Build the manifest bind-input bag from the caller's explicit input bag
- * and the implicit inputs, validated against the composition's declared
- * `mountLayout.inputs`.
- *
- *   • an undeclared explicit input key fails fast;
- *   • a non-primitive / mixed-array input value fails fast;
- *   • a declared input with neither an explicit value nor an implicit
- *     value is simply omitted — the compiler then applies the input's
- *     own `default` (or fails fast if it is `required`).
- *
- * Returns `{}` when the composition declared no inputs.
- */
-export function buildAgentManifestBindInputs(
-  source: AgentManifestSource,
-  explicitInputs: Record<string, unknown> | null,
-  implicitInputs: AgentManifestImplicitInputs,
-): Readonly<Record<string, unknown>> {
-  const declared = new Set(Object.keys(source.mountLayout?.inputs ?? {}));
-  if (declared.size === 0) {
-    return {};
-  }
-
-  if (
-    explicitInputs !== null &&
-    (typeof explicitInputs !== 'object' || Array.isArray(explicitInputs))
-  ) {
-    throw new AgentMountLayoutError(
-      source.agentRef,
-      'explicit manifest inputs must be an object when provided',
-    );
-  }
-  const explicit = explicitInputs ?? {};
-  for (const [key, value] of Object.entries(explicit)) {
-    if (!declared.has(key)) {
-      throw new AgentMountLayoutError(
-        source.agentRef,
-        `manifest inputs contain undeclared key "${key}"`,
-      );
-    }
-    assertManifestInputValue(source.agentRef, key, value);
-  }
-
-  const implicit: Record<string, ManifestInputValue> = {
-    orgId: implicitInputs.orgId,
-    projectId: implicitInputs.projectId,
-    ...(implicitInputs.sessionId !== undefined
-      ? { sessionId: implicitInputs.sessionId }
-      : {}),
-  };
-
-  const out: Record<string, unknown> = {};
-  for (const key of declared) {
-    if (Object.hasOwn(explicit, key)) {
-      out[key] = explicit[key];
-      continue;
-    }
-    if (Object.hasOwn(implicit, key)) {
-      out[key] = implicit[key];
-    }
-  }
-  return out;
-}
-
-/** An authored manifest version: MAJOR.MINOR.PATCH. */
-const MANIFEST_SEMVER = /^\d+\.\d+\.\d+$/;
-/** An `AgentRef` version: the `AgentRevision.sequence` integer. */
-const AGENT_REVISION_SEQUENCE = /^\d+$/;
-
-/**
- * Map an `AgentRef` version onto `WorkspaceManifestMetadataSchema.version`.
- *
- * These are two different vocabularies and the reconstruction sits exactly on
- * the seam. An `AgentRef` is pinned by `AgentRevision.sequence` — a monotonic
- * INTEGER, so real refs look like `document-md-default@2`. The manifest schema
- * was written for AUTHORED YAML and requires MAJOR.MINOR.PATCH. Passing the
- * sequence straight through made `compileManifest` reject every reconstructed
- * manifest with "version must follow semver MAJOR.MINOR.PATCH", which is a
- * schema complaint about a field no author ever wrote.
- *
- * Sequence N maps to `N.0.0`: total, injective, and order-preserving, so
- * `drift-detector`'s version comparison keeps working and two distinct
- * revisions can never collide on one manifest version.
- *
- * A semver-shaped version passes through untouched — the legacy
- * `workspace-manifests-api` refs are genuinely semver, and this module serves
- * both. Anything else is REFUSED rather than coerced: a ref we cannot map is a
- * contract we do not understand, and inventing a version for it would put a
- * fabricated identity into the compiled manifest.
- */
-function toManifestVersion(agentRef: string, version: string): string {
-  if (MANIFEST_SEMVER.test(version)) {
-    return version;
-  }
-  if (AGENT_REVISION_SEQUENCE.test(version)) {
-    return `${version}.0.0`;
-  }
-  throw new AgentMountLayoutError(
-    agentRef,
-    `cannot map ref version "${version}" onto a manifest version — expected ` +
-      'either an AgentRevision sequence integer or semver MAJOR.MINOR.PATCH',
-  );
-}
-
-/** Split a `slug@version` composition ref; fail fast on a bare slug. */
-function splitAgentRef(ref: string): [slug: string, version: string] {
-  const at = ref.lastIndexOf('@');
-  if (at <= 0 || at === ref.length - 1) {
-    throw new AgentMountLayoutError(
-      ref,
-      'expected a version-pinned `slug@version` composition ref — the ' +
-        'session resolver always pins the resolved version',
-    );
-  }
-  return [ref.slice(0, at), ref.slice(at + 1)];
-}
-
-/**
- * Manifest inputs flow into seed-file templates via Handlebars
- * interpolation. Non-primitives produce `[object Object]` silently;
- * mixed-type arrays break string-array inputs. Reject both at the
- * boundary so the error surfaces near the cause.
- */
-function assertManifestInputValue(
-  agentRef: string,
-  key: string,
-  value: unknown,
-): void {
-  if (
-    value !== null &&
-    typeof value !== 'string' &&
-    typeof value !== 'number' &&
-    typeof value !== 'boolean' &&
-    !Array.isArray(value)
-  ) {
-    throw new AgentMountLayoutError(
-      agentRef,
-      `manifest input "${key}" must be a primitive ` +
-        `(string, number, boolean, string[]) — got ${typeof value}`,
-    );
-  }
-  if (
-    Array.isArray(value) &&
-    !value.every((entry) => typeof entry === 'string')
-  ) {
-    throw new AgentMountLayoutError(
-      agentRef,
-      `manifest input "${key}" is an array — every element must be a string`,
-    );
-  }
-}