@xemahq/kernel-contracts 0.1.0

package/src/agent-composition/lib/composition.ts

@@ -0,0 +1,205 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent Composition ──
+//
+// The recursive "workflow-as-agent" primitive: an Agent armed with Skills
+// and Tools, whose sub-agents are themselves fully-armed composition nodes
+// (nestable, by-reference). A composition is usable BOTH as an
+// interactive-session agent AND as a Temporal workflow step.
+//
+// By-reference: a node names an agent as `slug@version`; the same agent
+// definition can be the root of one composition and a leaf of another.
+//
+// Phase 6 collapses `AgentSessionProfile`, `Session.subAgentBindings`, and
+// the agent section of `WorkspaceManifest` into this primitive.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ToolSelectionEntry } from '../../mcp-tool';
+import type { ModelRef } from '../../workflow';
+import type { SkillRef } from '../../skill';
+import type { CapabilityLayer } from './capability-layer';
+import type { CompositionWorkspace } from './composition-workspace';
+
+/**
+ * A stable reference to an agent definition, optionally version-pinned.
+ */
+export interface AgentRef {
+  readonly slug: string;
+  /** Pinned version; omitted = latest. */
+  readonly version?: string;
+}
+
+/**
+ * Ownership scope of a composition — who may manage it and how broadly it
+ * is reusable. Mirrors `SkillSpace`; compositions are org-scoped so they
+ * are authored once and reused across projects.
+ */
+export enum CompositionSpace {
+  System = 'system',
+  Biome = 'biome',
+  Org = 'org',
+  Project = 'project',
+  User = 'user',
+}
+
+/**
+ * Lifecycle state of a composition version. Closed set.
+ * - `draft`: editable; never resolved by runtime consumers.
+ * - `published`: immutable; the only state resolution will serve.
+ * - `archived`: retired; kept for lineage but never resolved.
+ */
+export enum CompositionLifecycle {
+  Draft = 'draft',
+  Published = 'published',
+  Archived = 'archived',
+}
+
+/**
+ * Hard runtime envelope a coordinator-style composition node enforces on
+ * itself and every descendant it spawns at runtime. Counters are
+ * decremented as the activity observes `task()` invocations and an
+ * activity-level enforcer aborts the run when ANY limit breaches.
+ *
+ * Inherited by descendants when absent on a child — the root coordinator
+ * declares the budget once and the whole subtree shares it.
+ *
+ * **Breach semantics — IMPORTANT:** any breach aborts the SSE stream and
+ * throws a non-retryable `ApplicationFailure(COMPOSITION_BUDGET_EXCEEDED)`.
+ * The activity ends without emitting a deliverable; the harvester never
+ * runs. All in-flight work is lost — HITL re-dispatches from the prior
+ * gate. This is the right semantics for *structural* runaways (depth /
+ * fanout / spawns are misbehaviour signals), but harsh for `tokenBudget`
+ * which can trip on a phase that is 90% done and slightly over budget.
+ *
+ * Until we design a graceful-drain / partial-emit path, `tokenBudget` is
+ * OPTIONAL — leave it `undefined` and the enforcer treats it as
+ * unlimited. `maxDepth` / `maxFanout` / `maxSpawns` are the load-bearing
+ * structural caps.
+ */
+export interface CompositionLimits {
+  /** Recursion depth ceiling — root = depth 0, first sub-agent = 1, etc. */
+  readonly maxDepth: number;
+  /** Concurrent `task()` spawns allowed per node within a single turn. */
+  readonly maxFanout: number;
+  /** Total `task()` spawns allowed across the whole subtree for this phase. */
+  readonly maxSpawns: number;
+  /**
+   * Total prompt+completion tokens allowed across the whole subtree.
+   * OPTIONAL. When `undefined`, the enforcer skips token-budget checks
+   * entirely (unlimited). Set this only after measuring real phase
+   * usage — premature caps cause expensive "phase 90% done, lost on
+   * breach" failures. See the breach-semantics note above.
+   */
+  readonly tokenBudget?: number | undefined;
+}
+
+/**
+ * A node in the composition tree. The root node is the primary agent;
+ * `children` are its sub-agents, each itself a fully-armed node (recursive).
+ *
+ * `skills` / `tools` / `modelOverride` attach AT this node — they extend or
+ * override what the referenced agent definition declares intrinsically.
+ */
+export interface CompositionNode {
+  /** The agent definition this node runs. */
+  readonly agent: AgentRef;
+  /** Optional alias when the same agent appears more than once in the tree. */
+  readonly alias?: string;
+  /** Skills attached at this node. */
+  readonly skills: readonly SkillRef[];
+  /** Tools attached at this node. */
+  readonly tools: readonly ToolSelectionEntry[];
+  /**
+   * Optional concrete model override for this node. When omitted the
+   * Model Resolution Matrix decides at the invocation boundary.
+   */
+  readonly modelOverride?: ModelRef;
+  /** Sub-agents — themselves fully-armed composition nodes (recursive). */
+  readonly children: readonly CompositionNode[];
+  /**
+   * Hard budget the runtime enforces against `task()` spawn telemetry
+   * for THIS node and every descendant it produces at runtime. Inherited
+   * by descendants when omitted, so a coordinator typically declares
+   * limits once at the root. Absent root + absent descendants = no
+   * enforcement (today's pre-coordinator workflows).
+   */
+  readonly limits?: CompositionLimits;
+}
+
+/**
+ * A named, versioned, reusable Agent Composition.
+ */
+export interface Composition {
+  /** Stable slug; the identity within the registry. */
+  readonly slug: string;
+  readonly version: string;
+  readonly displayName: string;
+  readonly description?: string;
+  readonly scope: CompositionSpace;
+  readonly lifecycle: CompositionLifecycle;
+  /** The root (primary) agent node. */
+  readonly root: CompositionNode;
+  /** Capability envelope applied to the composition at runtime. */
+  readonly capability?: CapabilityLayer;
+  /**
+   * Authored workspace-layout config — persist-paths, env vars, preview
+   * surface. The authoritative SOURCE projected onto `WorkspaceSpec`
+   * (`@xemahq/agent-workspace-contracts`). Optional + additive: a
+   * composition with no `workspace` block runs on the AWP base slots
+   * alone. Absorbs the layout/persistence/env portion of the retiring
+   * `WorkspaceManifest`.
+   */
+  readonly workspace?: CompositionWorkspace;
+}
+
+/**
+ * The flattened, runtime-facing form of one resolved composition node.
+ * The resolution service produces this tree from a stored `Composition`;
+ * the workspace/composer pipeline consumes it. Sub-agent nodes appear
+ * as `children` (still recursive) — each child is itself fully armed.
+ *
+ * Distinct from `CompositionNode` (the AUTHORED form): a resolved node
+ * has its agent reference fully version-pinned, never `latest`.
+ */
+export interface ResolvedCompositionNode {
+  /** Fully version-pinned agent reference. */
+  readonly agent: Required<AgentRef>;
+  readonly alias?: string;
+  /** Skill references attached at this node (version-pinned). */
+  readonly skills: readonly SkillRef[];
+  /** Tool references attached at this node. */
+  readonly tools: readonly ToolSelectionEntry[];
+  /** Concrete model override, when the node pinned one. */
+  readonly modelOverride?: ModelRef;
+  /** Resolved sub-agent nodes (recursive). */
+  readonly children: readonly ResolvedCompositionNode[];
+  /**
+   * Resolved budget for this node. The resolver propagates the nearest
+   * declared `limits` from the source `CompositionNode` (root usually
+   * carries it; descendants inherit). Absent = no enforcement on this
+   * node and its descendants — preserves today's pre-coordinator
+   * workflow behaviour where no budget was declared.
+   */
+  readonly limits?: CompositionLimits;
+}
+
+/**
+ * The resolution service's output: a composition resolved against a task
+ * context, ready for the composer/workspace pipeline to consume.
+ */
+export interface ResolvedComposition {
+  readonly slug: string;
+  readonly version: string;
+  readonly displayName: string;
+  readonly scope: CompositionSpace;
+  /** Resolved root node — the primary agent. */
+  readonly root: ResolvedCompositionNode;
+  /** Capability envelope applied to the whole composition at runtime. */
+  readonly capability: CapabilityLayer;
+  /**
+   * Resolved workspace-layout config — present when the source
+   * composition declared a `workspace` block. The `${input.x}`
+   * interpolation in `env` values is already resolved here. The
+   * workspace pipeline projects this onto the run's `WorkspaceSpec`.
+   */
+  readonly workspace?: CompositionWorkspace;
+}

