@xemahq/dsl 0.8.0 → 0.8.2

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

@@ -1,446 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// ── AgentWorkspaceSpec types ──
-//
-// A AgentWorkspaceSpec 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 `agentRef:` on the `xema/agent`
-// action — the named Agent 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
-// Agent. Customers author them with the same ergonomics as
-// workflow YAMLs.
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Top-level manifest envelope. `apiVersion: xema.dev/workspace/v1`,
- * `kind: AgentWorkspaceSpec`. 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 AgentWorkspaceSpec {
-  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: CredentialBackendKind;
-  /** 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;
-  /**
-   * Fully-qualified long-lived branch the per-session branch auto-merges
-   * into on pause (per-session-branch + auto-merge model). Mirrors
-   * `SlotPersistencePolicy.git-push.mergeTarget` in
-   * `@xemahq/kernel-contracts/agent-workspace`.
-   */
-  readonly mergeTarget?: string;
-}
-
-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;
-  /** Stage key (e.g. `engineering`, `interactive`). */
-  readonly stage: 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 node-level instructions. A prompt
-   * fragment layered ONTO the referenced base agent's intrinsic system
-   * prompt — the same lever as `AgentNode.instructions`, exposed here
-   * so a AgentWorkspaceSpec can author a migrated agent as
-   * `base agent slug + instructions` without minting a new agent definition.
-   * May reference `${input.x}`. Bounded by `MAX_AGENT_INSTRUCTIONS_LENGTH`
-   * and validated fail-fast by `ManifestAgentBlockSchema`.
-   */
-  readonly instructions?: string;
-  /**
-   * How `instructions` combine with the referenced base agent's
-   * `systemPrompt`. Absent ⇒ {@link PromptMergeMode.Append}. `Replace` makes
-   * `instructions` the system prompt while still inheriting the base agent's
-   * CONFIG. Validated by `ManifestAgentBlockSchema`.
-   */
-  readonly promptMode?: PromptMergeMode;
-  /**
-   * Optional per-agent permission override. A partial
-   * OpenCode-style `PermissionMap` deep-merged (per top-level key) over the
-   * referenced base agent's authored permission before the system tiers run.
-   * Lets a generic base agent be specialized into a bounded role (read-only
-   * reviewer, scoped `task` allowlist) without minting a new agent
-   * definition. Validated by `ManifestAgentBlockSchema`.
-   */
-  readonly permission?: PermissionMap;
-  /**
-   * 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;
-  /**
-   * Optional node-level instructions for this delegate. Same
-   * `base agent slug + instructions` lever as the primary agent block;
-   * layered onto the referenced agent's intrinsic system prompt. May
-   * reference `${input.x}`. Bounded by `MAX_AGENT_INSTRUCTIONS_LENGTH`.
-   */
-  readonly instructions?: string;
-  /**
-   * How `instructions` combine with the referenced base agent's
-   * `systemPrompt`. Absent ⇒ {@link PromptMergeMode.Append}.
-   */
-  readonly promptMode?: PromptMergeMode;
-  /**
-   * Optional per-delegate permission override. Deep-merged (per top-level
-   * key) over the referenced base agent's authored permission before the
-   * system tiers run — the lever that turns a generic base agent into a
-   * bounded delegate. Validated by `ManifestSubAgentSchema`.
-   */
-  readonly permission?: PermissionMap;
-}
-
-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,
-  CredentialBackendKind,
-  ManifestSurface,
-  ModelClass,
-  OutputSurfaceKind,
-  PromptMergeMode,
-  ToolsetKey,
-} from '@xemahq/kernel-contracts/workflow';
-import type { ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
-import type { PermissionMap } from '@xemahq/kernel-contracts/agent-workspace';
-
-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[] };