@xemahq/agent-session-runtime 0.4.0 → 0.6.0

package/dist/lib/dispatch-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-contract.d.ts","sourceRoot":"","sources":["../../src/lib/dispatch-contract.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAMrE,eAAO,MAAM,wBAAwB;;;CAK3B,CAAC;AAEX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAa3E,MAAM,WAAW,aAAa;IAM5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAQD,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAKnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC,cAAc,CAAC;IAE9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IASxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;CAC/C;AAOD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC,cAAc,CAAC;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;CAC/C;AAED,MAAM,MAAM,2BAA2B,GACnC,oBAAoB,GACpB,oBAAoB,CAAC;AAUzB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAK9C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAKnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;CACvC;AAQD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}
+{"version":3,"file":"dispatch-contract.d.ts","sourceRoot":"","sources":["../../src/lib/dispatch-contract.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAMrE,eAAO,MAAM,wBAAwB;;;CAK3B,CAAC;AAEX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAa3E,MAAM,WAAW,aAAa;IAM5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAQD,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAMxB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAKnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC,cAAc,CAAC;IAE9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IASxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;CAC/C;AAOD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC,cAAc,CAAC;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;CAC/C;AAED,MAAM,MAAM,2BAA2B,GACnC,oBAAoB,GACpB,oBAAoB,CAAC;AAUzB,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAK9C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAKnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;CACvC;AAQD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/agent-session-runtime",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -37,8 +37,8 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "@xemahq/dsl": "^0.2.0",
-    "@xemahq/kernel-contracts": "^0.4.0"
+    "@xemahq/dsl": "^0.4.0",
+    "@xemahq/kernel-contracts": "^0.6.0"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/lib/composer.ts

@@ -277,7 +277,7 @@ export class DefaultWorkspaceImageComposer implements WorkspaceImageComposer {
         mode: WorkspaceMountMode.ReadOnly,
         mountKey: `agent-bundle:${req.manifest.agent.slug}`,
         source: {
-          kind: 'agent-definition',
+          kind: 'agent-kernel',
           orgId: req.orgId,
           agentSlug: req.manifest.agent.slug,
           stageKey: req.manifest.agent.stageKey,
@@ -294,7 +294,7 @@ export class DefaultWorkspaceImageComposer implements WorkspaceImageComposer {
           mode: WorkspaceMountMode.ReadOnly,
           mountKey: `agent-bundle:${sub}`,
           source: {
-            kind: 'agent-definition',
+            kind: 'agent-kernel',
             orgId: req.orgId,
             agentSlug: sub,
             stageKey: req.manifest.agent.stageKey,

package/src/lib/composition-resolution.ts

@@ -1,7 +1,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── Shared composition-resolver primitives ──
 //
-// The "one resolver, not N" foundation. Composition (agent) tree resolution
+// The "one resolver, not N" foundation. Agent (agent) tree resolution
 // — walk the tree, collect skills / tools, append instructions, merge the
 // permission/model overlay, and project to a runtime config — was
 // re-implemented in agent-session-api, the workflow-runtime-worker, and
@@ -9,14 +9,14 @@
 // `modelOverride` and collected only the root node's skills). This module
 // extracts the PURE parts so every consumer shares ONE implementation.
 //
-// All inputs are kernel `ResolvedComposition` / `ResolvedCompositionNode`
+// All inputs are kernel `ResolvedAgent` / `ResolvedAgentNode`
 // shapes (`@xemahq/kernel-contracts/agent-composition`). Each node `extends
 // NodeOverlayFragment`, so its `modelOverride` / `instructions` / `permission`
 // overlay trio is read directly off the node — no per-shape restatement.
 //
 // Tier-1 functions (collect / walk) copy the canonical agent-session-api
 // resolver semantics EXACTLY: depth-first PRE-ORDER over DESCENDANTS,
-// FIRST-occurrence-by-slug wins. Tier-2 (`projectCompositionToRuntimeConfig`)
+// FIRST-occurrence-by-slug wins. Tier-2 (`projectAgentToRuntimeConfig`)
 // assembles those into the runtime projection.
 //
 // `RuntimeAgentConfig` lives HERE, not in `@xemahq/kernel-contracts`, because
@@ -35,8 +35,8 @@ import {
   type SubAgentBinding,
 } from '@xemahq/kernel-contracts/workflow';
 import type {
-  ResolvedComposition,
-  ResolvedCompositionNode,
+  ResolvedAgent,
+  ResolvedAgentNode,
 } from '@xemahq/kernel-contracts/agent-composition';
 import type { PermissionMap } from '@xemahq/kernel-contracts/agent-permission';
 import {
@@ -52,10 +52,10 @@ import {
  * composition resolver in llm-registry-api owns the wire format, so drift is
  * a platform bug, not a user error. Fail-fast: no silent coercion.
  */
-export class CompositionResolutionError extends Error {
+export class AgentResolutionError extends Error {
   constructor(context: string, detail: string) {
-    super(`Composition resolution failed for "${context}": ${detail}`);
-    this.name = 'CompositionResolutionError';
+    super(`Agent resolution failed for "${context}": ${detail}`);
+    this.name = 'AgentResolutionError';
   }
 }
 
@@ -68,7 +68,7 @@ export class CompositionResolutionError extends Error {
  * dropped. Mirrors {@link SubAgentBinding} minus the kernel's intrinsic-floor
  * semantics (those are merged downstream, per-consumer).
  */
-export interface FlattenedCompositionNode {
+export interface FlattenedAgentNode {
   readonly slug: string;
   readonly alias?: string;
   readonly modelOverride?: ModelRef;
@@ -91,7 +91,7 @@ export interface CollectScopeOptions {
  * PROJECTION, not a wire contract — lives in this lib, not kernel-contracts.
  */
 export interface RuntimeAgentConfig {
-  readonly compositionRef: string;
+  readonly agentRef: string;
   readonly primaryAgentSlug: string;
   /** Root instructions (+ overlay), normalized; `null` when none. */
   readonly primaryInstructions: string | null;
@@ -123,14 +123,14 @@ export interface RuntimeAgentConfig {
  * This is where the worker drift is corrected: `modelOverride` is carried on
  * every entry, never dropped.
  */
-export function flattenCompositionTree(
-  root: ResolvedCompositionNode,
-): readonly FlattenedCompositionNode[] {
+export function flattenAgentTree(
+  root: ResolvedAgentNode,
+): readonly FlattenedAgentNode[] {
   const seen = new Set<string>();
-  const out: FlattenedCompositionNode[] = [];
-  const visit = (node: ResolvedCompositionNode): void => {
+  const out: FlattenedAgentNode[] = [];
+  const visit = (node: ResolvedAgentNode): void => {
     for (const child of node.children) {
-      const slug = child.agent.slug;
+      const slug = child.kernel.slug;
       if (slug.length === 0) {
         continue;
       }
@@ -160,13 +160,13 @@ export function flattenCompositionTree(
  * only.
  */
 export function collectSkills(
-  root: ResolvedCompositionNode,
+  root: ResolvedAgentNode,
   opts?: CollectScopeOptions,
 ): readonly string[] {
   const scope = opts?.scope ?? 'tree';
   const seen = new Set<string>();
   const out: string[] = [];
-  const addNode = (node: ResolvedCompositionNode): void => {
+  const addNode = (node: ResolvedAgentNode): void => {
     for (const slug of projectSkillSlugs(node.skills)) {
       if (!seen.has(slug)) {
         seen.add(slug);
@@ -176,7 +176,7 @@ export function collectSkills(
   };
   addNode(root);
   if (scope === 'tree') {
-    const visit = (node: ResolvedCompositionNode): void => {
+    const visit = (node: ResolvedAgentNode): void => {
       for (const child of node.children) {
         addNode(child);
         visit(child);
@@ -194,18 +194,18 @@ export function collectSkills(
  * fail-fast via {@link projectToolSelection}.
  */
 export function collectTools(
-  root: ResolvedCompositionNode,
+  root: ResolvedAgentNode,
   opts?: CollectScopeOptions,
 ): readonly ToolSelectionEntry[] {
   const scope = opts?.scope ?? 'root';
-  const ctx = root.agent.slug;
+  const ctx = root.kernel.slug;
   if (scope === 'root') {
     return projectToolSelection(root.tools, ctx);
   }
   const out: ToolSelectionEntry[] = [...projectToolSelection(root.tools, ctx)];
-  const visit = (node: ResolvedCompositionNode): void => {
+  const visit = (node: ResolvedAgentNode): void => {
     for (const child of node.children) {
-      out.push(...projectToolSelection(child.tools, child.agent.slug));
+      out.push(...projectToolSelection(child.tools, child.kernel.slug));
       visit(child);
     }
   };
@@ -215,11 +215,11 @@ export function collectTools(
 
 /**
  * Per-descendant-slug normalized instructions, keyed by agent slug. Mirrors
- * {@link flattenCompositionTree} (DFS pre-order, first-wins). A descendant
+ * {@link flattenAgentTree} (DFS pre-order, first-wins). A descendant
  * with no (or whitespace-only) instructions contributes no key.
  */
 export function collectInstructionsBySlug(
-  root: ResolvedCompositionNode,
+  root: ResolvedAgentNode,
 ): Readonly<Record<string, string>> {
   return collectDescendantOverlay(root, (child) =>
     normalizeInstructions(child.instructions),
@@ -231,7 +231,7 @@ export function collectInstructionsBySlug(
  * first-wins. A descendant with no (or empty) override contributes no key.
  */
 export function collectPermissionsBySlug(
-  root: ResolvedCompositionNode,
+  root: ResolvedAgentNode,
 ): Readonly<Record<string, PermissionMap>> {
   return collectDescendantOverlay(root, (child) =>
     normalizePermission(child.permission),
@@ -244,10 +244,10 @@ export function collectPermissionsBySlug(
  * with no override contributes no key. Each override is validated fail-fast.
  */
 export function collectModelOverridesBySlug(
-  root: ResolvedCompositionNode,
+  root: ResolvedAgentNode,
 ): Readonly<Record<string, ModelRef>> {
   return collectDescendantOverlay(root, (child) =>
-    projectModelOverride(child.modelOverride, child.agent.slug),
+    projectModelOverride(child.modelOverride, child.kernel.slug),
   );
 }
 
@@ -258,14 +258,14 @@ export function collectModelOverridesBySlug(
  * with no override. Centralizes the walk the three per-slug collectors share.
  */
 function collectDescendantOverlay<T>(
-  root: ResolvedCompositionNode,
-  project: (child: ResolvedCompositionNode) => T | null,
+  root: ResolvedAgentNode,
+  project: (child: ResolvedAgentNode) => T | null,
 ): Readonly<Record<string, T>> {
   const out: Record<string, T> = {};
   const seen = new Set<string>();
-  const visit = (node: ResolvedCompositionNode): void => {
+  const visit = (node: ResolvedAgentNode): void => {
     for (const child of node.children) {
-      const slug = child.agent.slug;
+      const slug = child.kernel.slug;
       if (slug.length === 0) {
         continue;
       }
@@ -354,7 +354,7 @@ export function projectModelOverride(
   }
   if (raw.kind === ModelRefKind.CONCRETE) {
     if (typeof raw.modelId !== 'string' || raw.modelId.trim().length === 0) {
-      throw new CompositionResolutionError(
+      throw new AgentResolutionError(
         context,
         'concrete modelOverride is missing a modelId',
       );
@@ -368,7 +368,7 @@ export function projectModelOverride(
     modelClass === undefined ||
     !MODEL_CLASS_VALUES.includes(modelClass as ModelClass)
   ) {
-    throw new CompositionResolutionError(
+    throw new AgentResolutionError(
       context,
       `strategy modelOverride.modelClass must be one of ${MODEL_CLASS_VALUES.join(
         ', ',
@@ -380,7 +380,7 @@ export function projectModelOverride(
 
 /** Project a node's skill refs into a flat, non-empty slug list. */
 function projectSkillSlugs(
-  skills: ResolvedCompositionNode['skills'] | undefined,
+  skills: ResolvedAgentNode['skills'] | undefined,
 ): string[] {
   if (!Array.isArray(skills)) {
     return [];
@@ -397,7 +397,7 @@ function projectSkillSlugs(
  * Fail-fast on shape errors — the composition resolver owns the wire format.
  */
 function projectToolSelection(
-  tools: ResolvedCompositionNode['tools'] | undefined,
+  tools: ResolvedAgentNode['tools'] | undefined,
   context: string,
 ): ToolSelectionEntry[] {
   if (!Array.isArray(tools)) {
@@ -410,7 +410,7 @@ function projectToolSelection(
       typeof tool.providerKind !== 'string' ||
       !validKinds.has(tool.providerKind)
     ) {
-      throw new CompositionResolutionError(
+      throw new AgentResolutionError(
         context,
         `tools[${idx}].providerKind must be one of ${Object.values(
           ToolProviderKind,
@@ -421,7 +421,7 @@ function projectToolSelection(
       typeof tool.resourceId !== 'string' ||
       tool.resourceId.trim().length === 0
     ) {
-      throw new CompositionResolutionError(
+      throw new AgentResolutionError(
         context,
         `tools[${idx}].resourceId must be a non-empty string`,
       );
@@ -437,7 +437,7 @@ function projectToolSelection(
         typeof tool.toolName !== 'string' ||
         tool.toolName.trim().length === 0
       ) {
-        throw new CompositionResolutionError(
+        throw new AgentResolutionError(
           context,
           `tools[${idx}].toolName must be a non-empty string for kind='tool'`,
         );
@@ -449,7 +449,7 @@ function projectToolSelection(
         toolName: tool.toolName,
       });
     } else {
-      throw new CompositionResolutionError(
+      throw new AgentResolutionError(
         context,
         `tools[${idx}].kind must be "provider" or "tool"`,
       );
@@ -461,7 +461,7 @@ function projectToolSelection(
 // ─── Tier-2: projection ───────────────────────────────────────────────────────
 
 /**
- * Project a `ResolvedComposition` into a {@link RuntimeAgentConfig} — the
+ * Project a `ResolvedAgent` into a {@link RuntimeAgentConfig} — the
  * runtime-facing shape a driver materializes the primary agent + delegates
  * from. The single resolver every consumer shares.
  *
@@ -477,12 +477,12 @@ function projectToolSelection(
  *     deep-merge against the AGENT's authored permission happens in the
  *     downstream materializer, not in this projection).
  */
-export function projectCompositionToRuntimeConfig(
-  resolved: ResolvedComposition,
+export function projectAgentToRuntimeConfig(
+  resolved: ResolvedAgent,
   overlay?: NodeOverlayFragment,
 ): RuntimeAgentConfig {
   const root = resolved.root;
-  const compositionRef = `${resolved.slug}@${resolved.version}`;
+  const agentRef = `${resolved.slug}@${resolved.version}`;
 
   const rootInstructions = normalizeInstructions(root.instructions);
   const overlayInstructions = normalizeInstructions(overlay?.instructions);
@@ -494,21 +494,21 @@ export function projectCompositionToRuntimeConfig(
 
   const rootModelOverride = projectModelOverride(
     root.modelOverride,
-    compositionRef,
+    agentRef,
   );
   const overlayModelOverride = projectModelOverride(
     overlay?.modelOverride,
-    `${compositionRef}#overlay`,
+    `${agentRef}#overlay`,
   );
 
   const rootPermission = normalizePermission(root.permission);
   const overlayPermission = normalizePermission(overlay?.permission);
 
-  const flattened = flattenCompositionTree(root);
+  const flattened = flattenAgentTree(root);
 
   return {
-    compositionRef,
-    primaryAgentSlug: root.agent.slug,
+    agentRef,
+    primaryAgentSlug: root.kernel.slug,
     primaryInstructions:
       primaryInstructions.length > 0 ? primaryInstructions : null,
     primaryPermission: overlayPermission ?? rootPermission,

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

@@ -1,5 +1,5 @@
 // ═══════════════════════════════════════════════════════════════════════════
-// ── Composition → CompiledWorkspaceManifest reconstruction ──
+// ── Agent → CompiledWorkspaceManifest reconstruction ──
 //
 // Phase 10 (`workspace-manifests-api` retirement). The composer turns a
 // `CompiledWorkspaceManifest` into a `WorkspaceMountPlan`; before this
@@ -7,7 +7,7 @@
 // `WorkspaceManifest` row from `workspace-manifests-api` and run
 // `compileManifest` on it.
 //
-// The Agent Composition primitive now carries the user-data MOUNT LAYOUT
+// The Agent 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
@@ -62,22 +62,22 @@ export type { CompiledWorkspaceManifest };
  * 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) {
+export class AgentMountLayoutError extends Error {
+  constructor(agentRef: string, detail: string) {
     super(
-      `Cannot derive a workspace mount layout from Agent Composition ` +
-        `"${compositionRef}": ${detail}`,
+      `Cannot derive a workspace mount layout from Agent ` +
+        `"${agentRef}": ${detail}`,
     );
-    this.name = 'CompositionMountLayoutError';
+    this.name = 'AgentMountLayoutError';
   }
 }
 
 /**
  * The agent run-config the seeder projects from the source manifest's
- * `spec.agent` block. Mirrors `CompositionAgentRunConfigDto` without
+ * `spec.agent` block. Mirrors `AgentRunConfigDto` without
  * importing the generated client.
  */
-export interface CompositionAgentRunConfigInput {
+export interface AgentRunConfigInput {
   /** Stage key. */
   readonly stage: string;
   /** Canonical `AgentRunRole` — drives renderer + system-overlay framing. */
@@ -96,11 +96,11 @@ export interface CompositionAgentRunConfigInput {
  * / `inputs` against the manifest DSL's authoritative schema, so the loose
  * typing here is checked downstream, not silently trusted.
  */
-export interface CompositionMountLayoutInput {
+export interface AgentMountLayoutInput {
   /** Raw `spec.mounts` block — manifest DSL mount-declaration map. */
   readonly mounts: Readonly<Record<string, unknown>>;
   /** Projected `spec.agent` run-config. */
-  readonly agentRunConfig: CompositionAgentRunConfigInput;
+  readonly agentRunConfig: AgentRunConfigInput;
   /** Raw `spec.seedFiles` array — manifest DSL seed-file entries. */
   readonly seedFiles: readonly unknown[];
   /** Raw `spec.inputs` block — manifest DSL input-declaration map. */
@@ -118,7 +118,7 @@ export interface CompositionMountLayoutInput {
  * worker drift). All optional ⇒ backward-compatible with callers that only
  * supply `slug` / `alias`.
  */
-export interface CompositionSubAgentBindingInput {
+export interface AgentSubAgentBindingInput {
   readonly slug: string;
   readonly alias?: string;
   /** Per-delegate model override — OVERRIDE on the referenced agent's model. */
@@ -141,7 +141,7 @@ export interface CompositionSubAgentBindingInput {
  * same kind/root/port the bundle-apply path reads from
  * `composition.workspace.outputSurface`.
  */
-export interface CompositionOutputSurfaceInput {
+export interface AgentOutputSurfaceInput {
   readonly kind: 'none' | 'web' | 'static' | 'app' | 'tunnel';
   readonly port?: number;
   readonly healthPath?: string;
@@ -156,19 +156,19 @@ export interface CompositionOutputSurfaceInput {
  * `WorkspaceManifest` from. The caller maps its richer resolved-composition
  * shape onto this — keeping the runtime package free of any API client.
  */
-export interface CompositionManifestSource {
+export interface AgentManifestSource {
   /** Version-pinned `slug@version` of the resolved composition. */
-  readonly compositionRef: string;
+  readonly agentRef: 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[];
+  readonly subAgentBindings: readonly AgentSubAgentBindingInput[];
   /**
    * 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;
+  readonly mountLayout: AgentMountLayoutInput | undefined;
   /**
    * The composition's `workspace.outputSurface` block. Threaded into the
    * reconstructed manifest's `spec.outputSurface` so the compiled
@@ -178,7 +178,7 @@ export interface CompositionManifestSource {
    * composition declared no surface — the DSL compile then yields the
    * `{ kind: 'none' }` default.
    */
-  readonly outputSurface?: CompositionOutputSurfaceInput;
+  readonly outputSurface?: AgentOutputSurfaceInput;
   /**
    * The composition's `workspace.credentials` block. Threaded into the
    * reconstructed manifest's `spec.credentials` so the compiled manifest's
@@ -218,7 +218,7 @@ export interface CompositionManifestSource {
  * 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 {
+export interface AgentManifestImplicitInputs {
   readonly orgId: string;
   readonly projectId: string;
   readonly sessionId?: string;
@@ -242,18 +242,18 @@ type ManifestInputValue =
  * shape.
  *
  * `bindInputs` is the resolved manifest input bag (explicit inputs ∪
- * implicit inputs), built by {@link buildCompositionManifestBindInputs}.
+ * implicit inputs), built by {@link buildAgentManifestBindInputs}.
  * The compile fails fast on an unresolved required input or an enum
  * violation — exactly the legacy behaviour.
  */
-export function compileCompositionWorkspaceManifest(
-  source: CompositionManifestSource,
+export function compileAgentWorkspaceManifest(
+  source: AgentManifestSource,
   bindInputs: Readonly<Record<string, unknown>>,
 ): CompiledWorkspaceManifest {
   const mountLayout = source.mountLayout;
   if (!mountLayout) {
-    throw new CompositionMountLayoutError(
-      source.compositionRef,
+    throw new AgentMountLayoutError(
+      source.agentRef,
       '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 ' +
@@ -261,7 +261,7 @@ export function compileCompositionWorkspaceManifest(
     );
   }
 
-  const [slug, version] = splitCompositionRef(source.compositionRef);
+  const [slug, version] = splitAgentRef(source.agentRef);
 
   // Sub-agents the composition resolved become the manifest agent block's
   // `subAgents[]`. The composer + EnvironmentResolver surface these on the
@@ -333,7 +333,7 @@ export function compileCompositionWorkspaceManifest(
     metadata: {
       slug,
       version,
-      // Compositions resolved for a session bootstrap are, by definition,
+      // Agents 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],
@@ -343,8 +343,8 @@ export function compileCompositionWorkspaceManifest(
 
   const result = compileManifest(envelope, bindInputs);
   if (!result.ok) {
-    throw new CompositionMountLayoutError(
-      source.compositionRef,
+    throw new AgentMountLayoutError(
+      source.agentRef,
       `reconstructed manifest failed to compile: ${result.errors
         .map((e) => `${e.path}: ${e.message}`)
         .join('; ')}`,
@@ -355,7 +355,7 @@ export function compileCompositionWorkspaceManifest(
 
 /**
  * Project the composition's `workspace.outputSurface` block (carried on
- * the runtime-agnostic `CompositionManifestSource`) into the manifest DSL's
+ * the runtime-agnostic `AgentManifestSource`) 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` /
@@ -366,7 +366,7 @@ export function compileCompositionWorkspaceManifest(
  * `{ kind: 'none', autoOpen: false, mode: 'single' }`.
  */
 function projectOutputSurface(
-  surface: CompositionOutputSurfaceInput | undefined,
+  surface: AgentOutputSurfaceInput | undefined,
 ): ManifestOutputSurface | undefined {
   if (!surface) return undefined;
   return {
@@ -386,7 +386,7 @@ function projectOutputSurface(
 
 /**
  * Project the composition's `workspace.credentials` block (carried on the
- * runtime-agnostic `CompositionManifestSource` as the kernel
+ * runtime-agnostic `AgentManifestSource` as the kernel
  * `CompiledManifestCredential[]`) into the manifest DSL's authored
  * `ManifestCredential[]` shape so the reconstructed envelope's
  * `spec.credentials` carries the same entries as the source.
@@ -415,7 +415,7 @@ function projectCredentials(
 
 /**
  * Project the composition's `workspace.permissions` block (carried on the
- * runtime-agnostic `CompositionManifestSource` as the kernel
+ * runtime-agnostic `AgentManifestSource` as the kernel
  * `CompiledManifestPermissions`) into the manifest DSL's authored
  * `ManifestPermissions` shape so the reconstructed envelope's
  * `spec.permissions` carries the same tool allow/deny lists as the source.
@@ -457,10 +457,10 @@ function projectPermissions(
  *
  * Returns `{}` when the composition declared no inputs.
  */
-export function buildCompositionManifestBindInputs(
-  source: CompositionManifestSource,
+export function buildAgentManifestBindInputs(
+  source: AgentManifestSource,
   explicitInputs: Record<string, unknown> | null,
-  implicitInputs: CompositionManifestImplicitInputs,
+  implicitInputs: AgentManifestImplicitInputs,
 ): Readonly<Record<string, unknown>> {
   const declared = new Set(Object.keys(source.mountLayout?.inputs ?? {}));
   if (declared.size === 0) {
@@ -471,20 +471,20 @@ export function buildCompositionManifestBindInputs(
     explicitInputs !== null &&
     (typeof explicitInputs !== 'object' || Array.isArray(explicitInputs))
   ) {
-    throw new CompositionMountLayoutError(
-      source.compositionRef,
+    throw new AgentMountLayoutError(
+      source.agentRef,
       '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,
+      throw new AgentMountLayoutError(
+        source.agentRef,
         `manifest inputs contain undeclared key "${key}"`,
       );
     }
-    assertManifestInputValue(source.compositionRef, key, value);
+    assertManifestInputValue(source.agentRef, key, value);
   }
 
   const implicit: Record<string, ManifestInputValue> = {
@@ -509,10 +509,10 @@ export function buildCompositionManifestBindInputs(
 }
 
 /** Split a `slug@version` composition ref; fail fast on a bare slug. */
-function splitCompositionRef(ref: string): [slug: string, version: string] {
+function splitAgentRef(ref: string): [slug: string, version: string] {
   const at = ref.lastIndexOf('@');
   if (at <= 0 || at === ref.length - 1) {
-    throw new CompositionMountLayoutError(
+    throw new AgentMountLayoutError(
       ref,
       'expected a version-pinned `slug@version` composition ref — the ' +
         'session resolver always pins the resolved version',
@@ -528,7 +528,7 @@ function splitCompositionRef(ref: string): [slug: string, version: string] {
  * boundary so the error surfaces near the cause.
  */
 function assertManifestInputValue(
-  compositionRef: string,
+  agentRef: string,
   key: string,
   value: unknown,
 ): void {
@@ -539,8 +539,8 @@ function assertManifestInputValue(
     typeof value !== 'boolean' &&
     !Array.isArray(value)
   ) {
-    throw new CompositionMountLayoutError(
-      compositionRef,
+    throw new AgentMountLayoutError(
+      agentRef,
       `manifest input "${key}" must be a primitive ` +
         `(string, number, boolean, string[]) — got ${typeof value}`,
     );
@@ -549,8 +549,8 @@ function assertManifestInputValue(
     Array.isArray(value) &&
     !value.every((entry) => typeof entry === 'string')
   ) {
-    throw new CompositionMountLayoutError(
-      compositionRef,
+    throw new AgentMountLayoutError(
+      agentRef,
       `manifest input "${key}" is an array — every element must be a string`,
     );
   }

package/src/lib/dispatch-contract.ts

@@ -84,14 +84,14 @@ export interface CreateAndRunDispatch {
   /** Stable spine identity within the workflow run. */
   readonly jobKey: string;
   /**
-   * Agent Composition ref (`slug` = latest published, or `slug@version`)
+   * Agent 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
+   * service stamps this onto `Session.agentRef`; 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 agentRef: string;
   readonly agentSlug: string;
   readonly promptContext: DispatchPromptContext;
 }