@xemahq/dsl 0.1.1

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

@@ -0,0 +1,392 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── WorkspaceManifest types ──
+//
+// A WorkspaceManifest declares the SHAPE of `/workspace/` for an agent
+// invocation: which user-data mounts (inputs, references, repos, …) the
+// agent expects, which platform-rendered slots the composer should
+// auto-emit (agents-md, context-json, agent-bundles, …), and which
+// per-profile seed files to drop in.
+//
+// Workflows reference manifests by `compositionRef:` on the `xema/agent`
+// action — the named Agent Composition carries the manifest on its
+// `workspace.mountLayout` block; interactive sessions reference them via
+// the session's composition. The composer in `@xemahq/agent-session-runtime`
+// turns a (manifest, bindInputs) pair into a `WorkspaceMountPlan` and
+// posts it to `/workspace/mounts/apply`.
+//
+// Manifests are shipped by biomes as `*.workspace.yaml` content;
+// on install each is compiled and projected into a published Agent
+// Composition. Customers author them with the same ergonomics as
+// workflow YAMLs.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Top-level manifest envelope. `apiVersion: xema.dev/workspace/v1`,
+ * `kind: WorkspaceManifest`. Versioning is at the spec level —
+ * manifests are stored by `(slug, version)` so old workflow runs always
+ * resolve to the manifest they were authored against.
+ *
+ * `extends:` (optional) names a base manifest to inherit from.
+ * Resolution is single-level: the base manifest itself MUST NOT carry
+ * its own `extends:`. The resolver merges the base's spec into the
+ * child's spec deterministically (see {@link MANIFEST_MERGE_RULES}):
+ *   • `mounts` and `inputs` are unioned key-by-key; child's per-slot
+ *     declaration wins on conflict.
+ *   • `seedFiles` and `env` are concatenated (base first, child after);
+ *     duplicates by `path` / `name` keep the LAST occurrence (child wins).
+ *   • `agent` block is fully replaced by the child (it's the agent's
+ *     identity, not inheritable).
+ *
+ * The reference is a `xema://manifest/<slug>@<version>` URI. The
+ * resolver in {@link resolveManifestExtends} fetches the base via a
+ * caller-supplied lookup function — the kernel package stays runtime-
+ * dep-free.
+ */
+export interface WorkspaceManifest {
+  readonly apiVersion: 'xema.dev/workspace/v1';
+  readonly kind: 'WorkspaceManifest';
+  readonly extends?: string;
+  readonly metadata: WorkspaceManifestMetadata;
+  readonly spec: WorkspaceManifestSpec;
+}
+
+/**
+ * Slugs of the kernel-shipped manifest templates. Biomes/orgs may
+ * register their own templates with their own slugs; these four are
+ * always available at the system tier.
+ *
+ * `primary-agent-base`        — coordinator/lead/executor shape with
+ *                                inputs RO, references RO, attachments
+ *                                RO, deliverables RW.
+ * `subagent-base`             — same as primary-agent-base minus
+ *                                attachments.
+ * `reviewer-base`             — adds `prior-artifacts`, `review-brief`,
+ *                                `findings` slots for review flows.
+ * `agent-session-base`  — adds session-attachments slot for
+ *                                chat-driven runs.
+ */
+export const KERNEL_MANIFEST_TEMPLATE_SLUGS = [
+  'primary-agent-base',
+  'subagent-base',
+  'reviewer-base',
+  'agent-session-base',
+] as const;
+
+export type KernelManifestTemplateSlug = (typeof KERNEL_MANIFEST_TEMPLATE_SLUGS)[number];
+
+export interface WorkspaceManifestMetadata {
+  readonly slug: string;
+  readonly version: string;
+  /**
+   * `system` (xema-internal), or any string identifying the org. The
+   * `biome:<id>` source tier is stored separately on the row, not in
+   * the manifest YAML itself.
+   */
+  readonly org?: string;
+  readonly description?: string;
+  /**
+   * Execution surfaces this manifest is compatible with. Optional in
+   * YAML for additive rollout; the compiler defaults absent values to
+   * `[workflow, agent-session]` so existing manifests keep
+   * compiling. Validated against {@link ManifestSurface}. Pairs with
+   * the workflow action manifest's `consumes[].surfaces` and the
+   * agent-session runtime — a manifest with
+   * `surfaceCompat: [workflow]` cannot boot an interactive session,
+   * and the runtime fails fast at resolve time.
+   */
+  readonly surfaceCompat?: readonly ManifestSurface[];
+  /** Optional UX framing — drives Studio tiles, picker grouping. */
+  readonly display?: ManifestDisplayMetadata;
+}
+
+export interface ManifestDisplayMetadata {
+  readonly title?: string;
+  readonly blurb?: string;
+  /** Icon slug (frontend maps it to a glyph). */
+  readonly icon?: string;
+  /** Picker grouping. Free-form; kernel-shipped manifests prefer a closed set. */
+  readonly category?: string;
+  readonly badges?: readonly string[];
+  readonly sortOrder?: number;
+  readonly hidden?: boolean;
+  /** Call-to-action shown on the session-start tile. */
+  readonly ctaText?: string;
+  /** Marks a kernel-curated manifest (set by the kernel biome seeder). */
+  readonly curated?: boolean;
+}
+
+export interface WorkspaceManifestSpec {
+  /** Runtime parameters the manifest accepts at bind time. */
+  readonly inputs?: Record<string, ManifestInputDeclaration>;
+  /** User-data mounts (resolved from bind inputs). */
+  readonly mounts?: ManifestMountsBlock;
+  /** Agent runtime config — composer auto-derives the .opencode/* slots. */
+  readonly agent: ManifestAgentBlock;
+  /** Skill bundles auto-mounted at session/workflow boot. */
+  readonly skills?: readonly ManifestSkillRef[];
+  /**
+   * Default MCP tool selection inherited by every session/run booted on
+   * this manifest. Resolved at boot via mcp-gateway-api `POST /mcp-resolve`
+   * and merged into `opencode.json:mcp`. Sessions may override per-instance
+   * via `PATCH /sessions/:id/tools`.
+   */
+  readonly toolSelection?: readonly ToolSelectionEntry[];
+  /** Credential bindings resolved before agent dispatch. */
+  readonly credentials?: readonly ManifestCredential[];
+  /** Tool permissions overlay (allow/deny lists over agent's intrinsic floor). */
+  readonly permissions?: ManifestPermissions;
+  /** Workspace-relative paths captured on pause and restored on resume. */
+  readonly persistence?: ManifestPersistence;
+  /** Output-surface declaration (consumed by workspace-proxy). */
+  readonly outputSurface?: ManifestOutputSurface;
+  /** Profile-specific seed files (rendered via Handlebars or inlined). */
+  readonly seedFiles?: readonly ManifestSeedFile[];
+  /** Env vars applied via `PATCH /env/variables`. */
+  readonly env?: readonly ManifestEnvVar[];
+  /**
+   * Working files the platform materialises before the agent's first
+   * turn. Each entry binds a `<workspace-relative-path>.<ext>` to a
+   * source (`kb-page`, `git-file`, …) the platform keeps in sync for
+   * the lifetime of the session. The compiled output's `path` and
+   * `sourceRef` carry `${input.x}`-interpolated values; the worker's
+   * working-file engine dispatches by `sourceKind`.
+   */
+  readonly workingFiles?: readonly ManifestWorkingFile[];
+}
+
+/**
+ * Single working-file declaration in the manifest YAML. The schema's
+ * `path` regex requires a workspace-relative path (no leading `/`, no
+ * `..` segments); `slug` mirrors the file basename so the agent's
+ * mental model of `<slug>` and the on-disk file stay aligned. `format`
+ * + `syncDirection` are closed enums.
+ *
+ * `sourceRef` is a kind-specific string map (e.g. `{ pageId, versionId }`
+ * for `kb-page`). Values may carry `${input.x}` tokens — the compile
+ * step interpolates them against the bind inputs.
+ */
+export interface ManifestWorkingFile {
+  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>>;
+}
+
+export interface ManifestSkillRef {
+  readonly slug: string;
+  /** Optional semver range pin (`^1`, `~1.2.3`, etc.). */
+  readonly version?: string;
+}
+
+export interface ManifestCredential {
+  /** Stable name — UPPER_SNAKE_CASE; referenced from `env[].value`. */
+  readonly name: string;
+  readonly kind: CredentialKind;
+  /** Backend-specific reference. Interpreted by the credential fetcher. */
+  readonly sourceRef: string;
+  /** Required = resolve failure fails the bootstrap; optional = drift warning. */
+  readonly required?: boolean;
+}
+
+export interface ManifestPermissions {
+  readonly tools: {
+    readonly allow?: readonly ToolsetKey[];
+    readonly deny?: readonly ToolsetKey[];
+  };
+}
+
+/**
+ * Per-slot persistence policy override. Currently only `git-push` is
+ * overridable — `tarball`/`none` have no fields biomes need to tune.
+ * Mirrors `SlotPersistencePolicy.git-push` in
+ * `@xemahq/kernel-contracts/agent-workspace`, plus the contract-mirror enums
+ * (`ManifestGitPushBranchSuffix`, `ManifestGitPushConcurrencyMode`)
+ * imported below.
+ */
+export interface ManifestSlotPersistenceOverride {
+  readonly kind: 'git-push';
+  readonly branchPrefix: string;
+  readonly branchSuffix?: import('@xemahq/kernel-contracts/workflow').ManifestGitPushBranchSuffix;
+  readonly concurrencyMode?: import('@xemahq/kernel-contracts/workflow').ManifestGitPushConcurrencyMode;
+}
+
+export interface ManifestPersistence {
+  /** Workspace-relative paths. No leading `/`, no `..`. */
+  readonly paths: readonly string[];
+  /**
+   * Per-slot persistence policy overrides. Keyed by AWP slot key
+   * (`repos`, etc.). Compile-time-validated against the kernel spec —
+   * unknown slot keys and overrides of non-`git-push` slots fail
+   * compilation.
+   */
+  readonly overrides?: Readonly<Record<string, ManifestSlotPersistenceOverride>>;
+}
+
+export type ManifestOutputSurfaceMode = 'single' | 'multi';
+
+export interface ManifestOutputSurface {
+  readonly kind: OutputSurfaceKind;
+  readonly port?: number;
+  readonly healthPath?: string;
+  /** Auto-open the preview pane on first ready signal. */
+  readonly autoOpen?: boolean;
+  /**
+   * Single-port (default) vs. multi-app output surface. `multi` lets
+   * workspace-proxy's output-surface supervisor allocate a port per detected
+   * app target and emit one gateway route per app — used by webapp
+   * studios that scaffold N apps under one session.
+   */
+  readonly mode?: ManifestOutputSurfaceMode;
+  /**
+   * Workspace-relative directory served as a static site. Required by
+   * the schema when `kind === 'static'` and rejected for other kinds.
+   * The baked `static-artifact-server.mjs` serves this directory at the
+   * supervisor-assigned port.
+   */
+  readonly root?: string;
+  /**
+   * Default document name for directory requests in a `static` surface.
+   * Defaults to `index.html` at compile time. Schema rejects the field
+   * for non-`static` kinds.
+   */
+  readonly defaultDocument?: string;
+}
+
+export interface ManifestInputDeclaration {
+  readonly type: 'string' | 'string[]' | 'boolean' | 'number' | 'object[]';
+  readonly required?: boolean;
+  readonly default?:
+    | string
+    | number
+    | boolean
+    | readonly string[]
+    | readonly Readonly<Record<string, unknown>>[];
+  /** Closed-set values; if omitted any value of the right type is allowed. */
+  readonly enum?: readonly string[];
+  readonly description?: string;
+}
+
+/**
+ * User-data mount declarations. Each key matches a slot in
+ * `AWP_V1_SPEC` (inputs, references, repos, deliverable-specs,
+ * deliverables, attachments). Values can be `true`/`false` (use
+ * defaults), a mode override (`{ mode: 'read-write' }`), or per-slot
+ * config (e.g. `references: { kbSpaces: ${input.x} }`).
+ *
+ * Platform slots (agents-md, context-json, agent-bundles, etc.) are
+ * NEVER declared here — the composer auto-emits them based on
+ * `spec.agent`.
+ */
+export type ManifestMountsBlock = Record<string, ManifestMountDeclaration>;
+
+export type ManifestMountDeclaration =
+  | boolean
+  | { readonly mode?: 'read-only' | 'read-write' }
+  | { readonly kbSpaces: ReadonlyArray<string> | string }
+  | { readonly externalProjects: ReadonlyArray<string> | string }
+  | { readonly mode?: 'read-only' | 'read-write'; readonly [key: string]: unknown };
+
+export interface ManifestAgentBlock {
+  /** Agent slug to compose. May reference `${input.x}`. */
+  readonly slug: string;
+  /** Phase key (e.g. `engineering`, `interactive`). */
+  readonly phase: string;
+  /**
+   * Worker role — drives AGENTS.md rendering and the system-overlay
+   * `authority` block surfaced to the agent.
+   * Validated by `ManifestAgentBlockSchema` against
+   * `AGENT_RUN_ROLES` from `@xemahq/kernel-contracts/workflow`, so
+   * `compileManifest` returns a strongly-typed `AgentRunRole`.
+   */
+  readonly role: AgentRunRole;
+  /** Optional deliverable spec ref. May reference `${input.x}`. */
+  readonly deliverableSpecRef?: string;
+  /**
+   * Optional default model suggestion for the primary agent. Concrete or
+   * strategy ref (`@xemahq/workflow-contracts:ModelRef`). Step/session
+   * overrides take precedence; this is the manifest's recommended pick
+   * when no override is supplied. Validated as a discriminated union by
+   * `ManifestAgentBlockSchema`.
+   */
+  readonly defaultModel?: ManifestModelRef;
+  /**
+   * Optional sub-agent delegates the manifest bundles with the primary
+   * agent. Layered ON TOP of the primary's intrinsic delegates (declared
+   * in its source `permission.task` allowlist); step/session overrides
+   * add more on top. Bindings only ADD or refine model overrides — they
+   * never remove an intrinsic delegate.
+   */
+  readonly subAgents?: readonly ManifestSubAgent[];
+}
+
+export type ManifestModelRef =
+  | {
+      readonly kind: 'concrete';
+      readonly modelId: string;
+      readonly providerSlug?: string;
+      readonly temperature?: number;
+    }
+  | {
+      readonly kind: 'strategy';
+      readonly modelClass: ModelClass;
+      readonly temperature?: number;
+    };
+
+export interface ManifestSubAgent {
+  readonly slug: string;
+  readonly alias?: string;
+  readonly defaultModel?: ManifestModelRef;
+}
+
+export interface ManifestSeedFile {
+  /** Path relative to `/workspace/`. No leading `/`, no `..`. */
+  readonly path: string;
+  /** Mount slot to land in. Defaults to `inputs` if omitted. */
+  readonly slot?: string;
+  /** Named template — resolved at composition time from a skill-bundle
+   * resource (`assets/templates/<name>.hbs`) served by `skill-registry-api`. */
+  readonly template?: string;
+  /** Inline content — alternative to `template`. */
+  readonly content?: string;
+  /** Variables passed to the template renderer. May reference `${input.x}`. */
+  readonly vars?: Record<string, unknown>;
+}
+
+export interface ManifestEnvVar {
+  readonly name: string;
+  readonly value: string;
+}
+
+export type {
+  CompiledWorkspaceManifest,
+  CompiledMountDeclaration,
+  CompiledSeedFile,
+  CompiledSeedFileSource,
+} from '@xemahq/kernel-contracts/workflow';
+
+import type {
+  AgentRunRole,
+  CompiledWorkspaceManifest,
+  CredentialKind,
+  ManifestSurface,
+  ModelClass,
+  OutputSurfaceKind,
+  ToolsetKey,
+} from '@xemahq/kernel-contracts/workflow';
+import type { ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
+
+export interface ManifestIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+/**
+ * Result envelope for `compileManifest()`. Validation never throws —
+ * callers pattern-match on the discriminator. Lets the editor + preview
+ * flow surface every issue at once without try/catch ceremony.
+ */
+export type CompileResult =
+  | { readonly ok: true; readonly compiled: CompiledWorkspaceManifest }
+  | { readonly ok: false; readonly errors: readonly ManifestIssue[] };