package/src/agent-composition/lib/intrinsic-floor.ts

@@ -0,0 +1,50 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Intrinsic floor of baseline tools ──
+//
+// Every agent — regardless of manifest, composition, or per-session
+// declaration — receives this fixed set of read / edit / exec tools.
+// The floor is NEVER REMOVABLE: an agent manifest that declares an empty
+// tool selection (or no permission block at all) still gets the floor.
+//
+// The floor is the runtime intersection of:
+//   • OpenCode's native built-in tools — `bash`, `read`, `write`, `edit`,
+//     `grep`, `glob`, `ls`, `task`, `todo_write`. Materialised by the
+//     `EnvironmentResolver` into `ResolvedEnvironment.intrinsicFloorTools`
+//     so downstream consumers (worker activity, session-bundle apply)
+//     project them onto the agent's runtime permission surface.
+//   • The Memory v2 MCP tool — `memory`. The catalog stanza for this
+//     server is unconditionally injected by the session tool resolver so
+//     the tool is callable, not merely named.
+//
+// A linter (`tooling/boundaries/check-intrinsic-floor.mjs`) refuses any
+// biome agent manifest that declares one of these tools explicitly in
+// its `permission.<tool>: allow` frontmatter — the floor makes the
+// declaration redundant. Restrictive declarations (`deny` / `ask`) are
+// out of scope for the floor; the floor declares AVAILABILITY only and
+// does not override authored deny rules.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export enum IntrinsicFloorTool {
+  BASH = 'bash',
+  READ = 'read',
+  WRITE = 'write',
+  EDIT = 'edit',
+  GREP = 'grep',
+  GLOB = 'glob',
+  LS = 'ls',
+  TASK = 'task',
+  TODO_WRITE = 'todo_write',
+  MEMORY = 'memory',
+}
+
+export const INTRINSIC_FLOOR_TOOLS: readonly IntrinsicFloorTool[] =
+  Object.values(IntrinsicFloorTool);
+
+/**
+ * `true` when the supplied tool name is part of the intrinsic floor.
+ * Useful for linters and resolvers that need a closed-set check without
+ * pulling in the enum values manually.
+ */
+export function isIntrinsicFloorTool(name: string): name is IntrinsicFloorTool {
+  return (INTRINSIC_FLOOR_TOOLS as readonly string[]).includes(name);
+}

