ai-runtime-engine 2.9.0 → 3.0.1

package/dist/plugin/ai.js

@@ -71,8 +71,10 @@ export class AI {
         for (const providerCfg of this.config.providers) {
             if (providerCfg.kind === 'mock')
                 continue;
-            const provider = buildProvider(providerCfg, this.buildOpts);
-            this.registry.register(provider, providerCfg.enabled ?? true);
+            const enabled = providerCfg.enabled ?? true;
+            // A disabled provider never routes, so a zero-model config must not abort the whole runtime at load.
+            const provider = buildProvider(providerCfg, enabled ? this.buildOpts : { ...this.buildOpts, allowZeroModels: true });
+            this.registry.register(provider, enabled);
         }
     }
     /** Build an AI from a local config file/path or a remote http(s) URL. */
@@ -138,6 +140,19 @@ export class AI {
     telemetryEvents() {
         return this.telemetry.events?.() ?? [];
     }
+    /**
+     * Release AI-level resources. Today: flush any batching telemetry sink (e.g. OTLP) so a short-lived
+     * process does not drop events buffered below the batch threshold. Safe to call more than once, and a
+     * failing flush never throws (telemetry must not fail shutdown). Runtime.close() calls this.
+     */
+    async close() {
+        try {
+            await this.telemetry.flush?.();
+        }
+        catch {
+            /* a telemetry flush must never break shutdown */
+        }
+    }
     /** Run each provider's healthCheck(), seed the monitor, and return the statuses (for `doctor`). */
     async checkHealth() {
         const out = [];

package/dist/providers/estimate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Input-size estimation for routing, context-fit, and budget guardrails.
+ *
+ * This is a deterministic, conservative, LOCAL heuristic — it is deliberately NOT a reproduction of any
+ * provider's exact billing or tokenization. Its only guarantees are the ones the router needs:
+ *   - monotonic in payload size (a larger input never estimates fewer tokens),
+ *   - binary/multimodal parts contribute a nonzero estimate (an image is never "free"),
+ *   - text is counted exactly once (input.text and any `kind:'text'` parts, never double-counted).
+ *
+ * Text is ≈ chars/4 (the same ratio TokenEstimator uses; reimplemented here to avoid a providers→context
+ * dependency). Binary parts are sized from their decoded byte length at ~1 token per KiB with a 64-token
+ * floor per attachment, so a request with a large image cannot slip through context/budget checks as if
+ * it were empty. The floor and ratio are heuristic constants, not provider truth.
+ */
+import type { InputPart } from '../types.js';
+/** Tokens contributed by one input part. Text parts are chars/4; binary parts are bytes-derived. */
+export declare function estimatePartTokens(part: InputPart): number;
+/**
+ * Estimate the input token count of a request's `{ text, parts }`. Text from `input.text` and from any
+ * `kind:'text'` parts is summed and converted once; each binary part adds its own bytes-derived estimate.
+ */
+export declare function estimateInputTokens(input: {
+    text?: string;
+    parts?: InputPart[];
+}): number;

package/dist/providers/estimate.js

@@ -0,0 +1,55 @@
+/**
+ * Input-size estimation for routing, context-fit, and budget guardrails.
+ *
+ * This is a deterministic, conservative, LOCAL heuristic — it is deliberately NOT a reproduction of any
+ * provider's exact billing or tokenization. Its only guarantees are the ones the router needs:
+ *   - monotonic in payload size (a larger input never estimates fewer tokens),
+ *   - binary/multimodal parts contribute a nonzero estimate (an image is never "free"),
+ *   - text is counted exactly once (input.text and any `kind:'text'` parts, never double-counted).
+ *
+ * Text is ≈ chars/4 (the same ratio TokenEstimator uses; reimplemented here to avoid a providers→context
+ * dependency). Binary parts are sized from their decoded byte length at ~1 token per KiB with a 64-token
+ * floor per attachment, so a request with a large image cannot slip through context/budget checks as if
+ * it were empty. The floor and ratio are heuristic constants, not provider truth.
+ */
+const CHARS_PER_TOKEN = 4;
+const BYTES_PER_TOKEN = 1024;
+const MIN_PART_TOKENS = 64;
+/** Decoded byte length of a base64 string (ignoring padding), without allocating a Buffer. */
+function base64Bytes(data) {
+    if (!data)
+        return 0;
+    let len = data.length;
+    // Strip a possible data: URI prefix's base64 marker if present (defensive; `data` is base64 by convention).
+    const comma = data.indexOf(',');
+    if (data.startsWith('data:') && comma >= 0)
+        len = data.length - comma - 1;
+    let padding = 0;
+    if (len >= 1 && data.endsWith('='))
+        padding += 1;
+    if (len >= 2 && data.endsWith('=='))
+        padding += 1;
+    return Math.max(0, Math.floor((len * 3) / 4) - padding);
+}
+/** Tokens contributed by one input part. Text parts are chars/4; binary parts are bytes-derived. */
+export function estimatePartTokens(part) {
+    if (part.kind === 'text')
+        return Math.ceil(part.text.length / CHARS_PER_TOKEN);
+    const bytes = base64Bytes(part.data);
+    return Math.max(MIN_PART_TOKENS, Math.ceil(bytes / BYTES_PER_TOKEN));
+}
+/**
+ * Estimate the input token count of a request's `{ text, parts }`. Text from `input.text` and from any
+ * `kind:'text'` parts is summed and converted once; each binary part adds its own bytes-derived estimate.
+ */
+export function estimateInputTokens(input) {
+    let textChars = input.text?.length ?? 0;
+    let binaryTokens = 0;
+    for (const part of input.parts ?? []) {
+        if (part.kind === 'text')
+            textChars += part.text.length;
+        else
+            binaryTokens += estimatePartTokens(part);
+    }
+    return Math.ceil(textChars / CHARS_PER_TOKEN) + binaryTokens;
+}

package/dist/providers/factory.d.ts

@@ -14,5 +14,8 @@ export interface BuildOptions {
     fetchImpl?: FetchLike;
     clock?: Clock;
     env?: NodeJS.ProcessEnv;
+    /** Tolerate a zero-model result instead of throwing. Set only for providers that will not route (a
+     *  `enabled: false` provider), so a work-in-progress catalog-less block cannot abort runtime load. */
+    allowZeroModels?: boolean;
 }
 export declare function buildProvider(cfg: ProviderConfig, opts?: BuildOptions): AIProvider;

package/dist/providers/factory.js

@@ -28,11 +28,32 @@ export function buildProvider(cfg, opts = {}) {
     const credential = new Credential(apiKeyEnv, opts.env);
     const privacyClass = cfg.privacyClass ?? def.privacyClass;
     const wireShape = cfg.wireShape ?? def.wireShape;
-    const modelIds = Array.isArray(cfg.models) && cfg.models.length > 0
-        ? cfg.models
-        : cfg.defaultModel
-            ? [cfg.defaultModel]
-            : def.defaultModels;
+    // Resolve the model id list. `models: 'auto'` (and an omitted `models`) fall back to the caller's
+    // `defaultModel`, then to the kind's built-in catalog. An explicit `models: []` is an intentional
+    // "no models" statement and is treated as a config error, never a silent fallback.
+    let modelIds;
+    if (Array.isArray(cfg.models)) {
+        modelIds = cfg.models; // may be [] — caught by the zero-model guard below
+    }
+    else if (cfg.defaultModel) {
+        modelIds = [cfg.defaultModel];
+    }
+    else {
+        modelIds = def.defaultModels; // 'auto' or omitted → the kind's catalog (empty for openai-compatible/custom)
+    }
+    // Never silently register an ENABLED provider with zero routable models — that is a deterministic
+    // CONFIG problem (no model could be resolved), distinct from a provider being unavailable at runtime
+    // (health). A disabled provider (opts.allowZeroModels) is exempt: it will not route, so a missing model
+    // list must not abort construction of the whole runtime.
+    if (modelIds.length === 0 && !opts.allowZeroModels) {
+        const detail = Array.isArray(cfg.models)
+            ? 'an explicit empty models list'
+            : `'${cfg.kind}' has no built-in model catalog`;
+        const fix = Array.isArray(cfg.models)
+            ? 'remove the empty list or populate it (models: [...])'
+            : 'list models explicitly (models: [...]) or set defaultModel';
+        throw new AIError(`provider '${cfg.id}': no models resolved — ${detail}. ${fix}.`, { category: 'CONFIG' });
+    }
     const models = modelIds.map((id) => resolveModelMetadata(cfg.id, cfg.kind, id, cfg.capabilities));
     const config = {
         id: cfg.id,

package/dist/providers/httpClient.js

@@ -45,6 +45,10 @@ export async function callHttp(input) {
                 if (!retryable)
                     throw err;
                 lastError = err;
+                // No retry left ⇒ give up now; do not sleep out a backoff (up to 30s of Retry-After) before a
+                // failure that will happen regardless. Mirrors the network/timeout branch's last-attempt guard.
+                if (attempt > input.maxRetries)
+                    break;
                 const retryAfter = Number(res.headers.get('retry-after'));
                 await clock.sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter * 1000, 30_000) : attempt * 2000);
                 continue;

package/dist/providers/httpProvider.js

@@ -13,6 +13,7 @@ import { emptyProfile } from '../core/capabilities/evidence.js';
 import { extractJson } from '../util/extractJson.js';
 import { getWire } from './wire/registry.js';
 import { callHttp, callHttpStream } from './httpClient.js';
+import { estimateInputTokens } from './estimate.js';
 function originOf(url) {
     try {
         return new URL(url).origin;
@@ -44,7 +45,7 @@ export class HttpProvider {
             authMode: this.cfg.requiresKey === false ? 'none' : 'env',
             supportsModelListing: this.cfg.supportsModelListing ?? false,
             privacyClass: this.privacyClass,
-            models: this.cfg.models,
+            models: [...this.cfg.models], // defensive copy — never hand out the internal array by reference
             ...(this.cfg.defaultModel ? { defaultModel: this.cfg.defaultModel } : {}),
         };
     }
@@ -56,14 +57,14 @@ export class HttpProvider {
         return { providerId: this.id, state: 'AVAILABLE', routable: true, checkedAt: 0 };
     }
     async listModels() {
-        return this.cfg.models;
+        return [...this.cfg.models]; // defensive copy — a caller mutating the result must not corrupt config
     }
     async getCapabilities(model) {
         return this.cfg.models.find((m) => m.id === model)?.capabilities ?? emptyProfile();
     }
     async estimate(request) {
         const model = this.cfg.models.find((m) => m.id === request.model);
-        const inTokens = Math.ceil((request.input.text?.length ?? 0) / 4);
+        const inTokens = estimateInputTokens(request.input);
         const estimate = {
             providerId: this.id,
             model: request.model,

package/dist/providers/mock/mockProvider.js

@@ -5,6 +5,7 @@
  */
 import { AIError } from '../../core/fallback/errors.js';
 import { emptyProfile } from '../../core/capabilities/evidence.js';
+import { estimateInputTokens } from '../estimate.js';
 export class MockProvider {
     id;
     name;
@@ -31,7 +32,7 @@ export class MockProvider {
             authMode: 'none',
             supportsModelListing: true,
             privacyClass: this.privacyClass,
-            models: this.models,
+            models: [...this.models],
             ...(this.models[0] ? { defaultModel: this.models[0].id } : {}),
         };
     }
@@ -39,14 +40,14 @@ export class MockProvider {
         return { providerId: this.id, state: 'AVAILABLE', routable: true, checkedAt: 0 };
     }
     async listModels() {
-        return this.models;
+        return [...this.models];
     }
     async getCapabilities(model) {
         return this.models.find((m) => m.id === model)?.capabilities ?? emptyProfile();
     }
     async estimate(request) {
         const model = this.models.find((m) => m.id === request.model);
-        const inTokens = Math.ceil((request.input.text?.length ?? 0) / 4);
+        const inTokens = estimateInputTokens(request.input);
         const estimate = {
             providerId: this.id,
             model: request.model,

package/dist/runtime/config.d.ts

@@ -1,9 +1,10 @@
 /**
  * Runtime configuration loader. Canonical file: `.ai-runtime/config.yaml` (runtime settings + the
  * router config). WRAPS, never forks, the existing strict `parseConfig`: a small strict zod fragment
- * validates/plucks the runtime-level keys (runtime:, and learning/verification/budget/policy — which
- * the root schema rejects), then delegates the remainder to parseConfig so its strictness and
- * inline-secret rejection are preserved. Root `ai-runtime.yaml` remains a supported fallback.
+ * validates/plucks the purely runtime-level keys (runtime:, permissions:, routing:, mcp:), then delegates
+ * the remainder — including learning/verification/budget/policy, which became first-class RouterConfig
+ * keys on the root schema in 3.0.1 — to parseConfig so its strictness and inline-secret rejection are
+ * preserved. Root `ai-runtime.yaml` remains a supported fallback.
  *
  * NOTE: `src/config/load.ts` and `AI.load()` are intentionally untouched — the CLI's existing behavior
  * is frozen until Phase 2 migrates it.

package/dist/runtime/config.js

@@ -1,9 +1,10 @@
 /**
  * Runtime configuration loader. Canonical file: `.ai-runtime/config.yaml` (runtime settings + the
  * router config). WRAPS, never forks, the existing strict `parseConfig`: a small strict zod fragment
- * validates/plucks the runtime-level keys (runtime:, and learning/verification/budget/policy — which
- * the root schema rejects), then delegates the remainder to parseConfig so its strictness and
- * inline-secret rejection are preserved. Root `ai-runtime.yaml` remains a supported fallback.
+ * validates/plucks the purely runtime-level keys (runtime:, permissions:, routing:, mcp:), then delegates
+ * the remainder — including learning/verification/budget/policy, which became first-class RouterConfig
+ * keys on the root schema in 3.0.1 — to parseConfig so its strictness and inline-secret rejection are
+ * preserved. Root `ai-runtime.yaml` remains a supported fallback.
  *
  * NOTE: `src/config/load.ts` and `AI.load()` are intentionally untouched — the CLI's existing behavior
  * is frozen until Phase 2 migrates it.
@@ -17,8 +18,12 @@ import { parseConfig, STRATEGIES, KEY_LIKE } from '../config/schema.js';
 import { findConfigFile } from '../config/load.js';
 import { AIError } from '../core/fallback/errors.js';
 import { RUNTIME_MODES } from './types.js';
-/** Runtime-level keys that live in `.ai-runtime/config.yaml` but are NOT part of the strict root schema. */
-const RUNTIME_ONLY_KEYS = ['runtime', 'learning', 'verification', 'budget', 'policy', 'permissions', 'routing', 'mcp'];
+/**
+ * Runtime-level keys that live in `.ai-runtime/config.yaml` but are NOT part of the strict root schema.
+ * `learning`/`verification`/`budget`/`policy` moved to the root schema in 3.0.1 (they are RouterConfig
+ * fields), so they now flow through `parseConfig(rest)` directly instead of being folded back here.
+ */
+const RUNTIME_ONLY_KEYS = ['runtime', 'permissions', 'routing', 'mcp'];
 const capabilityRequirementShape = z.object({ group: z.enum(['input', 'output', 'intelligence', 'agent']), key: z.string().min(1), minEvidence: z.enum(['unsupported', 'unknown', 'inferred', 'documented', 'verified']).optional(), weight: z.number().optional() }).strict();
 const routingShape = z.object({ excludeProviders: z.array(z.string()).optional(), excludeModels: z.array(z.string()).optional(), preferProviders: z.array(z.string()).optional(), preferModels: z.array(z.string()).optional() }).strict();
 /**
@@ -40,13 +45,7 @@ const agentDefinition = z
     .strict();
 /** An agent definition id: the same prompt-safe shape an MCP server id must have. */
 const AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,32}$/;
-const runtimeSettings = z.object({ defaultMode: z.enum(RUNTIME_MODES).optional(), defaultStrategy: z.enum(STRATEGIES).optional(), context: z.object({ maxTokens: z.number().optional(), verifyLoss: z.boolean().optional(), summarize: z.boolean().optional() }).strict().optional(), skills: z.object({ paths: z.array(z.string()).optional(), packages: z.array(z.string()).optional(), autoload: z.boolean().optional() }).strict().optional(), embedding: z.object({ provider: z.enum(['local', 'openai-compatible']), baseUrl: z.string().optional(), apiKeyEnv: z.string().optional(), model: z.string().optional() }).strict().optional(), intent: z.object({ aiFallback: z.boolean().optional() }).strict().optional(), organization: z.string().optional(), storage: z.object({ encrypt: z.boolean(), keyEnv: z.string() }).strict().optional(), capabilities: z.object({ catalog: z.boolean().optional(), planning: z.boolean().optional(), aliases: z.record(z.string(), z.string()).optional(), pins: z.record(z.string(), z.string()).optional() }).strict().optional(), concurrency: z.object({ maxParallelSteps: z.number().optional(), perTool: z.record(z.string(), z.number()).optional(), perSkill: z.record(z.string(), z.number()).optional(), perProvider: z.record(z.string(), z.number()).optional(), perAgent: z.record(z.string(), z.number()).optional() }).strict().optional(), agents: z.object({ enabled: z.boolean().optional(), maxToolCalls: z.number().optional(), maxDurationMs: z.number().optional(), maxInnerCalls: z.number().optional(), definitions: z.record(z.string().regex(AGENT_ID_RE, 'an agent definition id must be lowercase kebab/snake (max 33 chars)'), agentDefinition).optional() }).strict().optional() }).strict();
-const learning = z.object({ enabled: z.boolean().optional() }).strict();
-const verification = z.object({ enabled: z.boolean().optional() }).strict();
-const budget = z.object({ maxCostUsd: z.number().optional(), maxCalls: z.number().optional() }).strict();
-const policy = z
-    .object({ allowProviders: z.array(z.string()).optional(), denyProviders: z.array(z.string()).optional(), requireLocal: z.boolean().optional(), maxCostUsd: z.number().optional(), strategy: z.enum(STRATEGIES).optional() })
-    .strict();
+const runtimeSettings = z.object({ defaultMode: z.enum(RUNTIME_MODES).optional(), defaultStrategy: z.enum(STRATEGIES).optional(), context: z.object({ maxTokens: z.number().optional(), verifyLoss: z.boolean().optional(), summarize: z.boolean().optional() }).strict().optional(), skills: z.object({ paths: z.array(z.string()).optional(), packages: z.array(z.string()).optional(), autoload: z.boolean().optional() }).strict().optional(), embedding: z.object({ provider: z.enum(['local', 'openai-compatible']), baseUrl: z.string().optional(), apiKeyEnv: z.string().optional(), model: z.string().optional() }).strict().optional(), intent: z.object({ aiFallback: z.boolean().optional() }).strict().optional(), organization: z.string().optional(), storage: z.object({ encrypt: z.boolean(), keyEnv: z.string() }).strict().optional(), capabilities: z.object({ catalog: z.boolean().optional(), planning: z.boolean().optional(), aliases: z.record(z.string(), z.string()).optional(), pins: z.record(z.string(), z.string()).optional() }).strict().optional(), concurrency: z.object({ maxParallelSteps: z.number().optional(), perTool: z.record(z.string(), z.number()).optional(), perSkill: z.record(z.string(), z.number()).optional(), perProvider: z.record(z.string(), z.number()).optional(), perAgent: z.record(z.string(), z.number()).optional() }).strict().optional(), agents: z.object({ enabled: z.boolean().optional(), decompose: z.boolean().optional(), maxToolCalls: z.number().optional(), maxDurationMs: z.number().optional(), maxInnerCalls: z.number().optional(), definitions: z.record(z.string().regex(AGENT_ID_RE, 'an agent definition id must be lowercase kebab/snake (max 33 chars)').refine((id) => !id.startsWith('auto_'), 'the `auto_` prefix is reserved for agents the runtime derives — pick another id'), agentDefinition).optional() }).strict().optional() }).strict();
 const permissions = z
     .object({ fsRead: z.boolean().optional(), fsWrite: z.boolean().optional(), shell: z.boolean().optional(), shellAllowedCommands: z.array(z.string()).optional(), gitWrite: z.boolean().optional(), gitCommit: z.boolean().optional(), gitPush: z.boolean().optional(), network: z.boolean().optional(), mcp: z.object({ servers: z.record(z.string(), z.union([z.enum(['off', 'read', 'full']), z.boolean()])).optional() }).strict().optional() })
     .strict();
@@ -77,7 +76,7 @@ const mcpServer = z
 });
 const mcp = z.object({ servers: z.record(z.string().regex(/^[a-z0-9][a-z0-9_-]{0,32}$/, 'an MCP server id must be lowercase kebab/snake (max 33 chars)'), mcpServer).optional() }).strict();
 const runtimeFragment = z
-    .object({ runtime: runtimeSettings.optional(), learning: learning.optional(), verification: verification.optional(), budget: budget.optional(), policy: policy.optional(), permissions: permissions.optional(), routing: routing.optional(), mcp: mcp.optional() })
+    .object({ runtime: runtimeSettings.optional(), permissions: permissions.optional(), routing: routing.optional(), mcp: mcp.optional() })
     .partial();
 /**
  * Parse a runtime config object (from `.ai-runtime/config.yaml` or a legacy root file). Runtime-level
@@ -94,20 +93,12 @@ export function parseRuntimeConfig(raw) {
         throw new AIError(`invalid ai-runtime config:\n${issues}`, { category: 'CONFIG' });
     }
     const frag = fragResult.data;
-    // Delegate the remainder (providers, strategy, weights, defaults, privacy, telemetry, tasks) to the strict router schema.
+    // Delegate the remainder to the strict router schema. This now includes learning/verification/budget/
+    // policy (root-schema keys since 3.0.1), so they land on the RouterConfig directly — no fold-back needed.
     const rest = omit(obj, RUNTIME_ONLY_KEYS);
     if (!('providers' in rest))
         rest.providers = [];
     const router = parseConfig(rest);
-    // Fold the runtime-only router keys back onto the RouterConfig (they exist on the type; resolveConfig reads them).
-    if (frag.learning)
-        router.learning = frag.learning;
-    if (frag.verification)
-        router.verification = frag.verification;
-    if (frag.budget)
-        router.budget = frag.budget;
-    if (frag.policy)
-        router.policy = frag.policy;
     // Top-level `routing:` is folded into the runtime settings (a runtime concern, resolved with env + per-run).
     const runtimeOut = { ...(frag.runtime ?? {}), ...(frag.routing ? { routing: frag.routing } : {}) };
     return { ...(Object.keys(runtimeOut).length ? { runtime: runtimeOut } : {}), ...(frag.permissions ? { permissions: frag.permissions } : {}), ...(frag.mcp ? { mcp: frag.mcp } : {}), router };

package/dist/runtime/events.d.ts

@@ -59,6 +59,12 @@ export type RuntimeEvent = {
     ts: number;
     runId: string;
     text: string;
+} | {
+    type: 'response.stream_abandoned';
+    ts: number;
+    runId: string;
+    providerId: string;
+    model: string;
 } | {
     type: 'agent.task.started';
     ts: number;

package/dist/runtime/runtime.d.ts

@@ -178,6 +178,15 @@ export declare class Runtime {
      * This run's agent envelopes. THE ONLY call site of `narrowEnvelope` — never re-derive an inner
      * catalog, a permission clamp, or a reservation anywhere else (see the header of agents/envelope.ts).
      */
+    /**
+     * Agents synthesized from the registry for this goal (Phase 3.7). Empty unless
+     * `runtime.agents.decompose` is on — so with the flag off nothing about planning changes.
+     *
+     * Deterministic and offline: no model call, no clock, no randomness. That is a requirement, not a
+     * preference — a derived definition is hashed into `agentDefHash`, and a resume that synthesized
+     * even slightly differently would discard every persisted inner plan as stale.
+     */
+    private derivedAgents;
     private agentEnvelopes;
     /** The MCP server manager: `list()`, `status(id)`, `test(id)`, `addServer`, `removeServer`, `setEnabled`. */
     mcp(): McpManager;
@@ -210,8 +219,9 @@ export declare class Runtime {
     /** Warnings from MCP wiring (id collisions) plus the manager's own (invalid store files, etc.). */
     mcpWarningsList(): string[];
     /**
-     * Release long-lived resources — today: MCP stdio child processes. A one-shot CLI command and the REPL
-     * both call this on completion/exit; without it a spawned server keeps the event loop alive.
+     * Release long-lived resources: MCP stdio child processes, and any batching telemetry sink (so a
+     * short-lived run does not drop OTLP events buffered below the batch threshold). A one-shot CLI command
+     * and the REPL both call this on completion/exit.
      */
     close(): Promise<void>;
     /** Skills whose required tools are all registered. */
@@ -299,9 +309,17 @@ export declare class Runtime {
      * skipped — no skill ran, so there is no success/failure to learn (recording them would teach noise). */
     private recordOrchestration;
     /**
-     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1, opt-in). Untrusted
-     * sources (anything not an in-tree builtin) have their descriptions fenced, and the block is bounded so
-     * a large catalog can never dominate the prompt.
+     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1; ON by default from
+     * 3.0.0 — set `runtime.capabilities.catalog: false` to remove it).
+     *
+     * The fence is real as of 3.0.0 and was not before: this block carries ids that come from MCP servers
+     * and third-party skills, and it renders them as trusted-looking prompt structure on every planning
+     * iteration of every run. Flattening (`promptSafe`) bounds their shape but says nothing about their
+     * provenance, so the whole block is wrapped as untrusted data. Three comments claimed "fenced" while
+     * no fence existed; shipping that ON by default would have made a false safety claim load-bearing.
+     *
+     * Both halves are bounded. The blocked-skill list had no cap at all — measured at ~24k characters
+     * with 300 blocked skills, silently, in every prompt.
      */
     private capabilityCatalogText;
     /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
@@ -373,6 +391,26 @@ export declare class Runtime {
      * an agent step would have failed every one of those steps.
      */
     private orchestrateRunners;
+    /**
+     * Reconcile findings that contradict each other, across ALL of this execution's agent tasks
+     * (Phase 3.7).
+     *
+     * `resolveConflicts` has existed since 3.4 with no caller, so two agents reaching opposite
+     * conclusions about the same subject both stayed `active` — and both were rendered into the next
+     * planning prompt, as if the runtime had no opinion about which was better supported. It does: it
+     * weighs evidence-based `confidence`, with `executionCoverage` only as a tiebreak.
+     *
+     * Runs at the ONE point new findings can appear — a task reaching a terminal state — and writes the
+     * outcome back onto the owning records, so a supersession survives a restart rather than being
+     * recomputed (and possibly recomputed differently) on every read.
+     *
+     * EVERY finding is passed in, not just the active ones. Resolving over the active subset makes the
+     * result depend on the order tasks happen to finish: a finding that beat a weak rival in wave 1 can
+     * itself lose in wave 2, and the wave-1 loser is then left pointing at a superseded finding — a
+     * broken chain nothing heals. Re-resolving the whole set each round is order-independent and gives
+     * the same answer as one pass over the final set.
+     */
+    private resolveFindingConflicts;
     /**
      * A bounded, fenced brief of what the agents have already established (Phase 3.5).
      *