@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/core/index.ts

@@ -4,6 +4,18 @@
  * Durable Objects, Matrix, or Hono; the host (`src/do`, `src/shell`) supplies
  * those through the `AmbientServices` adapters and mounts `pluginRoutes`.
  */
+import {
+  DecisionProviderRegistry,
+  DecisionProviderRouter,
+  DecisionRuntime,
+  HOST_DECISION_PROVIDER_ID,
+  resolveDecisionAdapter,
+  type DecisionAdapter,
+  type DecisionEvaluator,
+  type DecisionProviderPolicy,
+  type DecisionProviderRegistration,
+  type WorkersAiBinding,
+} from '@ixo/common/ai/decisions';
 import { z } from 'zod';
 import type { OraclePlugin, PluginRoute } from '../plugin-api/oracle-plugin';
 import type {
@@ -14,8 +26,17 @@ import type {
   PluginContext,
 } from '../plugin-api/types';
 import { baseEnvSchema, composeEnvSchema, validateEnv } from './env';
-import { createLlmAdapter, type OpenRouterLlmAdapter } from './llm';
-import { validateManifest, type PluginManifestOverride } from './manifest';
+import {
+  createLlmAdapter,
+  openRouterAttributionHeaders,
+  type OpenRouterLlmAdapter,
+} from './llm';
+import {
+  estimateTokensApprox,
+  OPERATING_GUIDE_WARN_TOKENS,
+  validateManifest,
+  type PluginManifestOverride,
+} from './manifest';
 import {
   resolvePlugins,
   type ExcludedPlugin,
@@ -23,6 +44,10 @@ import {
   type SoftDepGap,
 } from './plugin-loader';
 import { createRegistries, type Registries } from './registries';
+import {
+  type DeliveryConfig,
+  deliveryConfigWithEnv,
+} from '../delivery/profile';
 import { buildPluginContext } from './runtime-context';
 import { NOOP_LOGGER } from './utils';
 
@@ -50,6 +75,7 @@ export type {
 
 export {
   ConfigSchemaRegistry,
+  DecisionRegistry,
   ManifestRegistry,
   MiddlewareRegistry,
   SharedStateRegistry,
@@ -61,6 +87,7 @@ export {
 export type {
   ManifestCrossCheckResult,
   RegisteredConfigSchema,
+  RegisteredDecision,
   RegisteredManifest,
   RegisteredMiddleware,
   RegisteredSharedAccessor,
@@ -70,8 +97,67 @@ export type {
   ToolSummary,
 } from './registries';
 
+export {
+  AmbiguousDecisionProviderError,
+  CloudflareJevDecisionAdapter,
+  DECISION_PROVIDERS,
+  DecisionNotApplicableError,
+  DecisionProviderNotFoundError,
+  DecisionProviderRegistry,
+  DecisionProviderRouter,
+  DecisionProviderUnavailableError,
+  DecisionRuntime,
+  HOST_DECISION_PROVIDER_ID,
+  JevDecisionError,
+  OpenRouterJevDecisionAdapter,
+  StaleDecisionSubjectError,
+  UNAVAILABLE_DECISION_EVALUATOR,
+  WorkersAiJevDecisionAdapter,
+  assertFinalDecisionSubjectUnchanged,
+  canonicalizeFinalDecisionSubject,
+  createDecisionAuthorityReceipt,
+  createDecisionExecutionReceipt,
+  decisionProviderEnvShape,
+  digestFinalDecisionSubject,
+  measureDecisionQuestionIsolation,
+  resolveDecisionAdapter,
+} from '@ixo/common/ai/decisions';
+export type {
+  CloudflareJevAdapterOptions,
+  DecisionAdapter,
+  DecisionApplicability,
+  DecisionAuthorityReceipt,
+  DecisionCalibrationProvenance,
+  DecisionEvaluator,
+  DecisionExecution,
+  DecisionExecutionReceipt,
+  DecisionJudgmentMethod,
+  DecisionJudgmentProvenance,
+  DecisionLookup,
+  DecisionProviderConfigIssue,
+  DecisionProviderName,
+  DecisionProviderPolicy,
+  DecisionProviderProvenance,
+  DecisionProviderRegistration,
+  DecisionProviderResolution,
+  DecisionProviderSelection,
+  DecisionQuestionIsolationObservation,
+  DecisionQuestionIsolationReport,
+  DecisionRuntimeLogger,
+  FinalDecisionSubject,
+  FinalDecisionSubjectBinding,
+  FinalDecisionSubjectValue,
+  JevProviderName,
+  OpenRouterJevAdapterOptions,
+  ResolveDecisionAdapterOptions,
+  ResolveDecisionAdapterResult,
+  WorkersAiBinding,
+  WorkersAiJevAdapterOptions,
+} from '@ixo/common/ai/decisions';
+
 export {
   estimateTokensApprox,
+  OPERATING_GUIDE_WARN_TOKENS,
   manifestCategorySchema,
   manifestExampleSchema,
   manifestStabilitySchema,
@@ -114,6 +200,7 @@ export {
   isAllowedModel,
   listModelCatalog,
   listModels,
+  openRouterAttributionHeaders,
 } from './llm';
 export {
   OPENROUTER_MODELS_URL,
@@ -146,9 +233,16 @@ export type {
 export {
   buildOracleSection,
   composePrompt,
+  formatDateContext,
   formatTimeContext,
   formatUserPreferences,
+  renderTurnTimeNote,
 } from './prompt-composer';
+export {
+  stripTurnTimeNote,
+  TURN_TIME_NOTE_KWARG,
+  withTurnTimeNote,
+} from './turn-time-note';
 export type {
   ComposePromptInput,
   MemoryCommunity,
@@ -163,6 +257,8 @@ export type { CompiledTemplate, TemplateValues } from './template';
 
 export * from './middlewares';
 
+export { createMemoryUserKv } from './user-kv';
+
 export {
   EMPTY_SHARED,
   EVENT_NAMES,
@@ -253,6 +349,26 @@ export interface RuntimeCoreOptions {
    * namespaces, …) are stripped from `validatedEnv`.
    */
   env: Record<string, unknown>;
+  /**
+   * Single host-supplied Decision adapter, registered as provider `host` and
+   * the default. Wins over the `DECISION_PROVIDER` env configuration, which
+   * is then neither checked nor registered. Mutually exclusive with
+   * `decisionProviders`.
+   */
+  decisionAdapter?: DecisionAdapter;
+  /**
+   * Host-configured Decision providers, registered beside the env-selected
+   * provider (`DECISION_PROVIDER`, registered under that value as its id).
+   * Ids must be unique across both.
+   */
+  decisionProviders?: readonly DecisionProviderRegistration[];
+  /**
+   * Default and per-Decision routes over the registered providers. Without a
+   * `defaultProviderId` the env-selected provider is the default. With
+   * several providers and neither a route nor a default for a Decision, its
+   * evaluation is refused with `AmbiguousDecisionProviderError`.
+   */
+  decisionProviderPolicy?: DecisionProviderPolicy;
   /** Boot + runtime logger. Defaults to a silent logger. */
   logger?: Logger;
 }
@@ -263,6 +379,8 @@ export interface RuntimeCoreOptions {
  */
 export interface RuntimeCore {
   identity: OracleIdentity;
+  /** `OracleConfig.delivery`: how chat surfaces receive replies. */
+  delivery: DeliveryConfig;
   registries: Registries;
   /** Names of the plugins that loaded, in dependency order. */
   availablePlugins: ReadonlySet<string>;
@@ -278,13 +396,20 @@ export interface RuntimeCore {
   authExcludedRoutes: AuthExcludedRoute[];
   /** OpenRouter-backed LLM adapter (`get(role, params?)`). */
   llm: OpenRouterLlmAdapter;
+  /**
+   * Bounded semantic Decision evaluator over the decision registry and the
+   * configured adapter — what `ctx.decisions` forwards to. Without a provider
+   * every call rejects with `DecisionProviderUnavailableError`.
+   */
+  decisions: DecisionEvaluator;
   logger: Logger;
   /** A boot-time `PluginContext` scoped to `pluginName` (default `__runtime__`). */
   buildCtx(pluginName?: string): PluginContext;
   /**
    * Warm the registries' boot caches (`getTools` / `getSubAgents` /
-   * `getMiddlewares`) and run the cross-plugin checks that need them: tool,
-   * sub-agent and shared-state name collisions (fatal), and every manifest's
+   * `getMiddlewares` / `getDecisions`) and run the cross-plugin checks that
+   * need them: tool, sub-agent, shared-state and decision name collisions
+   * (fatal), and every manifest's
    * `examples[].tool` references (advisory — logged). Memoised — safe to
    * await on every turn; the first agent build would otherwise perform the
    * collection lazily without the checks. Rejects with the boot error.
@@ -297,6 +422,19 @@ function reportBootError(logger: Logger, message: string, hint?: string): void {
   logger.error(`[boot-error] ${body}`);
 }
 
+/**
+ * The Workers AI binding (`env.AI`) is an object exposing `run`. Only its
+ * shape can be checked: bindings carry no brand the runtime could test for.
+ */
+function isWorkersAiBinding(value: unknown): value is WorkersAiBinding {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'run' in value &&
+    typeof value.run === 'function'
+  );
+}
+
 function validateConfig(config: OracleConfig): void {
   if (!config || typeof config !== 'object') {
     throw new Error('createRuntimeCore: `config` is required.');
@@ -354,6 +492,24 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
     for (const warning of result.warnings) logger.warn(`[boot] ${warning}`);
     if (!result.valid) manifestErrors.push(...result.errors);
   }
+  const guides = registries.manifests.operatingGuides();
+  if (guides.length > 0) {
+    logger.log(
+      `[boot] operating guides: ${guides
+        .map(
+          ({ pluginName, guide }) =>
+            `${pluginName}=${guide.length} chars (~${estimateTokensApprox(guide)} tokens)`,
+        )
+        .join(', ')}`,
+    );
+    for (const { pluginName, guide } of guides) {
+      const tokens = estimateTokensApprox(guide);
+      if (tokens > OPERATING_GUIDE_WARN_TOKENS)
+        logger.warn(
+          `[boot] operating guide of '${pluginName}' is ~${tokens} tokens (over ${OPERATING_GUIDE_WARN_TOKENS}); it is in the system prompt of every turn that has the plugin loaded`,
+        );
+    }
+  }
   if (manifestErrors.length > 0) {
     for (const err of manifestErrors) reportBootError(logger, err);
     throw new Error(
@@ -386,7 +542,81 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
     );
   }
 
-  // 4. Identity.
+  // 4. Decision providers — resolved here so a selected provider with missing
+  // credentials, or a policy naming an unknown provider, fails at boot rather
+  // than on the first evaluation. A single host adapter wins over env and
+  // skips the env check. The Workers AI binding is not a string, so Zod
+  // strips it from `validated.config`; it is read from the raw env.
+  if (opts.decisionAdapter && opts.decisionProviders !== undefined) {
+    const message =
+      'createRuntimeCore: decisionAdapter and decisionProviders are mutually exclusive.';
+    reportBootError(logger, message);
+    throw new Error(message);
+  }
+  const decisionRegistrations: DecisionProviderRegistration[] = [];
+  let defaultDecisionProviderId: string | undefined;
+  if (opts.decisionAdapter) {
+    decisionRegistrations.push({
+      id: HOST_DECISION_PROVIDER_ID,
+      adapter: opts.decisionAdapter,
+    });
+    defaultDecisionProviderId = HOST_DECISION_PROVIDER_ID;
+  } else {
+    const workersAi = opts.env.AI;
+    const resolvedAdapter = resolveDecisionAdapter(validated.config, {
+      ...(isWorkersAiBinding(workersAi) ? { workersAi } : {}),
+      openRouterHeaders: openRouterAttributionHeaders(
+        String(validated.config.ORACLE_NAME),
+      ),
+    });
+    if (!resolvedAdapter.ok) {
+      const lines: string[] = [];
+      for (const issue of resolvedAdapter.issues) {
+        const message = `Decision provider env validation failed for '${issue.field}': ${issue.message}`;
+        reportBootError(
+          logger,
+          message,
+          `Set '${issue.field}' on the Worker (wrangler secret / vars).`,
+        );
+        lines.push(message);
+      }
+      throw new Error(
+        `Env validation failed (${lines.length} issues):\n  - ${lines.join('\n  - ')}`,
+      );
+    }
+    if (resolvedAdapter.adapter) {
+      // `resolveDecisionAdapter` only builds an adapter for a set provider.
+      const envProviderId = String(validated.config.DECISION_PROVIDER);
+      decisionRegistrations.push({
+        id: envProviderId,
+        adapter: resolvedAdapter.adapter,
+      });
+      defaultDecisionProviderId = envProviderId;
+    }
+    decisionRegistrations.push(...(opts.decisionProviders ?? []));
+  }
+  let decisionProviders: DecisionProviderRouter;
+  try {
+    const policy = opts.decisionProviderPolicy;
+    const defaultProviderId =
+      policy?.defaultProviderId ?? defaultDecisionProviderId;
+    decisionProviders = new DecisionProviderRouter(
+      new DecisionProviderRegistry(decisionRegistrations),
+      {
+        ...(defaultProviderId !== undefined && { defaultProviderId }),
+        ...(policy?.routes !== undefined && { routes: policy.routes }),
+      },
+    );
+  } catch (err) {
+    reportBootError(
+      logger,
+      `Decision provider configuration is invalid: ${err instanceof Error ? err.message : String(err)}`,
+      'Check createOracleWorker({ decisionProviders, decisionProviderPolicy }) against DECISION_PROVIDER.',
+    );
+    throw err;
+  }
+
+  // 5. Identity.
   const oracleDid = String(validated.config.ORACLE_DID);
   const entityDid =
     typeof validated.config.ORACLE_ENTITY_DID === 'string' &&
@@ -401,14 +631,20 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
     prompt: opts.config.prompt ?? {},
   };
 
-  // 5. Registries.
+  // 6. Registries.
   for (const plugin of resolved.loaded) {
     registries.tools.register(plugin);
     registries.subAgents.register(plugin);
     registries.middlewares.register(plugin);
     registries.configSchema.register(plugin);
     registries.sharedState.register(plugin);
+    registries.decisions.register(plugin);
   }
+  const decisions: DecisionEvaluator = new DecisionRuntime(
+    registries.decisions,
+    decisionProviders,
+    logger,
+  );
 
   const availablePlugins: ReadonlySet<string> = loadedNames;
   const buildCtx = (pluginName = '__runtime__'): PluginContext =>
@@ -420,7 +656,7 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
       pluginName,
     });
 
-  // 6. Routes + auth exclusions (sync — plugins close over config here).
+  // 7. Routes + auth exclusions (sync — plugins close over config here).
   const pluginRoutes: PluginRoute[] = resolved.loaded.flatMap(
     (p) => p.getRoutes?.(buildCtx(p.name)) ?? [],
   );
@@ -428,7 +664,7 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
     (p) => p.getAuthExcludedRoutes?.() ?? [],
   );
 
-  // 7. LLM.
+  // 8. LLM.
   const llm = createLlmAdapter(
     {
       OPEN_ROUTER_API_KEY: String(validated.config.OPEN_ROUTER_API_KEY),
@@ -446,7 +682,7 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
     logger,
   );
 
-  // 8. Warm-up (memoised). Collision + manifest cross-checks need the boot
+  // 9. Warm-up (memoised). Collision + manifest cross-checks need the boot
   // caches, which may involve async `getTools`, so they cannot run here.
   let warmed: Promise<void> | null = null;
   const warm = (): Promise<void> => {
@@ -455,10 +691,12 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
       await registries.tools.collectBoot(ctx);
       registries.subAgents.collectBoot(ctx);
       registries.middlewares.collect(ctx);
+      registries.decisions.collect(ctx);
       try {
         registries.tools.assertNoCollisions();
         registries.subAgents.assertNoCollisions();
         registries.sharedState.assertNoCollisions();
+        registries.decisions.assertNoCollisions();
         // Advisory only: request-time tools (`getRequestTools`) are invisible
         // at boot, so an example that names one reads as "unknown" here. The
         // Node runtime does not run this check at boot at all; surfacing it
@@ -497,6 +735,12 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
 
   return {
     identity,
+    delivery: deliveryConfigWithEnv(
+      opts.config.delivery,
+      typeof validated.config.MATRIX_CHAT_DELIVERY === 'string'
+        ? validated.config.MATRIX_CHAT_DELIVERY
+        : undefined,
+    ),
     registries,
     availablePlugins,
     plugins: resolved.loaded,
@@ -506,8 +750,22 @@ export function createRuntimeCore(opts: RuntimeCoreOptions): RuntimeCore {
     pluginRoutes,
     authExcludedRoutes,
     llm,
+    decisions,
     logger,
     buildCtx,
     warm,
   };
 }
+export {
+  DEFAULT_TURN_LIMITS,
+  HarnessLimitError,
+  TurnBudget,
+  harnessLimitOf,
+  isHarnessLimitError,
+  turnLimitsFromEnv,
+} from './turn-budget';
+export type { TurnLimits, TurnUsage } from './turn-budget';
+export { budgetedLlm } from './budgeted-llm';
+export type { BudgetedLlm, BudgetedLlmOptions } from './budgeted-llm';
+export { ToolScheduler } from './tool-scheduler';
+export type { ToolLane, ToolSchedulerOptions } from './tool-scheduler';

package/src/core/llm.ts

@@ -82,7 +82,7 @@ export const TIER_DISPLAY: Record<
 export const MODEL_CATALOG: readonly ModelCatalogEntry[] = [
   // ── $ Everyday — fast and cheap ─────────────────────────────────────────
   {
-    id: DEFAULT_MODEL_ID,
+    id: 'openai/gpt-5.4-nano',
     label: 'GPT-5.4 Nano',
     family: 'openai',
     tier: 'everyday',
@@ -120,7 +120,7 @@ export const MODEL_CATALOG: readonly ModelCatalogEntry[] = [
 
   // ── $$ Balanced — smarter, still affordable ─────────────────────────────
   {
-    id: 'openai/gpt-5.6-luna',
+    id: DEFAULT_MODEL_ID,
     label: 'GPT-5.6 Luna',
     family: 'openai',
     tier: 'balanced',
@@ -239,7 +239,10 @@ export function getDefaultModelId(
   return override.length > 0 ? override : DEFAULT_MODEL_ID;
 }
 
-const MODEL_INPUT_CAPS: Record<string, ModelInputCapabilities> = {
+/** Native input capabilities per catalog id (every key is a `MODEL_CATALOG` id). */
+export const MODEL_INPUT_CAPS: Readonly<
+  Record<string, ModelInputCapabilities>
+> = {
   'openai/gpt-5.4-nano': {
     image: true,
     file: true,
@@ -396,12 +399,19 @@ export async function listModels(
         OPEN_ROUTER_API_KEY?: unknown;
       }
     | undefined,
+  options: {
+    /** Keeps a background price refresh alive past the response (`ctx.waitUntil`). */
+    waitUntil?: (work: Promise<unknown>) => void;
+  } = {},
 ): Promise<ModelListing> {
   const apiKey =
     typeof env?.OPEN_ROUTER_API_KEY === 'string' && env.OPEN_ROUTER_API_KEY
       ? env.OPEN_ROUTER_API_KEY
       : undefined;
-  const livePrices = await fetchOpenRouterPrices({ apiKey });
+  const livePrices = await fetchOpenRouterPrices({
+    apiKey,
+    ...(options.waitUntil ? { waitUntil: options.waitUntil } : {}),
+  });
   return listModelCatalog(env, livePrices);
 }
 
@@ -446,6 +456,20 @@ export const OPENROUTER_MAIN_FALLBACKS: readonly string[] = [
 
 export const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
 
+/**
+ * Attribution headers OpenRouter asks callers to send. Shared by the chat
+ * models and the `openrouter-jev` Decision adapter so every request the
+ * oracle makes is credited to the same app.
+ */
+export function openRouterAttributionHeaders(
+  oracleName?: string,
+): Record<string, string> {
+  return {
+    'HTTP-Referer': 'oracle-app.com',
+    'X-Title': oracleName ?? 'Oracle App',
+  };
+}
+
 // ── Nebius (self-hosted deployments) ────────────────────────────────────────
 
 export const NEBIUS_BASE_URL = 'https://api.tokenfactory.nebius.com/v1/';
@@ -561,10 +585,7 @@ export function createLlmAdapter(
   if (env.LLM_PROVIDER === 'nebius') return createNebiusAdapter(env, logger);
   const defaultModelId = getDefaultModelId(env);
   const mainEffort = env.MAIN_REASONING_EFFORT ?? 'medium';
-  const headers: Record<string, string> = {
-    'HTTP-Referer': 'oracle-app.com',
-    'X-Title': env.ORACLE_NAME ?? 'Oracle App',
-  };
+  const headers = openRouterAttributionHeaders(env.ORACLE_NAME);
 
   const modelForRole = (role: ModelRole): string => {
     if (role === 'main') return defaultModelId;
@@ -758,7 +779,7 @@ export interface ResolveLangsmithTracingArgs {
   /** The turn's user DID — from the authenticated payload, never client-set metadata. */
   userDid: string;
   /** Ingress surface, so latency can be sliced per client in LangSmith. */
-  client: 'portal' | 'matrix' | 'slack';
+  client: 'portal' | 'matrix' | 'slack' | 'channel';
   env: LangsmithTracingEnv;
 }
 

package/src/core/main-agent-types.ts

@@ -1,8 +1,10 @@
+import type { TaskExecutionProfile } from '../core/execution-profile';
 import type { ContextBudget } from './context-budget';
 import type { ContextGuardEvent } from './middlewares/context-guard';
 import type { ResultCapConfig } from './middlewares/result-cap';
 import type { ReadResultOutcome } from '../do/result-store';
 import type { AgentMiddleware } from 'langchain';
+import type { TurnBudget } from './turn-budget';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { BaseCheckpointSaver } from '@langchain/langgraph';
 import type { ReactAgent } from 'langchain';
@@ -12,7 +14,9 @@ import type {
   MergedConfig,
   ModelRole,
   OracleIdentity,
+  PluginTool,
 } from '../plugin-api/types';
+import type { DeliveryProfile } from '../delivery/types';
 import type { Registries } from './registries';
 import type { AmbientServices, RunConfigContext } from './runtime-context';
 import type { TMainAgentGraphState } from './state';
@@ -30,7 +34,7 @@ export const mainAgentRequestContextSchema = z.object({
   }),
   session: z.object({
     id: z.string(),
-    client: z.enum(['portal', 'matrix', 'slack']),
+    client: z.enum(['portal', 'matrix', 'slack', 'channel']),
     requestId: z.string(),
     wsId: z.string().optional(),
     roomId: z.string().optional(),
@@ -85,6 +89,14 @@ export interface MainAgentHooks {
    * write-ahead tool marks of durable runs and the result cap live here.
    */
   toolMiddlewares?: AgentMiddleware[];
+  /**
+   * The tool-execution middleware (budget, scheduling, write claims). It
+   * must see a tool's own thrown error, so on the main agent it is placed
+   * innermost — inside the retry middlewares, which turn a thrown error into
+   * an error ToolMessage — and each retry attempt passes through it. Every
+   * sub-agent gets it after `toolMiddlewares`.
+   */
+  toolExecution?: AgentMiddleware;
   /**
    * The turn's result cap (result-cap.ts), applied inside every wrapped
    * tool — plugin, meta and sub-agent inner tools — so a large result is
@@ -110,9 +122,16 @@ export interface MainAgentHooks {
     offset: number,
     length: number,
   ) => Promise<ReadResultOutcome>;
+  /**
+   * Tools the host binds for this turn only, outside every plugin and the
+   * capability gate (chat delivery's `create_artifact`). `returnDirect` ends
+   * the run once the tool has answered, without another model call.
+   */
+  turnTools?: Array<{ tool: PluginTool; returnDirect?: boolean }>;
 }
 
 export interface MainAgentArgs {
+  executionProfile?: TaskExecutionProfile;
   registries: MainAgentRegistries;
   identity: OracleIdentity;
   config: MergedConfig;
@@ -120,6 +139,12 @@ export interface MainAgentArgs {
   ambient: AmbientServices;
   state: Partial<TMainAgentGraphState>;
   availablePlugins: ReadonlySet<string>;
+  /**
+   * Plugins the capability router chose for this turn. The gate admits their
+   * tools and tool handlers see them as loaded, but they are never written
+   * to the graph's `loadedPlugins` channel: the preload lasts one turn.
+   */
+  preloadedPlugins?: ReadonlySet<string>;
   /**
    * Checkpointer for the user's thread state. On Workers the Durable Object
    * owns it (SQLite over DO storage) and passes it in per turn; omit for a
@@ -141,6 +166,19 @@ export interface MainAgentArgs {
    * size. Omitted → the legacy fixed thresholds (tests, stateless builds).
    */
   contextBudget?: ContextBudget;
+  /**
+   * The turn's resource budget (turn-budget.ts). Model calls are charged by
+   * the metered LLM adapter and tool calls by the host's tool-execution
+   * middleware; the build itself only uses it to skip a summary after the
+   * deadline. Omitted → unbudgeted (tests, stateless builds).
+   */
+  turnBudget?: TurnBudget;
+  /**
+   * Where the reply lands (chat delivery). A `chat` profile adds the surface
+   * section to the prompt; tools see it as `ctx.session.surface`. Omitted →
+   * a Portal turn.
+   */
+  delivery?: DeliveryProfile;
   hooks?: MainAgentHooks;
 }
 
@@ -160,6 +198,8 @@ export interface MainAgentBuildResult {
    * turn, `write` never does). Declared by the plugin, else by name.
    */
   toolEffects: Map<string, 'read' | 'write'>;
+  /** Names of the sub-agent dispatch tools (`call_*_agent`): scheduled in their own lane. */
+  subAgentToolNames: ReadonlySet<string>;
   /**
    * The request's `{ user, session }` channel. Tools already fall back to it,
    * but pass it as `context` in the `invoke` / `stream` config so LangChain