@xemahq/kernel-contracts 0.3.5 → 0.3.6

package/src/workflow/lib/model-ref.ts

@@ -22,7 +22,7 @@
 
 import { z } from 'zod';
 
-import type { PermissionMap } from '../../agent-workspace/lib/agent-tool-defaults';
+import type { PermissionMap } from '../../agent-permission';
 
 /**
  * LLM-routing tier. The SINGLE source of truth for the closed set
@@ -70,27 +70,68 @@ export enum ModelRefKind {
   STRATEGY = 'strategy',
 }
 
+/**
+ * Model generation / sampling options — the closed set of knobs an author
+ * MAY set on a model reference.
+ *
+ * **No platform-side defaults (hard rule).** Every field is optional and
+ * Xema injects NO default for any of them. An unset field is passed through
+ * as ABSENT so the engine/provider applies its own default — never
+ * materialise a value here, in a DTO, a Zod `.default()`, a seeder, or a
+ * `?? <n>` fallback. Forward a field to the provider only when it is
+ * explicitly defined (the `request.x !== undefined` pattern).
+ *
+ * Spread (via `extends`) by both {@link ConcreteModelRef} and
+ * {@link StrategyModelRef} so every override slot in the platform inherits
+ * new options for free — one fragment, no parallel field, no per-slot
+ * restatement (the `ModelRef` / `PermissionMap` reuse pattern).
+ */
+export interface ModelOptions {
+  /** Sampling temperature. Unset = engine default (NOT 0). */
+  readonly temperature?: number;
+  /** Nucleus sampling top-p. Unset = engine default. */
+  readonly topP?: number;
+  /** Max output tokens for the completion. Unset = engine default. */
+  readonly maxTokens?: number;
+  /** Stop sequences. Unset = engine default. */
+  readonly stop?: readonly string[];
+  /** Presence penalty. Unset = engine default. */
+  readonly presencePenalty?: number;
+  /** Frequency penalty. Unset = engine default. */
+  readonly frequencyPenalty?: number;
+  /**
+   * Reasoning effort, provider-specific (e.g. `low`/`medium`/`high`).
+   * Free-form string because the accepted set differs per provider.
+   * Unset = engine default.
+   */
+  readonly reasoningEffort?: string;
+  /** Extended-thinking token budget, provider-specific. Unset = engine default. */
+  readonly thinkingBudget?: number;
+}
+
 /**
  * Pin to a specific (modelId, providerSlug). The provider slug is
  * optional only when the modelId is globally unique across credentialed
  * providers for the org — when ambiguous, the resolver returns 400.
+ *
+ * Carries the optional {@link ModelOptions} sampling knobs (temperature,
+ * topP, maxTokens, …) — all pass-through-only, no platform default.
  */
-export interface ConcreteModelRef {
+export interface ConcreteModelRef extends ModelOptions {
   readonly kind: ModelRefKind.CONCRETE;
   readonly modelId: string;
   readonly providerSlug?: string;
-  readonly temperature?: number;
 }
 
 /**
  * Route through the existing `ModelStrategy` cascade for a given
  * `ModelClass`. The bound model can change without invalidating the
- * reference (lazy resolution).
+ * reference (lazy resolution). Carries the optional {@link ModelOptions}
+ * sampling knobs — all pass-through-only, no platform default.
  */
-export interface StrategyModelRef {
+export interface StrategyModelRef extends ModelOptions {
   readonly kind: ModelRefKind.STRATEGY;
   readonly modelClass: ModelClass;
-  readonly temperature?: number;
 }
 
 export type ModelRef = ConcreteModelRef | StrategyModelRef;
@@ -103,35 +144,47 @@ export function isStrategyModelRef(ref: ModelRef): ref is StrategyModelRef {
   return ref.kind === ModelRefKind.STRATEGY;
 }
 
+/**
+ * The INVOCATION-overlay fragment shared by EVERY "agent node" shape — the
+ * genuinely-identical trio that specializes a referenced agent WITHOUT
+ * authoring a new definition. Single declaration site (the
+ * `ModelRef`/`PermissionMap` reuse pattern): `CompositionNode`,
+ * `SubAgentBinding`, the compiled manifest agent block, and the typed
+ * workflow/session invocation overlays all `extends` this — the trio is
+ * never restated per shape.
+ *
+ * Identity floors always win (add-or-restrict, never widen):
+ *   - `modelOverride` — OVERRIDE: which model + how it samples
+ *     ({@link ModelOptions}). Resolver reads `modelOverride.temperature`
+ *     etc. to stamp sampling; omitted ⇒ the Model Resolution Matrix decides.
+ *   - `instructions`  — ADDITIVE: a prompt fragment layered AFTER the base
+ *     agent's `systemPrompt` (composite order: base prompt THEN this; the
+ *     platform `system-overlay.md` is injected LATER by the runtime).
+ *     Absent/blank ⇒ base prompt passes through unchanged (never an empty
+ *     append).
+ *   - `permission`    — RESTRICT-merge: a partial `PermissionMap`
+ *     deep-merged per top-level key OVER the base agent's authored
+ *     permission, BEFORE the system tiers run (`resolveAgentPermissions`).
+ *     A present key replaces the base's value for that key; absent keys
+ *     fall through. Omitted ⇒ base permissions unchanged. May only narrow.
+ */
+export interface NodeOverlayFragment {
+  readonly modelOverride?: ModelRef;
+  readonly instructions?: string;
+  readonly permission?: PermissionMap;
+}
+
 /**
  * A runtime attachment: "while this session/step runs, mount agent
- * `slug` as a delegate available to the primary, optionally with a
- * model override."
+ * `slug` as a delegate available to the primary, optionally specialized
+ * via the {@link NodeOverlayFragment} trio (model / instructions / permission)."
  *
  * Intrinsic delegates (those declared in the primary's own source
  * manifest under `permission.task.<slug>: allow`) are the floor — they
  * are always mounted and cannot be removed by any binding layer. A
- * binding on an intrinsic slug refines its model only.
+ * binding on an intrinsic slug refines its overlay only.
  */
-export interface SubAgentBinding {
+export interface SubAgentBinding extends NodeOverlayFragment {
   readonly slug: string;
   readonly alias?: string;
-  readonly modelOverride?: ModelRef;
-  /**
-   * Optional node-level instructions carried through from the authored
-   * manifest's `spec.agent.subAgents[].instructions` (WS5 Phase B). A prompt
-   * fragment the runtime layers ONTO the referenced base agent's intrinsic
-   * system prompt — the `base agent slug + instructions` lever. Absent = the
-   * base agent's prompt passes through unchanged.
-   */
-  readonly instructions?: string;
-  /**
-   * Optional node-level permission override carried through from
-   * `spec.agent.subAgents[].permission`. Deep-merged (per top-level key)
-   * over the referenced base agent's authored permission before the system
-   * tiers run — the lever that turns a generic base agent into a bounded
-   * delegate (read-only, scoped `task` allowlist) without a new definition.
-   * Absent = the base agent's permissions pass through unchanged.
-   */
-  readonly permission?: PermissionMap;
 }