package/src/agent-composition/lib/model-resolution-matrix.ts

@@ -0,0 +1,112 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Model Resolution Matrix ──
+//
+// Replaces the hardcoded `PHASE_MODEL_CLASS_MAP`. A dynamic, dimensional
+// rule set answering "which provider/model should THIS invocation use?".
+//
+//   • One DEFAULT rule (empty selector) → the org default model. Always exists.
+//   • Each other rule = { selector: {agent?, skill?, project?, …}, target }.
+//   • Resolution: among rules whose every selector dimension matches the
+//     invocation context, the rule matching the MOST dimensions wins; ties
+//     broken by `priority`. No match → default.
+//   • A run/realtime override sits above all rules.
+//
+// A model cannot change mid-LLM-turn, so the matrix resolves at invocation
+// boundaries — agent start, sub-agent spawn, and `/skill` launch.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ModelRef } from '../../workflow';
+
+/**
+ * Open registry of matrix dimensions. v1 ships agent/skill/project/group;
+ * v1.1 adds `purpose` for non-agent invocations (memory summarization,
+ * embedding, reorganization). New dimensions are added here + carried in
+ * `ModelMatrixSelector.extra` (untyped) or as a typed first-class field.
+ *
+ * The `group` dimension is the kernel-neutral name for a sub-app's
+ * structural grouping tag on a job (e.g. the software-dev biome maps
+ * its `phaseKey:` YAML field onto this dimension at compile time).
+ */
+export enum ResolutionDimension {
+  Agent = 'agent',
+  Skill = 'skill',
+  Project = 'project',
+  Group = 'group',
+  Purpose = 'purpose',
+}
+
+/**
+ * A selector matches an invocation context on zero or more dimensions.
+ * An empty selector is the DEFAULT rule.
+ */
+export interface ModelMatrixSelector {
+  /** Match when the resolving agent's slug equals this value. */
+  readonly agent?: string;
+  /** Match when the active/launched skill's slug equals this value. */
+  readonly skill?: string;
+  /** Match when the invocation's project id equals this value. */
+  readonly project?: string;
+  /**
+   * Match when the invocation's structural group key equals this value.
+   * Kernel-neutral name; the software-dev biome's `phaseKey:` YAML field
+   * is mapped onto this dimension by the DSL compiler.
+   */
+  readonly group?: string;
+  /**
+   * Match when the invocation's non-agent purpose equals this value. Used
+   * for system flows that route LLM calls outside the agent/skill model —
+   * e.g. memory summarization, memory embedding, memory reorganization.
+   * Closed value set is owned by each consuming service (e.g.
+   * `MemoryMatrixPurpose` in memory-api).
+   */
+  readonly purpose?: string;
+  /** Forward-compat: additional dimensions resolved from the registry. */
+  readonly extra?: Readonly<Record<string, string>>;
+}
+
+/**
+ * One rule in the matrix. `target` is a `ModelRef` — concrete (provider +
+ * model) or a strategy (model strategies remain a valid target).
+ */
+export interface ModelResolutionRule {
+  readonly id: string;
+  /** Empty selector = the default rule. */
+  readonly selector: ModelMatrixSelector;
+  readonly target: ModelRef;
+  /** Tie-break hint when two rules match the same number of dimensions. */
+  readonly priority?: number;
+}
+
+/**
+ * The invocation context the matrix is resolved against.
+ */
+export interface ModelResolutionContext {
+  readonly agentSlug: string;
+  readonly projectId?: string;
+  readonly skillSlug?: string;
+  readonly groupKey?: string;
+  /**
+   * Non-agent invocation purpose (e.g. memory summarization/embedding).
+   * Optional — agent and skill invocations leave this undefined.
+   */
+  readonly purpose?: string;
+  /** Values for any extra registered dimensions. */
+  readonly extra?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Traced outcome of resolving the matrix for one invocation. Surfaced in
+ * the Studio debugger so a user can see WHICH rule won and WHY.
+ */
+export interface ResolvedModelDecision {
+  /** The resolved model reference. */
+  readonly model: ModelRef;
+  /** Id of the rule that won; `null` when the default fallback was used. */
+  readonly matchedRuleId: string | null;
+  /** Dimensions the winning rule matched on. */
+  readonly matchedDimensions: readonly ResolutionDimension[];
+  /** `true` when a run/realtime override pre-empted the matrix. */
+  readonly overridden: boolean;
+  /** Human-readable win reason for the Studio debugger. */
+  readonly reason: string;
+}

package/src/agent-workspace/index.ts

@@ -0,0 +1,27 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace Contracts — Barrel Export ──
+//
+// Typed mirror of the "unified xema workspace" that every agent session
+// runs inside. Shared between:
+//   • workflow-runtime-worker (activities) — writes AGENTS.md +
+//     context.json, harvests manifest.
+//   • llm-registry-api (PR B agent-run-context renderer) — composes
+//     AGENTS.md + context.json + mount plan.
+//   • deliverable-specs-api (PR A) — validates against spec contracts.
+//   • workspace-proxy — enforces mount-plan mode + layout.
+//
+// No runtime deps — pure types + one enum-backed helper
+// (`parseDeliverableSpecRef`). Safe to import from workflow bundles.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/workspace-layout';
+export * from './lib/workspace-spec';
+export * from './lib/awp-v1';
+export * from './lib/context-json';
+export * from './lib/manifest';
+export * from './lib/deliverable-spec-ref';
+export * from './lib/endpoint-fetch-spec';
+export * from './lib/agent-run-context';
+export * from './lib/mount-apply';
+export * from './lib/agent-tool-defaults';
+export * from './lib/working-file';

package/src/agent-workspace/lib/agent-run-context.ts

@@ -0,0 +1,44 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Rendered agent-run context ──
+//
+// Output shape of `POST /agent-run-context/render` (llm-registry-api,
+// PR B). The activity (worker-side) calls this endpoint before driving
+// the OpenCode session; the renderer composes it by combining the
+// agent definition, project override, phase config, and the resolved
+// deliverable spec (fetched from deliverable-specs-api).
+//
+// The activity is deterministic w.r.t. this struct: same
+// `resolvedAgentSnapshotHash` + same `mountPlan.entries` hashes must
+// produce identical session results on replay. This is what lets
+// Temporal retries resume mid-session without re-running the work.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ContextJson } from './context-json';
+import type { WorkspaceMountPlan } from './workspace-layout';
+
+export interface RenderedAgentRunContext {
+  /**
+   * Full markdown body of `/workspace/AGENTS.md` — prepend role
+   * orientation + completion protocol + spec-specific deliverable
+   * instructions. Written verbatim to the workspace by the activity.
+   */
+  readonly agentsMd: string;
+  /** The parsed context.json payload; serialized to JSON at write time. */
+  readonly contextJson: ContextJson;
+  readonly mountPlan: WorkspaceMountPlan;
+  /** MCP tool ids enabled for this session after phase-config + overlay application. */
+  readonly toolAllowlist: readonly string[];
+  /** Applied overlay refs (stack + concern) — surfaced for audit + UI display. */
+  readonly appliedOverlays: readonly string[];
+  /**
+   * Stable sha256 of the composed AgentInvocationSnapshot inputs. Used
+   * for retry determinism + audit trail.
+   */
+  readonly resolvedAgentSnapshotHash: string;
+  /**
+   * Sha256 of the rendered context (agentsMd + contextJson canonicalized
+   * + mountPlan). Different from `resolvedAgentSnapshotHash` because
+   * inputs may change between invocations (e.g. new references/).
+   */
+  readonly renderedContextHash: string;
+}