@xemahq/agent-session-runtime 0.1.1 → 0.2.0

package/src/lib/composition-resolution.ts

@@ -0,0 +1,524 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Shared composition-resolver primitives ──
+//
+// The "one resolver, not N" foundation. Composition (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
+// workspace-proxy with drift and two live bugs (the worker dropped sub-agent
+// `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`
+// 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`)
+// assembles those into the runtime projection.
+//
+// `RuntimeAgentConfig` lives HERE, not in `@xemahq/kernel-contracts`, because
+// it is a runtime PROJECTION (assembled by this resolver for in-process
+// consumers) — not a wire contract crossing a service boundary. Kernel
+// contracts are reserved for shapes two services must agree on; this is an
+// implementation detail of the shared resolver.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  ModelRefKind,
+  MODEL_CLASS_VALUES,
+  type ModelClass,
+  type ModelRef,
+  type NodeOverlayFragment,
+  type SubAgentBinding,
+} from '@xemahq/kernel-contracts/workflow';
+import type {
+  ResolvedComposition,
+  ResolvedCompositionNode,
+} from '@xemahq/kernel-contracts/agent-composition';
+import type { PermissionMap } from '@xemahq/kernel-contracts/agent-permission';
+import {
+  ToolProviderKind,
+  type ToolSelectionEntry,
+} from '@xemahq/kernel-contracts/mcp-tool';
+
+// ─── Errors ──────────────────────────────────────────────────────────────────
+
+/**
+ * Raised when a resolved composition node carries a malformed overlay the
+ * resolver cannot project — an invalid `modelOverride` or `tools` entry. The
+ * 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 {
+  constructor(context: string, detail: string) {
+    super(`Composition resolution failed for "${context}": ${detail}`);
+    this.name = 'CompositionResolutionError';
+  }
+}
+
+// ─── Local types ──────────────────────────────────────────────────────────────
+
+/**
+ * The flattened, runtime-facing form of one DESCENDANT composition node —
+ * its slug plus the {@link NodeOverlayFragment} overlay trio carried verbatim
+ * off the resolved node. THE worker bug fix: `modelOverride` is carried, not
+ * dropped. Mirrors {@link SubAgentBinding} minus the kernel's intrinsic-floor
+ * semantics (those are merged downstream, per-consumer).
+ */
+export interface FlattenedCompositionNode {
+  readonly slug: string;
+  readonly alias?: string;
+  readonly modelOverride?: ModelRef;
+  readonly instructions?: string;
+  readonly permission?: PermissionMap;
+}
+
+/** Scope selector for the tree-collectors. */
+export interface CollectScopeOptions {
+  /**
+   * `'tree'` = root node ∪ every descendant (de-duped, first-seen order).
+   * `'root'` = the root node only.
+   */
+  readonly scope?: 'tree' | 'root';
+}
+
+/**
+ * The runtime projection of a resolved composition: everything a runtime
+ * driver needs to materialize the primary agent + its delegates. A
+ * PROJECTION, not a wire contract — lives in this lib, not kernel-contracts.
+ */
+export interface RuntimeAgentConfig {
+  readonly compositionRef: string;
+  readonly primaryAgentSlug: string;
+  /** Root instructions (+ overlay), normalized; `null` when none. */
+  readonly primaryInstructions: string | null;
+  /** Root permission (+ overlay); `null` when none. */
+  readonly primaryPermission: PermissionMap | null;
+  /** Root model override (+ overlay); `null` when none. */
+  readonly primaryModelOverride: ModelRef | null;
+  /** Flattened descendant bindings — NOW carrying the overlay trio. */
+  readonly subAgentBindings: readonly SubAgentBinding[];
+  readonly subAgentInstructionsBySlug: Readonly<Record<string, string>>;
+  readonly subAgentPermissionBySlug: Readonly<Record<string, PermissionMap>>;
+  readonly subAgentModelOverridesBySlug: Readonly<Record<string, ModelRef>>;
+  /** Root-scoped skill slugs. */
+  readonly defaultSkillSlugs: readonly string[];
+  /** Whole-tree skill slugs (root ∪ descendants). */
+  readonly allSkillSlugs: readonly string[];
+  /** Root-scoped tool selection. */
+  readonly defaultToolSelection: readonly ToolSelectionEntry[];
+}
+
+// ─── Tier-1: collect / walk ───────────────────────────────────────────────────
+
+/**
+ * Flatten the resolved composition tree's DESCENDANT nodes (NOT the root)
+ * into a flat list. Depth-first PRE-ORDER; on a slug appearing more than once
+ * the FIRST occurrence wins so its `alias` / overlay trio are deterministic.
+ * A node with an empty slug is skipped (defends against a malformed resolve).
+ *
+ * This is where the worker drift is corrected: `modelOverride` is carried on
+ * every entry, never dropped.
+ */
+export function flattenCompositionTree(
+  root: ResolvedCompositionNode,
+): readonly FlattenedCompositionNode[] {
+  const seen = new Set<string>();
+  const out: FlattenedCompositionNode[] = [];
+  const visit = (node: ResolvedCompositionNode): void => {
+    for (const child of node.children) {
+      const slug = child.agent.slug;
+      if (slug.length === 0) {
+        continue;
+      }
+      if (!seen.has(slug)) {
+        seen.add(slug);
+        out.push({
+          slug,
+          ...(child.alias ? { alias: child.alias } : {}),
+          ...(child.modelOverride
+            ? { modelOverride: child.modelOverride }
+            : {}),
+          ...(child.instructions ? { instructions: child.instructions } : {}),
+          ...(child.permission ? { permission: child.permission } : {}),
+        });
+      }
+      visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}
+
+/**
+ * Collect skill slugs. `scope: 'tree'` (default) = de-duped union of the root
+ * node's skills plus every descendant's, in first-seen order — fixes the
+ * worker "root-skills-only" bug. `scope: 'root'` = the root node's skills
+ * only.
+ */
+export function collectSkills(
+  root: ResolvedCompositionNode,
+  opts?: CollectScopeOptions,
+): readonly string[] {
+  const scope = opts?.scope ?? 'tree';
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const addNode = (node: ResolvedCompositionNode): void => {
+    for (const slug of projectSkillSlugs(node.skills)) {
+      if (!seen.has(slug)) {
+        seen.add(slug);
+        out.push(slug);
+      }
+    }
+  };
+  addNode(root);
+  if (scope === 'tree') {
+    const visit = (node: ResolvedCompositionNode): void => {
+      for (const child of node.children) {
+        addNode(child);
+        visit(child);
+      }
+    };
+    visit(root);
+  }
+  return out;
+}
+
+/**
+ * Collect tool selection. `scope: 'root'` (default — matches today's
+ * behaviour) = the root node's tools. `scope: 'tree'` = the root node's tools
+ * followed by every descendant's, in pre-order. Every entry is validated
+ * fail-fast via {@link projectToolSelection}.
+ */
+export function collectTools(
+  root: ResolvedCompositionNode,
+  opts?: CollectScopeOptions,
+): readonly ToolSelectionEntry[] {
+  const scope = opts?.scope ?? 'root';
+  const ctx = root.agent.slug;
+  if (scope === 'root') {
+    return projectToolSelection(root.tools, ctx);
+  }
+  const out: ToolSelectionEntry[] = [...projectToolSelection(root.tools, ctx)];
+  const visit = (node: ResolvedCompositionNode): void => {
+    for (const child of node.children) {
+      out.push(...projectToolSelection(child.tools, child.agent.slug));
+      visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}
+
+/**
+ * Per-descendant-slug normalized instructions, keyed by agent slug. Mirrors
+ * {@link flattenCompositionTree} (DFS pre-order, first-wins). A descendant
+ * with no (or whitespace-only) instructions contributes no key.
+ */
+export function collectInstructionsBySlug(
+  root: ResolvedCompositionNode,
+): Readonly<Record<string, string>> {
+  return collectDescendantOverlay(root, (child) =>
+    normalizeInstructions(child.instructions),
+  );
+}
+
+/**
+ * Per-descendant-slug permission overlay, keyed by agent slug. DFS pre-order,
+ * first-wins. A descendant with no (or empty) override contributes no key.
+ */
+export function collectPermissionsBySlug(
+  root: ResolvedCompositionNode,
+): Readonly<Record<string, PermissionMap>> {
+  return collectDescendantOverlay(root, (child) =>
+    normalizePermission(child.permission),
+  );
+}
+
+/**
+ * Per-descendant-slug `modelOverride`, keyed by agent slug — the BUG-2
+ * surface (the worker dropped these). DFS pre-order, first-wins. A descendant
+ * with no override contributes no key. Each override is validated fail-fast.
+ */
+export function collectModelOverridesBySlug(
+  root: ResolvedCompositionNode,
+): Readonly<Record<string, ModelRef>> {
+  return collectDescendantOverlay(root, (child) =>
+    projectModelOverride(child.modelOverride, child.agent.slug),
+  );
+}
+
+/**
+ * Shared DFS-pre-order, first-occurrence-wins walk over the DESCENDANT nodes,
+ * projecting each child to an optional overlay value via `project`. A `null`
+ * projection contributes no key — keeping the wire byte-identical for nodes
+ * with no override. Centralizes the walk the three per-slug collectors share.
+ */
+function collectDescendantOverlay<T>(
+  root: ResolvedCompositionNode,
+  project: (child: ResolvedCompositionNode) => T | null,
+): Readonly<Record<string, T>> {
+  const out: Record<string, T> = {};
+  const seen = new Set<string>();
+  const visit = (node: ResolvedCompositionNode): void => {
+    for (const child of node.children) {
+      const slug = child.agent.slug;
+      if (slug.length === 0) {
+        continue;
+      }
+      if (!seen.has(slug)) {
+        seen.add(slug);
+        const value = project(child);
+        if (value !== null) {
+          out[slug] = value;
+        }
+      }
+      visit(child);
+    }
+  };
+  visit(root);
+  return out;
+}
+
+// ─── Instruction-append primitive ─────────────────────────────────────────────
+
+/**
+ * THE single "append node instructions after the base prompt" primitive every
+ * consumer shares. Base prompt FIRST, a blank-line separator, then the
+ * trimmed instructions. Empty / whitespace-only / `null` instructions leave
+ * the base prompt UNCHANGED — no trailing append — so a no-instructions node
+ * is byte-identical to the pre-instructions behaviour.
+ */
+export function appendInstructions(
+  baseSystemPrompt: string,
+  nodeInstructions: string | null,
+): string {
+  const trimmed = nodeInstructions === null ? '' : nodeInstructions.trim();
+  if (trimmed.length === 0) {
+    return baseSystemPrompt;
+  }
+  // Empty base (e.g. a root node with no own instructions layered with an
+  // overlay) ⇒ the instructions ARE the result, with no leading separator.
+  if (baseSystemPrompt.length === 0) {
+    return trimmed;
+  }
+  return `${baseSystemPrompt}\n\n${trimmed}`;
+}
+
+// ─── Normalizers / projectors (copied from the canonical resolver) ────────────
+
+/**
+ * Normalize a node's optional `instructions` to a trimmed non-empty string or
+ * `null`. A node that omits instructions — or declares a whitespace-only
+ * value — yields `null` so the render path stays byte-identical to the
+ * pre-instructions behaviour. The length cap is enforced upstream at
+ * composition write time; this is not a re-validation.
+ */
+export function normalizeInstructions(raw: string | undefined): string | null {
+  if (typeof raw !== 'string') {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Normalize a node's optional `permission` override to a non-empty map or
+ * `null`. Structural validation happened upstream at composition write time;
+ * this only drops an absent / empty map so the wire stays byte-identical for
+ * nodes with no override.
+ */
+export function normalizePermission(
+  raw: PermissionMap | undefined,
+): PermissionMap | null {
+  if (!raw || typeof raw !== 'object' || Object.keys(raw).length === 0) {
+    return null;
+  }
+  return raw;
+}
+
+/**
+ * Project a node's optional `modelOverride` into a validated kernel
+ * {@link ModelRef}, or `null` when absent. Fail-fast on shape errors — the
+ * composition resolver owns the wire format, so drift is a platform bug.
+ */
+export function projectModelOverride(
+  raw: ModelRef | undefined,
+  context: string,
+): ModelRef | null {
+  if (raw === undefined) {
+    return null;
+  }
+  if (raw.kind === ModelRefKind.CONCRETE) {
+    if (typeof raw.modelId !== 'string' || raw.modelId.trim().length === 0) {
+      throw new CompositionResolutionError(
+        context,
+        'concrete modelOverride is missing a modelId',
+      );
+    }
+    return raw;
+  }
+  // `kind` is the closed `concrete | strategy` set — this is the strategy
+  // branch.
+  const modelClass = raw.modelClass;
+  if (
+    modelClass === undefined ||
+    !MODEL_CLASS_VALUES.includes(modelClass as ModelClass)
+  ) {
+    throw new CompositionResolutionError(
+      context,
+      `strategy modelOverride.modelClass must be one of ${MODEL_CLASS_VALUES.join(
+        ', ',
+      )}`,
+    );
+  }
+  return raw;
+}
+
+/** Project a node's skill refs into a flat, non-empty slug list. */
+function projectSkillSlugs(
+  skills: ResolvedCompositionNode['skills'] | undefined,
+): string[] {
+  if (!Array.isArray(skills)) {
+    return [];
+  }
+  return skills
+    .map((s) => s.slug)
+    .filter(
+      (slug): slug is string => typeof slug === 'string' && slug.length > 0,
+    );
+}
+
+/**
+ * Project a node's tool refs into the validated `ToolSelectionEntry[]` shape.
+ * Fail-fast on shape errors — the composition resolver owns the wire format.
+ */
+function projectToolSelection(
+  tools: ResolvedCompositionNode['tools'] | undefined,
+  context: string,
+): ToolSelectionEntry[] {
+  if (!Array.isArray(tools)) {
+    return [];
+  }
+  const validKinds = new Set<string>(Object.values(ToolProviderKind));
+  const out: ToolSelectionEntry[] = [];
+  for (const [idx, tool] of tools.entries()) {
+    if (
+      typeof tool.providerKind !== 'string' ||
+      !validKinds.has(tool.providerKind)
+    ) {
+      throw new CompositionResolutionError(
+        context,
+        `tools[${idx}].providerKind must be one of ${Object.values(
+          ToolProviderKind,
+        ).join(', ')}`,
+      );
+    }
+    if (
+      typeof tool.resourceId !== 'string' ||
+      tool.resourceId.trim().length === 0
+    ) {
+      throw new CompositionResolutionError(
+        context,
+        `tools[${idx}].resourceId must be a non-empty string`,
+      );
+    }
+    if (tool.kind === 'provider') {
+      out.push({
+        kind: 'provider',
+        providerKind: tool.providerKind,
+        resourceId: tool.resourceId,
+      });
+    } else if (tool.kind === 'tool') {
+      if (
+        typeof tool.toolName !== 'string' ||
+        tool.toolName.trim().length === 0
+      ) {
+        throw new CompositionResolutionError(
+          context,
+          `tools[${idx}].toolName must be a non-empty string for kind='tool'`,
+        );
+      }
+      out.push({
+        kind: 'tool',
+        providerKind: tool.providerKind,
+        resourceId: tool.resourceId,
+        toolName: tool.toolName,
+      });
+    } else {
+      throw new CompositionResolutionError(
+        context,
+        `tools[${idx}].kind must be "provider" or "tool"`,
+      );
+    }
+  }
+  return out;
+}
+
+// ─── Tier-2: projection ───────────────────────────────────────────────────────
+
+/**
+ * Project a `ResolvedComposition` into a {@link RuntimeAgentConfig} — the
+ * runtime-facing shape a driver materializes the primary agent + delegates
+ * from. The single resolver every consumer shares.
+ *
+ * The optional `overlay` (a session/step-level {@link NodeOverlayFragment})
+ * applies ON TOP of the root node:
+ *   - `primaryInstructions` = appendInstructions(root instructions, overlay
+ *     instructions) — base root prompt fragment FIRST, then the overlay.
+ *   - `primaryModelOverride` = overlay.modelOverride ?? root.modelOverride —
+ *     the overlay wins; absent ⇒ root.
+ *   - `primaryPermission` = overlay.permission ?? root.permission — the
+ *     overlay wins; absent ⇒ root. Restrict-only semantics: the overlay only
+ *     narrows (it replaces the root's permission map wholesale here; per-key
+ *     deep-merge against the AGENT's authored permission happens in the
+ *     downstream materializer, not in this projection).
+ */
+export function projectCompositionToRuntimeConfig(
+  resolved: ResolvedComposition,
+  overlay?: NodeOverlayFragment,
+): RuntimeAgentConfig {
+  const root = resolved.root;
+  const compositionRef = `${resolved.slug}@${resolved.version}`;
+
+  const rootInstructions = normalizeInstructions(root.instructions);
+  const overlayInstructions = normalizeInstructions(overlay?.instructions);
+  // Layer the overlay fragment AFTER the root's own instructions fragment.
+  const primaryInstructions = appendInstructions(
+    rootInstructions ?? '',
+    overlayInstructions,
+  );
+
+  const rootModelOverride = projectModelOverride(
+    root.modelOverride,
+    compositionRef,
+  );
+  const overlayModelOverride = projectModelOverride(
+    overlay?.modelOverride,
+    `${compositionRef}#overlay`,
+  );
+
+  const rootPermission = normalizePermission(root.permission);
+  const overlayPermission = normalizePermission(overlay?.permission);
+
+  const flattened = flattenCompositionTree(root);
+
+  return {
+    compositionRef,
+    primaryAgentSlug: root.agent.slug,
+    primaryInstructions:
+      primaryInstructions.length > 0 ? primaryInstructions : null,
+    primaryPermission: overlayPermission ?? rootPermission,
+    primaryModelOverride: overlayModelOverride ?? rootModelOverride,
+    subAgentBindings: flattened.map((n) => ({ ...n })),
+    subAgentInstructionsBySlug: collectInstructionsBySlug(root),
+    subAgentPermissionBySlug: collectPermissionsBySlug(root),
+    subAgentModelOverridesBySlug: collectModelOverridesBySlug(root),
+    defaultSkillSlugs: collectSkills(root, { scope: 'root' }),
+    allSkillSlugs: collectSkills(root, { scope: 'tree' }),
+    defaultToolSelection: collectTools(root, { scope: 'root' }),
+  };
+}

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

@@ -31,7 +31,9 @@ import {
   ManifestSurface,
   OutputSurfaceKind,
   type AgentRunRole,
+  type ModelRef,
 } from '@xemahq/kernel-contracts/workflow';
+import type { PermissionMap } from '@xemahq/kernel-contracts/agent-permission';
 import {
   compileManifest,
   type CompiledWorkspaceManifest,
@@ -104,10 +106,23 @@ export interface CompositionMountLayoutInput {
 /**
  * A single manifest-declared sub-agent binding the composition resolved.
  * Mirrors the binding subset the manifest DSL's `ManifestSubAgent` needs.
+ *
+ * Carries the {@link NodeOverlayFragment} overlay trio (`modelOverride` /
+ * `instructions` / `permission`) so a resolved sub-agent's per-node
+ * specialization survives the manifest reconstruction. Without these the
+ * worker silently DROPPED a delegate's `modelOverride` (the root fix for the
+ * worker drift). All optional ⇒ backward-compatible with callers that only
+ * supply `slug` / `alias`.
  */
 export interface CompositionSubAgentBindingInput {
   readonly slug: string;
   readonly alias?: string;
+  /** Per-delegate model override — OVERRIDE on the referenced agent's model. */
+  readonly modelOverride?: ModelRef;
+  /** Per-delegate instructions — APPENDED to the referenced agent's prompt. */
+  readonly instructions?: string;
+  /** Per-delegate permission — RESTRICT-merged over the agent's permission. */
+  readonly permission?: PermissionMap;
 }
 
 /**
@@ -227,6 +242,20 @@ export function compileCompositionWorkspaceManifest(
     (binding) => ({
       slug: binding.slug,
       ...(binding.alias !== undefined ? { alias: binding.alias } : {}),
+      // Pass the overlay trio through to the manifest agent block so a
+      // resolved delegate's per-node `modelOverride` / `instructions` /
+      // `permission` are NOT dropped on reconstruction (the worker bug).
+      // `ManifestSubAgent.defaultModel` is the manifest DSL's name for the
+      // kernel `modelOverride` slot.
+      ...(binding.modelOverride !== undefined
+        ? { defaultModel: binding.modelOverride }
+        : {}),
+      ...(binding.instructions !== undefined
+        ? { instructions: binding.instructions }
+        : {}),
+      ...(binding.permission !== undefined
+        ? { permission: binding.permission }
+        : {}),
     }),
   );
 
@@ -309,7 +338,9 @@ function projectOutputSurface(
   return {
     kind: surface.kind as OutputSurfaceKind,
     ...(surface.port === undefined ? {} : { port: surface.port }),
-    ...(surface.healthPath === undefined ? {} : { healthPath: surface.healthPath }),
+    ...(surface.healthPath === undefined
+      ? {}
+      : { healthPath: surface.healthPath }),
     ...(surface.autoOpen === undefined ? {} : { autoOpen: surface.autoOpen }),
     ...(surface.mode === undefined ? {} : { mode: surface.mode }),
     ...(surface.root === undefined ? {} : { root: surface.root }),