@xemahq/agent-session-runtime 0.1.1

package/src/lib/composer.ts

@@ -0,0 +1,1041 @@
+import { createHash } from 'node:crypto';
+
+import {
+  AWP_V1_SPEC,
+  WorkspaceMount,
+  WorkspaceMountMode,
+  type SlotDefinition,
+  type WorkspaceMountPlan,
+  type WorkspaceMountPlanEntry,
+} from '@xemahq/kernel-contracts/agent-workspace';
+import {
+  BriefcaseReferenceKind,
+  type AgentRunRole,
+  type Briefcase,
+  type BriefcaseReference,
+  type BriefcaseUpload,
+  type CompiledWorkingFile,
+  type MountSource,
+  type RenderedAgentRunContextParams,
+} from '@xemahq/kernel-contracts/workflow';
+
+import { UnknownSlotError } from './errors';
+import type {
+  ComposeWorkspaceImageRequest,
+  WorkspaceImageComposer,
+} from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── WorkspaceImageComposer ──
+//
+// Turns a (manifest, bindInputs, agentContext) tuple into a typed
+// WorkspaceMountPlan. The plan is what the workspace-proxy
+// `/workspace/mounts/apply` handler resolves into bytes-on-disk.
+//
+// The composer auto-emits five platform-rendered slots from the agent
+// block (agents-md, context-json, agent-bundles per delegated subagent,
+// skill-bundles per skill, instructions). User-data slots are emitted
+// from the manifest's mounts block + agentContext refs.
+//
+// Resolution of WHICH agents/skills/instructions to mount happens
+// upstream in llm-registry-api (via the resolvers calling
+// `agent-run-context/render` and the per-resource bundle endpoints).
+// The composer only enumerates which `MountSource` discriminators to
+// emit; the resolver fetches the bytes at apply time.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Resolved agent metadata the caller passed in via `agentContext`.
+ * Keys are arbitrary; the composer recognizes a closed set of common
+ * keys to drive the platform-rendered slot emission and falls back to
+ * the manifest's declared agent block for everything else.
+ */
+interface AgentContextShape {
+  readonly delegatedSubAgents?: readonly string[];
+  readonly skills?: readonly string[];
+  readonly instructions?: readonly string[];
+  readonly inputsJsonBase64?: string;
+  readonly kbSpaceIds?: readonly string[];
+  /**
+   * Per-space page selections — emitted as `kb-pages` MountSource
+   * entries under `references/kb/<spaceId>/<pageSlug>.md`. Used by the
+   * runtime KB-mount feature on Interactive Sessions / Design System Builder
+   * (the user picks individual pages from a space to attach to a live
+   * session). Empty `pageSlugs` selections are dropped by the composer
+   * — fail-fast on an empty selection happens in the resolver.
+   */
+  readonly kbPageMounts?: ReadonlyArray<{
+    readonly spaceId: string;
+    readonly pageSlugs: readonly string[];
+  }>;
+  readonly externalProjectIds?: readonly string[];
+  readonly repoRef?: string;
+  readonly repoRevision?: string;
+  readonly deliverableSpecRef?: string;
+  readonly deliverablesRef?: string | readonly string[];
+  readonly sessionId?: string;
+  /**
+   * Per-job hand-off: artifact-store versions emitted by upstream jobs
+   * (typically `xema/http@v1` with `outputMode: artifact` or any
+   * `xema/emit-artifact@v1` step) that this agent should see as
+   * concrete files inside `/workspace/<slot>/<fileName>`. The agent
+   * reads them via its tool surface — they do NOT travel through
+   * `agent-run-context.workflowInputs.*` or the system prompt.
+   *
+   * Each entry specifies which workspace slot to mount into; the
+   * manifest MUST enable that slot or the composer fails fast at
+   * `extractInputArtifactSources`.
+   */
+  readonly inputArtifacts?: ReadonlyArray<InputArtifactRef>;
+}
+
+/**
+ * Wire shape for `agentContext.inputArtifacts[]`. Workflow authors
+ * populate these by referencing upstream outputs:
+ *
+ * ```yaml
+ * inputArtifacts:
+ *   - artifactId: ${{ needs.fetch.outputs.artifactId }}
+ *     version:    ${{ needs.fetch.outputs.version }}
+ *     fileName:   page.html
+ *     payloadField: body
+ * ```
+ *
+ * `slot` defaults to `inputs` — the canonical workspace slot for "data
+ * the workflow is feeding into this agent."
+ */
+export interface InputArtifactRef {
+  readonly artifactId: string;
+  readonly version: number;
+  readonly fileName: string;
+  readonly slot?: string;
+  readonly payloadField?: string;
+  readonly contentType?: string;
+}
+
+export class DefaultWorkspaceImageComposer implements WorkspaceImageComposer {
+  async compose(req: ComposeWorkspaceImageRequest): Promise<WorkspaceMountPlan> {
+    // Exactly-one-of invariant: the doc on `ComposeWorkspaceImageRequest`
+    // promises `workflowRun` xor `interactive`. Enforce it here so
+    // `deriveApplyId` can never collapse two unrelated requests onto a
+    // shared `applyId` (which would let workspace-proxy dedup
+    // unrelated mounts). No silent fallback per the engineering
+    // constitution.
+    const hasWorkflow = req.workflowRun !== undefined;
+    const hasInteractive = req.interactive !== undefined;
+    if (hasWorkflow === hasInteractive) {
+      throw new Error(
+        `ComposeWorkspaceImageRequest must declare exactly one of \`workflowRun\` or \`interactive\` (got workflowRun=${hasWorkflow}, interactive=${hasInteractive}).`,
+      );
+    }
+    const ctx = req.agentContext as AgentContextShape;
+    // Surface discriminator. The xor-checked `workflowRun` / `interactive`
+    // fields above ARE the kernel surface signal; we project them onto a
+    // boolean here for the gates further down. Workflow content
+    // (deliverable specs, input artifacts, deliverables) must never leak
+    // into a session surface — fail-fast per CLAUDE.md.
+    const isWorkflowSurface = hasWorkflow;
+    if (!isWorkflowSurface) {
+      // Hard-assert: a session must not be built with any workflow-only
+      // payload. This catches the "wrong agentContext fed into the session
+      // bootstrap" class of misuse before it materialises on disk.
+      if (ctx.inputArtifacts !== undefined && ctx.inputArtifacts.length > 0) {
+        throw new Error(
+          'WorkspaceImageComposer: agent-session surface received non-empty `agentContext.inputArtifacts` — input artifacts are a workflow-only concept. Drop the field or switch to a workflow surface.',
+        );
+      }
+      if (
+        ctx.deliverableSpecRef !== undefined ||
+        ctx.deliverablesRef !== undefined ||
+        req.agentOverrides?.deliverableSpecRef !== undefined ||
+        req.manifest.agent.deliverableSpecRef !== undefined
+      ) {
+        throw new Error(
+          'WorkspaceImageComposer: agent-session surface received a deliverable-spec / deliverables reference — deliverables are a workflow-only concept. Drop `deliverableSpecRef` / `deliverablesRef` for session calls, or switch to a workflow surface.',
+        );
+      }
+    }
+    // Role is caller-supplied. The silent `?? manifest.agent.role`
+    // fallback was removed as part of the unified-role refactor — every
+    // caller (worker activity, agent-session bootstrap, future
+    // entry points) MUST set `agentOverrides.role` explicitly. This
+    // prevents the class of bugs where a manifest declared the wrong
+    // role and the runtime silently propagated it to the wrong template.
+    if (req.agentOverrides?.role === undefined) {
+      throw new Error(
+        'ComposeWorkspaceImageRequest.agentOverrides.role is required — pass `manifest.agent.role` explicitly so the renderer can validate role-vs-surface up front.',
+      );
+    }
+    const role: AgentRunRole = req.agentOverrides.role;
+    const deliverableSpecRef =
+      req.agentOverrides?.deliverableSpecRef ??
+      req.manifest.agent.deliverableSpecRef ??
+      ctx.deliverableSpecRef;
+
+    const entries: WorkspaceMountPlanEntry[] = [];
+
+    // ── Platform-rendered single-file slots ───────────────────────────
+    // The three rendered-* sources (agents-md, context-json, system-overlay)
+    // all dispatch to llm-registry's `agent-run-context/render`, which
+    // returns `{agentsMd, contextJson, systemOverlay}` in a single
+    // response. Building them from one shared param object guarantees
+    // they hash to the same workspace-proxy cache key — so one
+    // mount-apply triggers exactly one upstream render call (instead of
+    // three) and the three slots are guaranteed to come from the same
+    // render snapshot. Diverging the params is a silent perf+consistency
+    // bug; do not do it.
+    // Workflow-only: `context.json.workflowInputs.*` is the workflow
+    // engine's `with:` block projection. Sessions have no such concept;
+    // surfacing it would be a lie. The hard-assert above ensures no
+    // workflow-only fields slip through; we still drop the projection
+    // here as a defence-in-depth.
+    const workflowInputs = isWorkflowSurface
+      ? pickWorkflowInputs(req.agentContext)
+      : null;
+    const renderedMounts = buildRenderedMounts(
+      req.manifest.mounts,
+      req.manifest.slug,
+      req.manifest.version,
+    );
+    const renderedInputArtifacts = buildRenderedInputArtifacts(ctx.inputArtifacts);
+    const renderedWorkingFiles = buildRenderedWorkingFiles(req.manifest.workingFiles);
+    const renderedSourceParams: RenderedAgentRunContextParams = {
+      orgId: req.orgId,
+      projectId: req.projectId,
+      agentSlug: req.manifest.agent.slug,
+      groupKey: req.manifest.agent.groupKey,
+      role,
+      ...(deliverableSpecRef === undefined ? {} : { deliverableSpecRef }),
+      ...(req.workflowRun?.runId === undefined ? {} : { runId: req.workflowRun.runId }),
+      ...(req.workflowRun?.jobRunId === undefined ? {} : { jobRunId: req.workflowRun.jobRunId }),
+      ...(req.interactive?.sessionId === undefined
+        ? {}
+        : { sessionId: req.interactive.sessionId }),
+      ...(workflowInputs === null ? {} : { workflowInputs }),
+      ...(renderedMounts.length === 0 ? {} : { mounts: renderedMounts }),
+      ...(renderedInputArtifacts.length === 0
+        ? {}
+        : { inputArtifacts: renderedInputArtifacts }),
+      ...(renderedWorkingFiles.length === 0
+        ? {}
+        : { workingFiles: renderedWorkingFiles }),
+    };
+
+    entries.push(
+      buildEntry({
+        slot: WorkspaceMount.AgentsMd,
+        relPath: '',
+        mode: WorkspaceMountMode.ReadOnly,
+        mountKey: 'agents-md',
+        source: { kind: 'rendered-agents-md', ...renderedSourceParams },
+      }),
+    );
+
+    entries.push(
+      buildEntry({
+        slot: WorkspaceMount.ContextJson,
+        relPath: '',
+        mode: WorkspaceMountMode.ReadOnly,
+        mountKey: 'context-json',
+        source: { kind: 'rendered-context-json', ...renderedSourceParams },
+      }),
+    );
+
+    entries.push(
+      buildEntry({
+        slot: WorkspaceMount.SystemOverlay,
+        relPath: '',
+        mode: WorkspaceMountMode.ReadOnly,
+        mountKey: 'system-overlay',
+        source: { kind: 'rendered-system-overlay', ...renderedSourceParams },
+      }),
+    );
+
+    // ── /workspace/tmp (scratch space) ──
+    // Always-on, read-write, tarball-persisted. Empty seed so the
+    // directory exists from session start; agents drop scratch files in
+    // and snapshots carry them across retries automatically.
+    entries.push(
+      buildEntry({
+        slot: WorkspaceMount.Tmp,
+        relPath: '.keep',
+        mode: WorkspaceMountMode.ReadWrite,
+        mountKey: 'tmp:seed',
+        source: {
+          kind: 'static-literal',
+          pathWithinWorkspace: 'tmp/.keep',
+          bytes: '',
+        },
+      }),
+    );
+
+    // ── Agent bundles (primary + delegated subagents) ─────────────────
+    entries.push(
+      buildEntry({
+        slot: WorkspaceMount.AgentBundles,
+        relPath: `${req.manifest.agent.slug}.md`,
+        mode: WorkspaceMountMode.ReadOnly,
+        mountKey: `agent-bundle:${req.manifest.agent.slug}`,
+        source: {
+          kind: 'agent-definition',
+          orgId: req.orgId,
+          agentSlug: req.manifest.agent.slug,
+          groupKey: req.manifest.agent.groupKey,
+          agentMode: 'primary',
+        },
+      }),
+    );
+    for (const sub of ctx.delegatedSubAgents ?? []) {
+      if (sub === req.manifest.agent.slug) continue; // primary already emitted
+      entries.push(
+        buildEntry({
+          slot: WorkspaceMount.AgentBundles,
+          relPath: `${sub}.md`,
+          mode: WorkspaceMountMode.ReadOnly,
+          mountKey: `agent-bundle:${sub}`,
+          source: {
+            kind: 'agent-definition',
+            orgId: req.orgId,
+            agentSlug: sub,
+            groupKey: req.manifest.agent.groupKey,
+            agentMode: 'subagent',
+          },
+        }),
+      );
+    }
+
+    // ── Skill bundles + /skill launch commands ────────────────────────
+    // Each skill is a multi-file BUNDLE (SKILL.md + bundled resources).
+    // The entry's relPath is the skill DIRECTORY; the `skill-bundle`
+    // resolver yields one file per bundle member, so the writer composes
+    // `<skill-bundles slot>/<skillKey>/<resolver relPath>`.
+    //
+    // Alongside each bundle we emit one OpenCode command file so typing
+    // `/<skillKey>` in a session loads and applies that skill natively.
+    //
+    // Kernel-shipped System skills are PREPENDED to whatever skills the
+    // caller already named in `agentContext.skills` (see
+    // `.claude/rules/skills-and-composition.md` — `SkillSpace.System`
+    // skills are auto-injected into every agent's mounted bundle).
+    // `dedupe` collapses any overlap so a caller that re-mentions a
+    // System skill in `agentContext.skills` does not double-mount it.
+    for (const skillKey of dedupe([
+      ...(req.systemSkillSlugs ?? []),
+      ...(ctx.skills ?? []),
+    ])) {
+      entries.push(
+        buildEntry({
+          slot: WorkspaceMount.SkillBundles,
+          relPath: skillKey,
+          mode: WorkspaceMountMode.ReadOnly,
+          mountKey: `skill-bundle:${skillKey}`,
+          source: {
+            kind: 'skill-bundle',
+            skillKey,
+          },
+        }),
+      );
+      const commandRelPath = `${skillKey}.md`;
+      entries.push(
+        buildEntry({
+          slot: WorkspaceMount.Commands,
+          relPath: commandRelPath,
+          mode: WorkspaceMountMode.ReadOnly,
+          mountKey: `skill-command:${skillKey}`,
+          source: {
+            kind: 'static-literal',
+            pathWithinWorkspace: `.opencode/command/${commandRelPath}`,
+            bytes: Buffer.from(renderSkillCommand(skillKey), 'utf8').toString(
+              'base64',
+            ),
+          },
+        }),
+      );
+    }
+
+    // ── Instruction sections ──────────────────────────────────────────
+    for (const sectionKey of dedupe(ctx.instructions ?? [])) {
+      entries.push(
+        buildEntry({
+          slot: WorkspaceMount.Instructions,
+          relPath: `${sectionKey}.md`,
+          mode: WorkspaceMountMode.ReadOnly,
+          mountKey: `instruction:${sectionKey}`,
+          source: {
+            kind: 'instruction-section',
+            orgId: req.orgId,
+            sectionKey,
+            agentSlug: req.manifest.agent.slug,
+            groupKey: req.manifest.agent.groupKey,
+          },
+        }),
+      );
+    }
+
+    // ── Input artifacts (workflow-step output → file in workspace) ──
+    // Walks `agentContext.inputArtifacts[]` and lands each artifact
+    // version as a single file under its target slot. Slot defaults to
+    // `inputs`. The slot MUST be enabled in the manifest — otherwise
+    // the workspace-proxy authority guard would reject any tool read on
+    // the resulting path, and the workflow author wants a hard signal
+    // not a silent skip.
+    //
+    // Workflow-surface only: the hard-assert at the top of compose()
+    // guarantees `ctx.inputArtifacts` is empty on session surfaces, so
+    // this loop is effectively a no-op there.
+    const enabledSlots = new Set(
+      Object.entries(req.manifest.mounts)
+        .filter(([, decl]) => decl.enabled)
+        .map(([slotKey]) => slotKey),
+    );
+    for (const ia of ctx.inputArtifacts ?? []) {
+      const slotKey = ia.slot ?? 'inputs';
+      if (!enabledSlots.has(slotKey)) {
+        throw new Error(
+          `WorkspaceImageComposer: agentContext.inputArtifacts targets slot '${slotKey}' but the manifest '${req.manifest.slug}@${req.manifest.version}' does not enable it. ` +
+            `Enable the slot in the agent manifest or change the inputArtifact's 'slot' to one of: [${[...enabledSlots].join(', ') || '(none)'}].`,
+        );
+      }
+      const slotDef = AWP_V1_SPEC.slots.find((s) => s.key === slotKey);
+      if (!slotDef) {
+        throw new UnknownSlotError(
+          slotKey,
+          'inputArtifacts',
+          req.manifest.slug,
+          req.manifest.version,
+        );
+      }
+      const fileName = ia.fileName.trim();
+      if (fileName.length === 0 || fileName.includes('..') || fileName.startsWith('/')) {
+        throw new Error(
+          `WorkspaceImageComposer: inputArtifact fileName '${ia.fileName}' is invalid — must be a non-empty relative path without '..' segments.`,
+        );
+      }
+      entries.push(
+        buildEntry({
+          slot: slotDef.path as WorkspaceMount,
+          relPath: fileName,
+          mode: WorkspaceMountMode.ReadOnly,
+          mountKey: `input-artifact:${ia.artifactId}:v${ia.version}:${fileName}`,
+          source: {
+            kind: 'artifact-version',
+            artifactId: ia.artifactId,
+            version: ia.version,
+            fileName,
+            ...(ia.payloadField !== undefined && { payloadField: ia.payloadField }),
+            ...(ia.contentType !== undefined && { contentType: ia.contentType }),
+          },
+        }),
+      );
+    }
+
+    // ── User-data mounts (manifest-declared) ──────────────────────────
+    for (const [slotKey, decl] of Object.entries(req.manifest.mounts)) {
+      if (!decl.enabled) continue;
+      const slotDef = AWP_V1_SPEC.slots.find((s) => s.key === slotKey);
+      if (!slotDef) {
+        throw new UnknownSlotError(
+          slotKey,
+          'manifest.mounts',
+          req.manifest.slug,
+          req.manifest.version,
+        );
+      }
+      const mode = decl.mode ?? slotDef.defaultMode;
+      const mountMode =
+        mode === 'read-write' ? WorkspaceMountMode.ReadWrite : WorkspaceMountMode.ReadOnly;
+      const sources = extractMountSourcesForSlot(
+        slotKey,
+        decl,
+        ctx,
+        deliverableSpecRef,
+        req.briefcase,
+        isWorkflowSurface,
+      );
+      for (const { source, relPath, mountKey } of sources) {
+        entries.push(
+          buildEntry({
+            slot: slotDef.path as WorkspaceMount,
+            relPath,
+            mode: mountMode,
+            mountKey,
+            source,
+          }),
+        );
+      }
+    }
+
+    // ── Manifest seed files (inline literal or resolved template) ─────
+    if (
+      req.manifest.requiredTemplateNames.length > 0 &&
+      req.templateResolver === undefined
+    ) {
+      throw new Error(
+        `WorkspaceImageComposer: manifest '${req.manifest.slug}@${req.manifest.version}' references templates ` +
+          `[${req.manifest.requiredTemplateNames.join(', ')}] but no templateResolver was supplied.`,
+      );
+    }
+    for (const sf of req.manifest.seedFiles) {
+      const slotDef = AWP_V1_SPEC.slots.find((s) => s.key === sf.slot);
+      if (!slotDef) {
+        throw new UnknownSlotError(
+          sf.slot,
+          'manifest.seedFiles',
+          req.manifest.slug,
+          req.manifest.version,
+        );
+      }
+      let bytesBase64: string;
+      if (sf.source.kind === 'inline') {
+        bytesBase64 = sf.source.bytesBase64;
+      } else {
+        const rendered = await req.templateResolver!.resolve(
+          sf.source.name,
+          sf.source.vars,
+        );
+        bytesBase64 = Buffer.from(rendered, 'utf8').toString('base64');
+      }
+      // `entry.relPath` is the file's location within the slot — used by
+      // the plan validator to dedup target paths AND by the writer as the
+      // file's final position. `source.pathWithinWorkspace` is identity
+      // metadata only (audit/telemetry), redundantly carrying the same
+      // value. The static-literal resolver yields `sub.relPath: ''` so
+      // the writer composes `<slot>/<entry.relPath>/<''>` → `<slot>/<entry.relPath>`,
+      // which is exactly what we want.
+      entries.push(
+        buildEntry({
+          slot: slotDef.path as WorkspaceMount,
+          relPath: sf.relPath,
+          mode: WorkspaceMountMode.ReadOnly,
+          mountKey: `seed:${sf.slot}:${sf.relPath}`,
+          source: {
+            kind: 'static-literal',
+            pathWithinWorkspace: sf.relPath,
+            bytes: bytesBase64,
+          },
+        }),
+      );
+    }
+
+    return {
+      applyId: deriveApplyId(req),
+      entries,
+    };
+  }
+}
+
+/**
+ * Stable apply-id — feeds the workspace-proxy lease key.
+ *
+ * Includes manifest slug + version + a content hash of the manifest's
+ * mount-affecting blocks (`agent`, `mounts`, `seedFiles`,
+ * `requiredTemplateNames`, `extends`). The content hash defends against
+ * the failure mode where a manifest is mutated in place without bumping
+ * `version` — without it, workspace-proxy would serve stale mounts from
+ * a cached lease keyed only on the unchanged version. The bind inputs
+ * hash + scopeId ensure cross-run / cross-input isolation.
+ *
+ * Hash is base16; collision probability is negligible at the per-lease
+ * scale we operate at.
+ */
+function deriveApplyId(req: ComposeWorkspaceImageRequest): string {
+  // Exactly one of the two is set — enforced at the top of compose().
+  const scopeId = req.workflowRun
+    ? `wf:${req.workflowRun.runId}:${req.workflowRun.jobRunId}`
+    : `is:${req.interactive!.sessionId}:${req.interactive!.turnGen ?? 0}`;
+  const inputsHash = createHash('sha256')
+    .update(JSON.stringify(stableSort(req.agentContext)))
+    .digest('hex')
+    .slice(0, 16);
+  const manifestContentHash = deriveManifestContentHash(req.manifest);
+  const components = [
+    req.orgId,
+    req.projectId,
+    req.manifest.slug,
+    req.manifest.version,
+    manifestContentHash,
+    req.manifest.agent.slug,
+    req.agentOverrides?.role ?? req.manifest.agent.role,
+    inputsHash,
+    scopeId,
+  ];
+  return createHash('sha256').update(components.join(':')).digest('hex');
+}
+
+/**
+ * Hash the manifest fields that drive mount composition. A change to
+ * any of these fields produces a different `applyId`, forcing
+ * workspace-proxy to allocate a fresh lease and re-resolve mounts. Any
+ * non-mount field (`description`, `metadata.author`, …) is excluded so
+ * cosmetic edits don't churn the lease.
+ */
+function deriveManifestContentHash(
+  manifest: ComposeWorkspaceImageRequest['manifest'],
+): string {
+  // `extends` is already flattened into `agent`/`mounts`/`seedFiles`/`env`
+  // by the DSL compiler, so hashing those four fields captures the
+  // effective workspace shape after inheritance.
+  const projection = {
+    agent: manifest.agent,
+    mounts: manifest.mounts,
+    seedFiles: manifest.seedFiles,
+    env: manifest.env,
+    requiredTemplateNames: manifest.requiredTemplateNames,
+  };
+  return createHash('sha256')
+    .update(JSON.stringify(stableSort(projection)))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function stableSort(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(stableSort);
+  const obj = value as Record<string, unknown>;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = stableSort(obj[key]);
+  }
+  return sorted;
+}
+
+function dedupe<T>(items: readonly T[]): readonly T[] {
+  return Array.from(new Set(items));
+}
+
+/**
+ * The OpenCode command-file body for a `/skill` launch command. Typing
+ * `/<skillKey>` in a session expands to this prompt — load the skill,
+ * then act on whatever the user passed as arguments.
+ */
+function renderSkillCommand(skillKey: string): string {
+  return [
+    '---',
+    `description: Load and apply the ${skillKey} skill`,
+    '---',
+    `Load and apply the \`${skillKey}\` skill, then act on the request: $ARGUMENTS`,
+    '',
+  ].join('\n');
+}
+
+function buildEntry(args: {
+  slot: WorkspaceMount;
+  relPath: string;
+  mode: WorkspaceMountMode;
+  mountKey: string;
+  source: MountSource;
+}): WorkspaceMountPlanEntry {
+  return {
+    mountKey: args.mountKey,
+    slot: args.slot,
+    relPath: args.relPath,
+    mode: args.mode,
+    source: args.source,
+  };
+}
+
+interface ExtractedMountSource {
+  readonly source: MountSource;
+  readonly relPath: string;
+  readonly mountKey: string;
+}
+
+/**
+ * Translate a manifest mount declaration + agentContext into one or
+ * more concrete MountSources. Closed switch on slot key — adding a
+ * new user-data slot requires extending here.
+ */
+function extractMountSourcesForSlot(
+  slotKey: string,
+  _decl: { readonly config: Readonly<Record<string, unknown>> },
+  ctx: AgentContextShape,
+  deliverableSpecRef: string | undefined,
+  briefcase: Briefcase | undefined,
+  isWorkflowSurface: boolean,
+): readonly ExtractedMountSource[] {
+  switch (slotKey) {
+    case 'inputs':
+      // Workflow-only slot. The inputs slot carries the rendered
+      // inputs.json blob serialized from workflow `with:` inputs;
+      // sessions have no such concept — the hard-assert at the top of
+      // compose() ensures workflow-only payloads never reach a session,
+      // and this guard makes the rule explicit at the source-extractor
+      // boundary too.
+      if (!isWorkflowSurface) return [];
+      if (!ctx.inputsJsonBase64) return [];
+      return [
+        {
+          source: {
+            kind: 'static-literal',
+            pathWithinWorkspace: 'inputs.json',
+            bytes: ctx.inputsJsonBase64,
+          },
+          relPath: 'inputs.json',
+          mountKey: 'inputs:json',
+        },
+      ];
+    case 'uploads':
+      return extractBriefcaseUploadMounts(briefcase?.uploads);
+    case 'references': {
+      const out: ExtractedMountSource[] = [];
+      for (const spaceId of dedupe(ctx.kbSpaceIds ?? [])) {
+        out.push({
+          source: { kind: 'kb-space', spaceId },
+          relPath: `kb/${spaceId}`,
+          mountKey: `references:kb:${spaceId}`,
+        });
+      }
+      for (const mount of ctx.kbPageMounts ?? []) {
+        const pageSlugs = dedupe(mount.pageSlugs);
+        if (pageSlugs.length === 0) continue;
+        out.push({
+          source: { kind: 'kb-pages', spaceId: mount.spaceId, pageSlugs },
+          relPath: `kb/${mount.spaceId}`,
+          // Mount-key disambiguates from the kb-space entry on the same
+          // space when both coexist — e.g. user mounted the whole space
+          // and later pinned additional specific pages. Slot promote
+          // does an atomic `rm -rf` + rename so the two entries' files
+          // coexist under `references/kb/<spaceId>/` after apply.
+          mountKey: `references:kb-pages:${mount.spaceId}`,
+        });
+      }
+      for (const projectId of dedupe(ctx.externalProjectIds ?? [])) {
+        out.push({
+          source: { kind: 'scm-repo', repoRef: projectId, ref: 'HEAD' },
+          relPath: `external-projects/${projectId}`,
+          mountKey: `references:project:${projectId}`,
+        });
+      }
+      for (const entry of extractBriefcaseReferenceMounts(briefcase?.references)) {
+        out.push(entry);
+      }
+      return out;
+    }
+    case 'repos':
+      if (!ctx.repoRef) return [];
+      return [
+        {
+          source: {
+            kind: 'scm-repo',
+            repoRef: ctx.repoRef,
+            ref: ctx.repoRevision ?? 'HEAD',
+          },
+          relPath: ctx.repoRef,
+          mountKey: `repo:${ctx.repoRef}`,
+        },
+      ];
+    case 'deliverable-specs':
+      // Workflow-only slot. Sessions never harvest deliverables, so a
+      // spec mount would be dead weight at best, misleading at worst.
+      // The compose()-level hard-assert ensures `deliverableSpecRef` is
+      // undefined on session surfaces, but we mirror the gate here so
+      // the slot-extractor switch is the single readable place that
+      // documents which slots are workflow-only.
+      if (!isWorkflowSurface) return [];
+      if (!deliverableSpecRef) return [];
+      return [
+        {
+          source: { kind: 'deliverable-specs', contractKey: deliverableSpecRef },
+          relPath: deliverableSpecRef,
+          mountKey: `deliverable-specs:${deliverableSpecRef}`,
+        },
+      ];
+    case 'deliverables': {
+      // Workflow-only slot — same rationale as `deliverable-specs`.
+      if (!isWorkflowSurface) return [];
+      const refs = ctx.deliverablesRef
+        ? Array.isArray(ctx.deliverablesRef)
+          ? ctx.deliverablesRef
+          : [ctx.deliverablesRef]
+        : [];
+      return refs.map((contractKey) => ({
+        source: { kind: 'deliverables', contractKey },
+        relPath: contractKey,
+        mountKey: `deliverables:${contractKey}`,
+      }));
+    }
+    case 'attachments':
+      if (!ctx.sessionId) return [];
+      return [
+        {
+          source: { kind: 'session-attachment', sessionId: ctx.sessionId },
+          relPath: '',
+          mountKey: `attachments:${ctx.sessionId}`,
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Project `briefcase.uploads[]` onto `artifact-version` MountSources
+ * under the `uploads` AWP slot. Each upload becomes one file at
+ * `/workspace/uploads/<filename>`. Empty filenames or paths containing
+ * traversal segments fail fast — the dispatch endpoint already
+ * validates these but we re-check at compose time so an in-memory
+ * mutation can never write outside the slot.
+ */
+function extractBriefcaseUploadMounts(
+  uploads: readonly BriefcaseUpload[] | undefined,
+): readonly ExtractedMountSource[] {
+  if (!uploads || uploads.length === 0) return [];
+  return uploads.map((u) => {
+    const fileName = u.filename.trim();
+    if (fileName.length === 0 || fileName.includes('..') || fileName.startsWith('/')) {
+      throw new Error(
+        `WorkspaceImageComposer: briefcase upload filename '${u.filename}' is invalid — must be a non-empty relative path without '..' segments.`,
+      );
+    }
+    return {
+      source: {
+        kind: 'artifact-version',
+        artifactId: u.artifact.artifactId,
+        version: u.artifact.version,
+        fileName,
+        ...(u.contentType !== null ? { contentType: u.contentType } : {}),
+      },
+      relPath: fileName,
+      mountKey: `briefcase-upload:${u.artifact.artifactId}:v${u.artifact.version}`,
+    } satisfies ExtractedMountSource;
+  });
+}
+
+/**
+ * Project `briefcase.references[]` onto MountSources under the
+ * `references` AWP slot. Each reference kind maps to the
+ * already-supported MountSource kind:
+ *
+ *   - `kb_page`      → `kb-pages` (single page, ref is `<spaceId>/<slug>`)
+ *   - `kb_space`     → `kb-space` (whole space, ref is `<spaceId>`)
+ *   - `artifact`     → `artifact-version` (ref is `<artifactId>@<version>`)
+ *   - `scm_repo`     → `scm-repo` (ref is `<repoRef>@<gitRef>` or `<repoRef>`)
+ *   - `external_url` → skipped (no on-disk file; surfaces via
+ *     context.json only — agents see it under workflowInputs)
+ */
+function extractBriefcaseReferenceMounts(
+  references: readonly BriefcaseReference[] | undefined,
+): readonly ExtractedMountSource[] {
+  if (!references || references.length === 0) return [];
+  const out: ExtractedMountSource[] = [];
+  for (const ref of references) {
+    const entry = briefcaseReferenceToMount(ref);
+    if (entry !== null) out.push(entry);
+  }
+  return out;
+}
+
+function briefcaseReferenceToMount(ref: BriefcaseReference): ExtractedMountSource | null {
+  switch (ref.kind) {
+    case BriefcaseReferenceKind.KB_SPACE:
+      return {
+        source: { kind: 'kb-space', spaceId: ref.ref },
+        relPath: `kb/${ref.ref}`,
+        mountKey: `briefcase-reference:kb-space:${ref.ref}`,
+      };
+    case BriefcaseReferenceKind.KB_PAGE: {
+      // ref shape: `<spaceId>/<pageSlug>` (matches the canonical
+      // /kb/spaces/:slug/pages/:pageSlug route used elsewhere).
+      const sep = ref.ref.indexOf('/');
+      if (sep <= 0 || sep === ref.ref.length - 1) {
+        throw new Error(
+          `briefcase reference kind=kb_page must encode ref as '<spaceId>/<pageSlug>' (got '${ref.ref}').`,
+        );
+      }
+      const spaceId = ref.ref.slice(0, sep);
+      const pageSlug = ref.ref.slice(sep + 1);
+      return {
+        source: { kind: 'kb-pages', spaceId, pageSlugs: [pageSlug] },
+        relPath: `kb/${spaceId}`,
+        mountKey: `briefcase-reference:kb-page:${spaceId}:${pageSlug}`,
+      };
+    }
+    case BriefcaseReferenceKind.ARTIFACT: {
+      // ref shape: `<artifactId>@<version>` (integer version, matches
+      // the artifact-store address scheme).
+      const at = ref.ref.lastIndexOf('@');
+      if (at <= 0) {
+        throw new Error(
+          `briefcase reference kind=artifact must encode ref as '<artifactId>@<version>' (got '${ref.ref}').`,
+        );
+      }
+      const artifactId = ref.ref.slice(0, at);
+      const version = Number.parseInt(ref.ref.slice(at + 1), 10);
+      if (!Number.isInteger(version) || version < 1) {
+        throw new Error(
+          `briefcase reference kind=artifact has invalid version in '${ref.ref}' — must be a positive integer.`,
+        );
+      }
+      const trimmedTitle = ref.title?.trim() ?? '';
+      const fileName = trimmedTitle.length > 0 ? trimmedTitle : `${artifactId}-v${version}`;
+      return {
+        source: {
+          kind: 'artifact-version',
+          artifactId,
+          version,
+          fileName,
+        },
+        relPath: fileName,
+        mountKey: `briefcase-reference:artifact:${artifactId}:v${version}`,
+      };
+    }
+    case BriefcaseReferenceKind.SCM_REPO: {
+      // ref shape: `<repoRef>` or `<repoRef>@<gitRef>`. The repoRef is
+      // opaque to the composer; the SCM resolver decodes it.
+      const at = ref.ref.indexOf('@');
+      const repoRef = at < 0 ? ref.ref : ref.ref.slice(0, at);
+      const gitRef = at < 0 ? 'HEAD' : ref.ref.slice(at + 1);
+      return {
+        source: { kind: 'scm-repo', repoRef, ref: gitRef },
+        relPath: `scm/${repoRef}`,
+        mountKey: `briefcase-reference:scm:${repoRef}:${gitRef}`,
+      };
+    }
+    case BriefcaseReferenceKind.EXTERNAL_URL:
+      // No on-disk mount — the URL surfaces via context.json's
+      // workflowInputs projection. Audit trail logs the ref.
+      return null;
+    default:
+      throw new Error(
+        `Unhandled briefcase reference kind '${(ref as { kind: string }).kind}'.`,
+      );
+  }
+}
+
+// Static-only assertion that AWP slot `path`s align with the
+// WorkspaceMount enum we depend on. Kept here so a kernel slot rename
+// fails fast at build time.
+function _assertSlotsCover(): SlotDefinition[] {
+  return [...AWP_V1_SPEC.slots];
+}
+void _assertSlotsCover;
+
+/**
+ * Drop the keys the composer itself consumes (subagents, skills, mount
+ * routing hints, etc.) so the remainder is what the caller passed as
+ * actual workflow inputs (e.g. the user's request text). Returns null
+ * when nothing remains so the rendered-context-json source can omit the
+ * field entirely instead of carrying an empty object.
+ */
+function pickWorkflowInputs(
+  agentContext: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> | null {
+  const COMPOSER_RESERVED = new Set<string>([
+    'delegatedSubAgents',
+    'skills',
+    'instructions',
+    'inputsJsonBase64',
+    'kbSpaceIds',
+    'kbPageMounts',
+    'externalProjectIds',
+    'repoRef',
+    'repoRevision',
+    'deliverableSpecRef',
+    'deliverablesRef',
+    'sessionId',
+    'inputArtifacts',
+  ]);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(agentContext)) {
+    if (COMPOSER_RESERVED.has(k)) continue;
+    if (v === undefined) continue;
+    out[k] = v;
+  }
+  return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * Project the manifest's mount declarations into the wire shape the
+ * llm-registry renderer consumes — `{ mount: '/workspace/<slot>', mode }`.
+ * The renderer derives `context.json.authority.mayWriteWorkspace[]` from
+ * this list; the system overlay surfaces it to the agent as the
+ * authoritative writable-paths declaration. Disabled mounts are dropped.
+ *
+ * Unknown slot keys throw `UnknownSlotError` — same fail-fast contract
+ * as the user-data loop, so a manifest typo or stale slot name
+ * surfaces at the first compose call instead of materializing an
+ * incomplete `mayWriteWorkspace[]`.
+ */
+/**
+ * Project the workflow-supplied input artifacts into the renderer
+ * wire shape: an absolute workspace path the agent reads from, plus the
+ * artifact lineage for traceability. The renderer surfaces these in
+ * AGENTS.md (`# Inputs`) and `context.json.workflow.inputArtifacts[]`,
+ * so the agent doesn't have to ls slot directories to discover them.
+ */
+function buildRenderedInputArtifacts(
+  inputArtifacts: readonly InputArtifactRef[] | undefined,
+): ReadonlyArray<{
+  readonly path: string;
+  readonly contentType?: string;
+  readonly sourceArtifactId: string;
+  readonly sourceVersion: number;
+}> {
+  if (!inputArtifacts || inputArtifacts.length === 0) return [];
+  const out: Array<{
+    path: string;
+    contentType?: string;
+    sourceArtifactId: string;
+    sourceVersion: number;
+  }> = [];
+  for (const ia of inputArtifacts) {
+    const slotKey = ia.slot ?? 'inputs';
+    const slotDef = AWP_V1_SPEC.slots.find((s) => s.key === slotKey);
+    if (!slotDef) continue;
+    out.push({
+      path: `${slotDef.path}/${ia.fileName}`,
+      ...(ia.contentType !== undefined && { contentType: ia.contentType }),
+      sourceArtifactId: ia.artifactId,
+      sourceVersion: ia.version,
+    });
+  }
+  return out;
+}
+
+/**
+ * Project compiled working-file bindings onto the render-request wire shape
+ * so llm-registry can surface them on `context.json.workingFiles`.
+ */
+function buildRenderedWorkingFiles(
+  workingFiles: readonly CompiledWorkingFile[] | undefined,
+): 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>>;
+}> {
+  if (!workingFiles || workingFiles.length === 0) return [];
+  return workingFiles.map((wf) => ({
+    slug: wf.slug,
+    path: wf.path,
+    format: wf.format,
+    syncDirection: wf.syncDirection,
+    sourceKind: wf.sourceKind,
+    sourceRef: wf.sourceRef,
+  }));
+}
+
+function buildRenderedMounts(
+  mounts: Readonly<Record<string, { enabled: boolean; mode?: 'read-only' | 'read-write' }>>,
+  manifestSlug: string,
+  manifestVersion: string,
+): ReadonlyArray<{ mount: string; mode: 'read-only' | 'read-write' }> {
+  const out: { mount: string; mode: 'read-only' | 'read-write' }[] = [];
+  for (const [slotKey, decl] of Object.entries(mounts)) {
+    if (!decl.enabled) continue;
+    const slotDef = AWP_V1_SPEC.slots.find((s) => s.key === slotKey);
+    if (!slotDef) {
+      throw new UnknownSlotError(
+        slotKey,
+        'rendered.mounts',
+        manifestSlug,
+        manifestVersion,
+      );
+    }
+    const mode = decl.mode ?? slotDef.defaultMode;
+    out.push({ mount: slotDef.path, mode });
+  }
+  return out;
+}