@xemahq/agent-session-runtime 0.1.1

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

@@ -0,0 +1,432 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Composition → CompiledWorkspaceManifest reconstruction ──
+//
+// Phase 10 (`workspace-manifests-api` retirement). 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 Composition 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,
+} from '@xemahq/kernel-contracts/workflow';
+import {
+  compileManifest,
+  type CompiledWorkspaceManifest,
+  type ManifestInputDeclaration,
+  type ManifestMountsBlock,
+  type ManifestOutputSurface,
+  type ManifestSeedFile,
+  type ManifestSubAgent,
+  type WorkspaceManifest 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 CompositionMountLayoutError extends Error {
+  constructor(compositionRef: string, detail: string) {
+    super(
+      `Cannot derive a workspace mount layout from Agent Composition ` +
+        `"${compositionRef}": ${detail}`,
+    );
+    this.name = 'CompositionMountLayoutError';
+  }
+}
+
+/**
+ * The agent run-config the seeder projects from the source manifest's
+ * `spec.agent` block. Mirrors `CompositionAgentRunConfigDto` without
+ * importing the generated client.
+ */
+export interface CompositionAgentRunConfigInput {
+  /** Phase key. */
+  readonly phase: 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 CompositionMountLayoutInput {
+  /** Raw `spec.mounts` block — manifest DSL mount-declaration map. */
+  readonly mounts: Readonly<Record<string, unknown>>;
+  /** Projected `spec.agent` run-config. */
+  readonly agentRunConfig: CompositionAgentRunConfigInput;
+  /** 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.
+ */
+export interface CompositionSubAgentBindingInput {
+  readonly slug: string;
+  readonly alias?: string;
+}
+
+/**
+ * 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 CompositionOutputSurfaceInput {
+  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 CompositionManifestSource {
+  /** Version-pinned `slug@version` of the resolved composition. */
+  readonly compositionRef: string;
+  /** Root node's agent slug — the manifest's primary agent. */
+  readonly primaryAgentSlug: string;
+  /** Manifest-declared sub-agent bindings (descendant nodes). */
+  readonly subAgentBindings: readonly CompositionSubAgentBindingInput[];
+  /**
+   * 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: CompositionMountLayoutInput | 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?: CompositionOutputSurfaceInput;
+}
+
+/**
+ * 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 CompositionManifestImplicitInputs {
+  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 buildCompositionManifestBindInputs}.
+ * The compile fails fast on an unresolved required input or an enum
+ * violation — exactly the legacy behaviour.
+ */
+export function compileCompositionWorkspaceManifest(
+  source: CompositionManifestSource,
+  bindInputs: Readonly<Record<string, unknown>>,
+): CompiledWorkspaceManifest {
+  const mountLayout = source.mountLayout;
+  if (!mountLayout) {
+    throw new CompositionMountLayoutError(
+      source.compositionRef,
+      '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] = splitCompositionRef(source.compositionRef);
+
+  // 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 } : {}),
+    }),
+  );
+
+  // 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 spec: WorkspaceManifestSpec = {
+    mounts: mountLayout.mounts as unknown as ManifestMountsBlock,
+    agent: {
+      slug: source.primaryAgentSlug,
+      phase: mountLayout.agentRunConfig.phase,
+      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 }),
+  };
+
+  const envelope: DslWorkspaceManifest = {
+    apiVersion: 'xema.dev/workspace/v1',
+    kind: 'WorkspaceManifest',
+    metadata: {
+      slug,
+      version,
+      // Compositions resolved for a session bootstrap are, by definition,
+      // agent-session compatible — the runtime EnvironmentResolver still
+      // re-asserts `surfaceCompat` against the AGENT_SESSION surface.
+      surfaceCompat: [ManifestSurface.AGENT_SESSION],
+    },
+    spec,
+  };
+
+  const result = compileManifest(envelope, bindInputs);
+  if (!result.ok) {
+    throw new CompositionMountLayoutError(
+      source.compositionRef,
+      `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 `CompositionManifestSource`) 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: CompositionOutputSurfaceInput | 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 }),
+  };
+}
+
+/**
+ * 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 buildCompositionManifestBindInputs(
+  source: CompositionManifestSource,
+  explicitInputs: Record<string, unknown> | null,
+  implicitInputs: CompositionManifestImplicitInputs,
+): 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 CompositionMountLayoutError(
+      source.compositionRef,
+      '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 CompositionMountLayoutError(
+        source.compositionRef,
+        `manifest inputs contain undeclared key "${key}"`,
+      );
+    }
+    assertManifestInputValue(source.compositionRef, 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;
+}
+
+/** Split a `slug@version` composition ref; fail fast on a bare slug. */
+function splitCompositionRef(ref: string): [slug: string, version: string] {
+  const at = ref.lastIndexOf('@');
+  if (at <= 0 || at === ref.length - 1) {
+    throw new CompositionMountLayoutError(
+      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(
+  compositionRef: string,
+  key: string,
+  value: unknown,
+): void {
+  if (
+    value !== null &&
+    typeof value !== 'string' &&
+    typeof value !== 'number' &&
+    typeof value !== 'boolean' &&
+    !Array.isArray(value)
+  ) {
+    throw new CompositionMountLayoutError(
+      compositionRef,
+      `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 CompositionMountLayoutError(
+      compositionRef,
+      `manifest input "${key}" is an array — every element must be a string`,
+    );
+  }
+}

package/src/lib/dispatch-contract.ts

@@ -0,0 +1,156 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent-session dispatch wire contract ──
+//
+// Typed shapes the workflow-runtime-worker activity passes to (and
+// receives from) `agent-session-api`'s
+// `POST /internal/sessions/:id/dispatch` endpoint.
+//
+// These live in the Kernel package so the worker can depend on them
+// without pulling in the (large) Orval client at type-check time. The
+// generated Orval models in `@xemahq/agent-session-api-client` MUST be
+// structurally compatible — CI enforces it via a type-equality check
+// in `biomes/agent-runtime/api/agent-session-api/test/contract-compat.test.ts`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ArtifactRef } from '@xemahq/kernel-contracts/workflow';
+
+/**
+ * Mode discriminator on the dispatch envelope. Drives whether the
+ * service creates a fresh Session row or resumes an existing one.
+ */
+export const AgentSessionDispatchMode = {
+  /** Iter 1: mint a new Session, provision a worker, run one turn, pause. */
+  create_and_run: 'create_and_run',
+  /** Iter N+1: resume an existing Session, mount revision inputs, run one turn, pause. */
+  resume_and_run: 'resume_and_run',
+} as const;
+
+export type AgentSessionDispatchModeValue =
+  (typeof AgentSessionDispatchMode)[keyof typeof AgentSessionDispatchMode];
+
+/**
+ * A single revision input file to seed into `/workspace/inputs/...`
+ * BEFORE the agent's turn starts. The dispatch service writes the file
+ * via workspace-proxy's mount-apply call (one round-trip), so the
+ * agent's first read of the workspace sees it.
+ *
+ * The path is RELATIVE to `/workspace/inputs/` and validated against
+ * path-traversal (`..`, absolute paths, symlinks). Slot membership is
+ * enforced — only paths inside the manifest's declared `inputs` slot
+ * can be written.
+ */
+export interface RevisionInput {
+  /**
+   * Path under `/workspace/inputs/`, e.g. `revisions/revision-2-<iso>.md`.
+   * Validated: no leading slash, no `..`, must match the declared
+   * inputs-slot subpath whitelist.
+   */
+  readonly path: string;
+  /** Base64-encoded file bytes. UTF-8 markdown is the common case. */
+  readonly contentBase64: string;
+}
+
+/**
+ * Per-iteration prompt-side context the worker hands to the agent.
+ * Kept small on purpose: the bulk of the iteration's reviewer-feedback
+ * lives in the revision file, not here. The agent reads the file path
+ * out of `revisionFilePath` and `read`s it from the workspace.
+ */
+export interface DispatchPromptContext {
+  /** Free-form task statement (same shape as `agentContext.prompt` today). */
+  readonly prompt: string;
+  /**
+   * Path inside the workspace where the agent will find the actionable
+   * revision directive for this iteration. Omitted on iter 1.
+   * Example: `inputs/revisions/revision-2-2026-05-19T12-30-00Z.md`.
+   */
+  readonly revisionFilePath?: string;
+  /**
+   * Iteration number for telemetry / heartbeat. `1` for create-and-run,
+   * `>=2` for resume-and-run.
+   */
+  readonly iteration: number;
+}
+
+/**
+ * `mode: create_and_run` payload. The service creates a Session, calls
+ * pool acquire, then drives one turn.
+ */
+export interface CreateAndRunDispatch {
+  readonly mode: typeof AgentSessionDispatchMode.create_and_run;
+  /** ownerKind is forced to `pipeline_run` on this code path. */
+  readonly pipelineRunId: string;
+  readonly jobRunId: string;
+  /** Stable spine identity within the workflow run. */
+  readonly jobKey: string;
+  /**
+   * Agent Composition ref (`slug` = latest published, or `slug@version`)
+   * the new pipeline-owned session should bootstrap from. The dispatch
+   * service stamps this onto `Session.compositionRef`; the session
+   * lifecycle resolves it via llm-registry-api's `GET /compositions/
+   * resolve/:ref` for both the agent/skill/tool tree and the workspace
+   * mount layout.
+   */
+  readonly compositionRef: string;
+  readonly agentSlug: string;
+  readonly promptContext: DispatchPromptContext;
+}
+
+/**
+ * `mode: resume_and_run` payload. The service resumes the named
+ * Session (must be `paused`), writes the revision inputs into the
+ * workspace as part of mount-apply, then drives one turn.
+ */
+export interface ResumeAndRunDispatch {
+  readonly mode: typeof AgentSessionDispatchMode.resume_and_run;
+  readonly sessionId: string;
+  readonly revisionInputs: readonly RevisionInput[];
+  readonly promptContext: DispatchPromptContext;
+}
+
+export type AgentSessionDispatchRequest =
+  | CreateAndRunDispatch
+  | ResumeAndRunDispatch;
+
+/**
+ * Response from the dispatch endpoint. Carries the harvested outputs
+ * from the turn AND the session's new (post-pause) snapshot generation
+ * so the caller can correlate the iteration with its MinIO blob.
+ *
+ * The `sessionId` is echoed back so a `create_and_run` caller can
+ * record it on Temporal state for the next iteration.
+ */
+export interface AgentSessionDispatchResponse {
+  readonly sessionId: string;
+  readonly snapshotGeneration: number;
+  readonly pausedAt: string;
+  /** Harvested deliverables (artifact refs emitted by the agent's turn). */
+  readonly deliverables: readonly ArtifactRef[];
+  /**
+   * Free-form structured output (e.g. inquiry answers). Same shape as
+   * today's `RawAgentActivityOutput.structuredOutput`.
+   */
+  readonly structuredOutput: unknown;
+  /**
+   * Markdown response artifact ref (if the manifest declared one).
+   * Same shape as today's `RawAgentActivityOutput.response`.
+   */
+  readonly response: ArtifactRef | null;
+}
+
+/**
+ * Body for `POST /internal/sessions/:id/inputs/append`. Used by
+ * out-of-band callers (e.g. interactive-session UI file uploads) when
+ * the fast path through mount-apply isn't applicable. Internal-only;
+ * never exposed through the public Gateway.
+ */
+export interface InputsAppendRequest {
+  readonly path: string;
+  readonly contentBase64: string;
+}
+
+export interface InputsAppendResponse {
+  readonly written: boolean;
+  /** SHA-256 of the bytes as written. Useful for idempotency checks. */
+  readonly sha256: string;
+}