@xemahq/kernel-contracts 0.3.5 → 0.3.6

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

@@ -13,9 +13,8 @@
 // the agent section of `WorkspaceManifest` into this primitive.
 // ═══════════════════════════════════════════════════════════════════════════
 
-import type { PermissionMap } from '../../agent-workspace';
 import type { ToolSelectionEntry } from '../../mcp-tool';
-import type { ModelRef } from '../../workflow';
+import type { NodeOverlayFragment } from '../../workflow';
 import type { SkillRef } from '../../skill';
 import type { CapabilityLayer } from './capability-layer';
 import type { CompositionWorkspace } from './composition-workspace';
@@ -100,7 +99,7 @@ export interface CompositionLimits {
  * `skills` / `tools` / `modelOverride` attach AT this node — they extend or
  * override what the referenced agent definition declares intrinsically.
  */
-export interface CompositionNode {
+export interface CompositionNode extends NodeOverlayFragment {
   /** The agent definition this node runs. */
   readonly agent: AgentRef;
   /** Optional alias when the same agent appears more than once in the tree. */
@@ -109,42 +108,10 @@ export interface CompositionNode {
   readonly skills: readonly SkillRef[];
   /** Tools attached at this node. */
   readonly tools: readonly ToolSelectionEntry[];
-  /**
-   * Optional model override for this node. When omitted the Model
-   * Resolution Matrix decides at the invocation boundary. Besides the
-   * concrete/strategy model choice, `ModelRef` carries the per-node
-   * `temperature` and (for `StrategyModelRef`) the `modelClass` — so a
-   * node specializes BOTH which model and how it samples here, without a
-   * dedicated parallel field. The bundle renderer reads
-   * `modelOverride.temperature` to stamp the agent's sampling temperature.
-   */
-  readonly modelOverride?: ModelRef;
-  /**
-   * Node-level instructions — a prompt fragment layered ONTO the referenced
-   * agent definition's intrinsic system prompt. This is the "instructions"
-   * lever that lets a handful of base agents (generic/coder/explorer/planner)
-   * be specialized per node without authoring a new agent definition.
-   *
-   * Composite ordering (resolver-enforced): `agentDefinition.systemPrompt`
-   * THEN these `instructions`. The platform `system-overlay.md` (AWP base +
-   * deliverable contract + authority) is injected LATER by the runtime — it
-   * is NOT part of this field. Absent/blank = the base prompt passes through
-   * unchanged (never an empty append).
-   */
-  readonly instructions?: string;
-  /**
-   * Node-level permission override — a partial `PermissionMap` deep-merged
-   * (per top-level key) OVER the referenced agent definition's authored
-   * `permission` block, BEFORE the system tiers are applied by
-   * `resolveAgentPermissions`. This is what lets a generic base agent
-   * (e.g. `planner`) be specialized into a read-only, no-network reviewer
-   * at a node — e.g. `{ edit: 'deny', webfetch: 'deny', task: { '*':
-   * 'deny', 'kb-researcher': 'allow' } }` — without authoring a new agent
-   * definition. A present key fully replaces the base agent's value for
-   * that key; absent keys fall through to the base. Omitted = the base
-   * agent's permissions pass through unchanged.
-   */
-  readonly permission?: PermissionMap;
+  // modelOverride / instructions / permission — the INVOCATION-overlay trio —
+  // are inherited from NodeOverlayFragment (single declaration site). They
+  // OVERRIDE the model, APPEND to the base prompt, and RESTRICT-merge the
+  // permission for this node only.
   /** Sub-agents — themselves fully-armed composition nodes (recursive). */
   readonly children: readonly CompositionNode[];
   /**
@@ -192,7 +159,7 @@ export interface Composition {
  * Distinct from `CompositionNode` (the AUTHORED form): a resolved node
  * has its agent reference fully version-pinned, never `latest`.
  */
-export interface ResolvedCompositionNode {
+export interface ResolvedCompositionNode extends NodeOverlayFragment {
   /** Fully version-pinned agent reference. */
   readonly agent: Required<AgentRef>;
   readonly alias?: string;
@@ -200,23 +167,10 @@ export interface ResolvedCompositionNode {
   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 node-level instructions, copied verbatim from the source
-   * `CompositionNode.instructions`. The composer/runtime layers this onto
-   * the referenced agent definition's `systemPrompt` (base prompt first,
-   * then instructions). Absent = no node-level override.
-   */
-  readonly instructions?: string;
-  /**
-   * Resolved node-level permission override, copied verbatim from the
-   * source `CompositionNode.permission`. The bundle renderer deep-merges
-   * it (per top-level key) over the referenced agent definition's authored
-   * permission before the system tiers run. Absent = no node-level
-   * permission override.
-   */
-  readonly permission?: PermissionMap;
+  // modelOverride / instructions / permission — inherited verbatim from the
+  // source node via NodeOverlayFragment (single declaration site). The
+  // composer layers instructions onto the base systemPrompt and deep-merges
+  // permission over the agent's authored permission before the system tiers.
   /** Resolved sub-agent nodes (recursive). */
   readonly children: readonly ResolvedCompositionNode[];
   /**

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

@@ -0,0 +1,75 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Invocation Overlay ──
+//
+// The INVOCATION-axis overlay: per-call shaping of a resolved agent that is
+// NEVER persisted into identity. ONE shared shape for both call sites —
+// a workflow step's `with:` block AND a session/thread override — so the
+// platform has a single overlay contract, not two divergent ones.
+//
+// Semantics (add-or-restrict ONLY — an overlay can extend context and NARROW
+// capability, but NEVER widen beyond the agent's own + org/project policy):
+//   - modelOverride : OVERRIDE   (inherited from NodeOverlayFragment)
+//   - instructions  : APPEND     (inherited; appended AFTER the resolved
+//                                 agent prompt — same field, same append
+//                                 semantics as a node; NO separate
+//                                 `instructionsAppend` name — one concept)
+//   - permission    : RESTRICT   (inherited; deep-merge, may only narrow)
+//   - tools         : ADD/REMOVE (still policy-checked at resolve time)
+//   - skills        : ADD-only   (identity skills are the floor)
+//
+// Agent SELECTION (which agent runs) is deliberately NOT part of this overlay:
+// in a workflow that is `agentSlug`/`agentRef`, and `compositionRef` selects a
+// workspace SOURCE, not the agent (see plan audit A5). The overlay only SHAPES
+// the already-selected agent.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ToolSelectionEntry } from '../../mcp-tool';
+import type { SkillRef } from '../../skill';
+import type { NodeOverlayFragment } from '../../workflow';
+
+/**
+ * Tools requested for this invocation. `add` requests extra tools, `remove`
+ * drops tools by ref. Both are still validated against the agent's resolved
+ * permission AND the step/session policy at resolve time — a request can
+ * never force-enable a tool the agent is not allowed to use (fail-fast).
+ */
+export interface InvocationToolOverlay {
+  readonly add?: readonly ToolSelectionEntry[];
+  /** Tool refs to drop for this invocation. */
+  readonly remove?: readonly string[];
+}
+
+/**
+ * Skills requested for this invocation. ADD-only: the resolved agent's own
+ * skills are the floor and cannot be removed by an overlay (they are
+ * governed, registered identity). Removal/disable is a separate, later
+ * governed capability — not part of the per-call overlay.
+ */
+export interface InvocationSkillOverlay {
+  readonly add?: readonly SkillRef[];
+}
+
+/**
+ * The canonical per-call overlay. Extends {@link NodeOverlayFragment}
+ * (model / instructions / permission) with tools + skills. Both the
+ * workflow-step overlay and the session overlay ARE this shape.
+ */
+export interface InvocationOverlay extends NodeOverlayFragment {
+  readonly tools?: InvocationToolOverlay;
+  readonly skills?: InvocationSkillOverlay;
+}
+
+/**
+ * A workflow step's typed `with:` overlay. Structurally an
+ * {@link InvocationOverlay}; named for the call site. The agent action
+ * manifest validates it via its `spec.inputs` JSON Schema (the existing
+ * fail-fast validation lane — NOT a new validation system).
+ */
+export type AgentStepWithOverlay = InvocationOverlay;
+
+/**
+ * A session/thread invocation overlay — the SAME shape as the workflow
+ * step overlay so sessions and workflows shape an agent identically
+ * (no second, looser session override surface).
+ */
+export type SessionInvocationOverlay = InvocationOverlay;

package/src/agent-permission/index.ts

@@ -0,0 +1,12 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent Permission Contracts — Barrel Export ──
+//
+// Kernel (Layer-0) leaf: the pure permission TYPES (PermissionMap,
+// PermissionRule, PermissionAction, PermissionKey, KNOWN_PERMISSION_KEYS).
+// Zero deps. Imported by `workflow`, `agent-workspace`, and any consumer
+// that needs the permission shape — breaks the prior workflow↔agent-workspace
+// cycle. The resolve LOGIC + system tiers live in
+// `agent-workspace/lib/agent-tool-defaults.ts`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/permission-map';

package/src/agent-permission/lib/permission-map.ts

@@ -0,0 +1,71 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Agent Permission types — single source of truth (Layer-0 leaf) ──
+//
+// The PURE permission TYPES, extracted to their own dependency-free subpath
+// so BOTH `workflow` (model-ref / compiled-workspace-manifest) and
+// `agent-workspace` (the resolve logic) can import them WITHOUT creating a
+// `workflow ↔ agent-workspace` import cycle. The merge logic + system tiers
+// (`resolveAgentPermissions`, `SYSTEM_*_PERMISSIONS`,
+// `assertNoRequiredPermissionsDenied`) stay in
+// `agent-workspace/lib/agent-tool-defaults.ts` and import these types.
+//
+// Mirrors OpenCode's unified `permission` surface (`packages/opencode/src/
+// config/permission.ts`).
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Permission keys that take a `Rule` shape — either a scalar action or
+ * a per-target map (e.g. `bash: { '*': 'allow', 'rm -rf *': 'deny' }`,
+ * `task: { 'html-builder': 'allow' }`, `external_directory: { '/**':
+ * 'allow' }`). Mirrors OpenCode's `permission.ts` `InputObject`.
+ */
+const KNOWN_RULE_PERMISSION_KEYS = [
+  'read',
+  'edit',
+  'glob',
+  'grep',
+  'list',
+  'bash',
+  'task',
+  'external_directory',
+  'lsp',
+  'skill',
+] as const;
+
+/**
+ * Permission keys that take a scalar `Action` only (no per-target map).
+ * Mirrors OpenCode's `permission.ts` `InputObject`.
+ */
+const KNOWN_ACTION_PERMISSION_KEYS = [
+  'todowrite',
+  'question',
+  'webfetch',
+  'websearch',
+  'doom_loop',
+] as const;
+
+export const KNOWN_PERMISSION_KEYS = [
+  ...KNOWN_RULE_PERMISSION_KEYS,
+  ...KNOWN_ACTION_PERMISSION_KEYS,
+] as const;
+
+export type PermissionKey = (typeof KNOWN_PERMISSION_KEYS)[number];
+
+export type PermissionAction = 'allow' | 'ask' | 'deny';
+
+/**
+ * A permission entry is either a scalar action or a per-target map. The
+ * map form is supported only for the keys in `KNOWN_RULE_PERMISSION_KEYS`
+ * — the action-only keys reject map shapes at the OpenCode schema layer.
+ * Catch-all entries (MCP tool names, biome-emitted globs) live alongside
+ * the closed set; their shape is validated by OpenCode at config load.
+ */
+export type PermissionRule = PermissionAction | Readonly<Record<string, PermissionAction>>;
+
+/**
+ * Full permission map. Closed-set keys carry typed rules; the index
+ * signature accommodates MCP tool names and biome-emitted glob patterns
+ * (e.g. `xema_*`, `emit*`) that OpenCode resolves via its catch-all
+ * `Schema.Record(Schema.String, Rule)` in `permission.ts`.
+ */
+export type PermissionMap = Readonly<Record<string, PermissionRule>>;

package/src/agent-workspace/lib/agent-tool-defaults.ts

@@ -29,62 +29,26 @@
 // pipelines, and authoring previews all merge through this function.
 // ═══════════════════════════════════════════════════════════════════════════
 
-/**
- * Permission keys that take a `Rule` shape — either a scalar action or
- * a per-target map (e.g. `bash: { '*': 'allow', 'rm -rf *': 'deny' }`,
- * `task: { 'html-builder': 'allow' }`, `external_directory: { '/**':
- * 'allow' }`). Mirrors OpenCode's `permission.ts` `InputObject`.
- */
-const KNOWN_RULE_PERMISSION_KEYS = [
-  'read',
-  'edit',
-  'glob',
-  'grep',
-  'list',
-  'bash',
-  'task',
-  'external_directory',
-  'lsp',
-  'skill',
-] as const;
-
-/**
- * Permission keys that take a scalar `Action` only (no per-target map).
- * Mirrors OpenCode's `permission.ts` `InputObject`.
- */
-const KNOWN_ACTION_PERMISSION_KEYS = [
-  'todowrite',
-  'question',
-  'webfetch',
-  'websearch',
-  'doom_loop',
-] as const;
-
-export const KNOWN_PERMISSION_KEYS = [
-  ...KNOWN_RULE_PERMISSION_KEYS,
-  ...KNOWN_ACTION_PERMISSION_KEYS,
-] as const;
-
-export type PermissionKey = (typeof KNOWN_PERMISSION_KEYS)[number];
-
-export type PermissionAction = 'allow' | 'ask' | 'deny';
-
-/**
- * A permission entry is either a scalar action or a per-target map. The
- * map form is supported only for the keys in `KNOWN_RULE_PERMISSION_KEYS`
- * — the action-only keys reject map shapes at the OpenCode schema layer.
- * Catch-all entries (MCP tool names, biome-emitted globs) live alongside
- * the closed set; their shape is validated by OpenCode at config load.
- */
-export type PermissionRule = PermissionAction | Readonly<Record<string, PermissionAction>>;
-
-/**
- * Full permission map. Closed-set keys carry typed rules; the index
- * signature accommodates MCP tool names and biome-emitted glob patterns
- * (e.g. `xema_*`, `emit*`) that OpenCode resolves via its catch-all
- * `Schema.Record(Schema.String, Rule)` in `permission.ts`.
- */
-export type PermissionMap = Readonly<Record<string, PermissionRule>>;
+// The pure permission TYPES now live in the dependency-free `agent-permission`
+// leaf subpath (breaking the prior workflow↔agent-workspace cycle). Import the
+// value (`KNOWN_PERMISSION_KEYS`) for the resolve logic below + the types, and
+// re-export all of them so the `agent-workspace` barrel surface stays stable
+// for every existing consumer.
+import { KNOWN_PERMISSION_KEYS } from '../../agent-permission';
+import type {
+  PermissionAction,
+  PermissionKey,
+  PermissionMap,
+  PermissionRule,
+} from '../../agent-permission';
+
+export {
+  KNOWN_PERMISSION_KEYS,
+  type PermissionAction,
+  type PermissionKey,
+  type PermissionMap,
+  type PermissionRule,
+} from '../../agent-permission';
 
 /**
  * Permissions every agent gets — manifests cannot deny them. Removing

package/src/reference-resolution/index.ts

@@ -0,0 +1,10 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Reference Resolution Contracts — Barrel Export ──
+//
+// Kernel (Layer-0) leaf: the shared graceful-degradation decision (DBM.1) used
+// by every resolver that walks a definition's declared references. Zero
+// cross-subpath deps so agent-composition / skill / capability / workflow /
+// action resolvers can all import it without a cycle.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/reference-resolution';

package/src/reference-resolution/lib/reference-resolution.ts

@@ -0,0 +1,175 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Reference Resolution — graceful-degradation decision (DBM.1) ──
+//
+// The ONE shared contract every resolver uses when it walks a definition's
+// declared references (an Agent node's `agentRef`, a skill's sub-skill, an
+// action's capability, a workflow's `uses:`) and asks "is this reference
+// available right now, and what do I do if it isn't?".
+//
+// It exists because of DYNAMIC BIOME MODULARITY: a definition authored while
+// biome X was installed keeps referencing X's contributions after X is
+// uninstalled/disabled. Today every resolver hard-fails uniformly
+// (AGENT_NOT_REGISTERED / MOUNT_SOURCE_NOT_FOUND aborts the whole run). The
+// shared policy below lets a reference be declared `optional` so its absence
+// degrades to a typed, observable skip instead of aborting — while the DEFAULT
+// stays fail-fast/fail-closed (no silent fallback).
+//
+// Modeled on `ResolvedModelDecision` (the Model Matrix's traced outcome): a
+// resolver returns one {@link ResolvedReferenceDecision} per reference, carrying
+// the outcome + a human-readable `reason` for the Studio debugger. Distinct
+// from model resolution on purpose — the Model Matrix always has a DEFAULT rule
+// so it can never be "unavailable"; references genuinely can.
+//
+// Pure Layer-0 leaf: zero cross-subpath imports so EVERY resolver
+// (agent-composition / skill / capability / workflow / action) can import it
+// without creating a cycle.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * How a resolver must treat a reference whose backing contribution is not
+ * currently available. Closed set; the DEFAULT is {@link Required}.
+ *
+ * This is the per-reference knob that makes biome add/remove non-breaking:
+ * authors mark the references they can live without as {@link Optional}; every
+ * other reference keeps the fail-fast contract.
+ */
+export enum MissingReferencePolicy {
+  /**
+   * Default. An unavailable reference is fatal — the resolver throws and the
+   * whole resolution/run fails fast. Never degrades silently.
+   */
+  Required = 'required',
+  /**
+   * An unavailable reference is skipped with a typed warning
+   * ({@link ReferenceResolutionState.OptionalSkipped}) and resolution
+   * continues without it. The only sanctioned degradation path.
+   */
+  Optional = 'optional',
+}
+
+/**
+ * The four — and only four — outcomes of resolving a single reference.
+ * Closed set; this is the "4-state ResolverDecision" of DBM.1.
+ */
+export enum ReferenceResolutionState {
+  /** Resolved to a live, available contribution. */
+  Present = 'present',
+  /**
+   * The reference is declared on the definition but its backing contribution
+   * is not currently available — typically because the owning biome was
+   * uninstalled or disabled. Fatal under {@link MissingReferencePolicy.Required};
+   * degrades to {@link OptionalSkipped} under {@link MissingReferencePolicy.Optional}.
+   */
+  DeclaredButUnavailable = 'declared-but-unavailable',
+  /**
+   * An {@link MissingReferencePolicy.Optional} reference that was
+   * {@link DeclaredButUnavailable} and was therefore skipped; resolution
+   * continued without it. This is the graceful-degradation terminal state.
+   */
+  OptionalSkipped = 'optional-skipped',
+  /**
+   * The reference resolves to a contribution the caller is NOT permitted to
+   * use (governance / scope / visibility denied it). Always fatal regardless
+   * of policy — fail-closed, never downgraded to a skip.
+   */
+  Denied = 'denied',
+}
+
+/**
+ * The closed set of reference KINDS a definition can declare and a resolver
+ * can resolve. Adding a new resolvable reference type = a one-line enum
+ * extension here.
+ */
+export enum ReferenceKind {
+  /** An Agent node's `agentRef` (a child agent / sub-agent). */
+  Agent = 'agent',
+  /** A skill bundle slug (intrinsic, node-attached, or a sub-skill). */
+  Skill = 'skill',
+  /** An MCP tool selection entry (`<provider>:<tool>@<v>`). */
+  Tool = 'tool',
+  /** A capability ref (`document:pdf-to-markdown@1`) reached via the router. */
+  Capability = 'capability',
+  /** A workflow action ref. */
+  Action = 'action',
+  /** A sub-workflow `uses:` ref. */
+  Workflow = 'workflow',
+}
+
+/**
+ * Declared-vs-enforced verification of a {@link ReferenceResolutionState.Present}
+ * reference — adopted from NemoClaw's verification model. Answers "the registry
+ * SAYS this exists, but is it actually reachable at the gateway/runtime?".
+ * Surfaced for diagnostics; it does NOT change fail-fast semantics (an
+ * unreachable-but-required reference still fails).
+ */
+export enum ReferenceVerification {
+  /** Declared in the registry AND confirmed reachable at the gateway/runtime. */
+  Verified = 'verified',
+  /** Declared in the registry but reachability at runtime is unconfirmed. */
+  RegistryOnly = 'registry-only',
+  /** Reachable at the gateway/runtime but with no registry declaration. */
+  GatewayOnly = 'gateway-only',
+  /** Neither declared nor reachable — pairs with {@link ReferenceResolutionState.DeclaredButUnavailable}. */
+  Unavailable = 'unavailable',
+}
+
+/**
+ * Owner attribution for a reference — which biome contributes it (NemoClaw's
+ * owner-attribution shape). The key signal behind a
+ * {@link ReferenceResolutionState.DeclaredButUnavailable} outcome: it names the
+ * biome whose install/enable would make the reference {@link ReferenceResolutionState.Present}
+ * again, so the UI can say "install biome X to restore `media:transcribe@1`".
+ *
+ * Both fields optional — System/kernel-shipped references have no owning biome.
+ */
+export interface ReferenceOwner {
+  /** The contributing biome's id; absent for System/kernel-shipped references. */
+  readonly biomeId?: string;
+  /** The contributing biome's version at resolution time, when known. */
+  readonly biomeVersion?: string;
+}
+
+/**
+ * The traced outcome of resolving ONE declared reference — the per-reference
+ * sibling of {@link ResolvedModelDecision}. A resolver emits one of these per
+ * reference it walks; the set is the audit trail the Studio debugger renders
+ * and the basis for any fail-fast throw.
+ */
+export interface ResolvedReferenceDecision {
+  /** What kind of reference this is. */
+  readonly kind: ReferenceKind;
+  /** The ref/slug exactly as authored on the definition. */
+  readonly ref: string;
+  /** The pinned version the definition requested, when it pinned one. */
+  readonly version?: string;
+  /** The policy that governed this reference (default {@link MissingReferencePolicy.Required}). */
+  readonly policy: MissingReferencePolicy;
+  /** The resolution outcome. */
+  readonly state: ReferenceResolutionState;
+  /** Declared-vs-enforced verification, when the resolver could determine it. */
+  readonly verification?: ReferenceVerification;
+  /** Which biome contributes the reference, for "install X to restore" UX. */
+  readonly owner?: ReferenceOwner;
+  /** Human-readable reason for the Studio debugger; mirrors `ResolvedModelDecision.reason`. */
+  readonly reason: string;
+}
+
+/**
+ * `true` when the decision must abort resolution fail-fast — every
+ * {@link ReferenceResolutionState.Denied}, plus any
+ * {@link ReferenceResolutionState.DeclaredButUnavailable} that was NOT marked
+ * {@link MissingReferencePolicy.Optional}. The single predicate every resolver
+ * checks so the fail-fast rule is implemented in exactly one place (no
+ * per-resolver re-derivation, no silent divergence).
+ */
+export function isFatalReferenceDecision(
+  decision: ResolvedReferenceDecision,
+): boolean {
+  if (decision.state === ReferenceResolutionState.Denied) {
+    return true;
+  }
+  if (decision.state === ReferenceResolutionState.DeclaredButUnavailable) {
+    return decision.policy !== MissingReferencePolicy.Optional;
+  }
+  return false;
+}

package/src/workflow/lib/compiled-workspace-manifest.ts

@@ -8,7 +8,7 @@
  * → workflow-contracts → workspace-manifest-dsl.
  */
 
-import type { PermissionMap } from '../../agent-workspace/lib/agent-tool-defaults';
+import type { PermissionMap } from '../../agent-permission';
 import type { ToolSelectionEntry } from '../../mcp-tool';
 
 import type { AgentRunRole } from './agent-role';