@fro.bot/systematic 3.15.1 → 3.16.0

package/dist/index.js

@@ -8,9 +8,10 @@ import {
   _enum,
   AgentOverlaySchema,
   CategoryOverlaySchema,
+  isRecord,
+  resolveRouting,
   loadConfig,
   loadConfigWithSources,
-  isRecord,
   isDiscoverableMarkdown,
   findAgentsInDir,
   extractAgentFrontmatter,
@@ -18,7 +19,7 @@ import {
   extractCommandFrontmatter,
   findSkillsInDir,
   discoverSkills
-} from "./index-7cyxcwf5.js";
+} from "./index-ae6mhwth.js";
 
 // src/index.ts
 import { createHash as createHash4 } from "crypto";
@@ -482,7 +483,7 @@ function loadSkillAsCommand(loaded) {
     config.subtask = loaded.subtask;
   return config;
 }
-function collectAgents(dir, disabledAgents, nativeAgents, overlays) {
+function collectAgents(dir, disabledAgents, nativeAgents, overlays, rawOverlays) {
   const agents = {};
   const agentList = findAgentsInDir(dir);
   const disabledSet = new Set(disabledAgents);
@@ -497,12 +498,16 @@ function collectAgents(dir, disabledAgents, nativeAgents, overlays) {
       continue;
     const config = loadAgentAsConfig(agentInfo);
     if (config) {
-      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays);
+      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays, rawOverlays);
     }
   }
   return agents;
 }
-function applyAgentOverlays(config, agentInfo, overlays) {
+var EMPTY_PI_SUBAGENTS_OVERLAYS = {
+  agents: {},
+  categories: {}
+};
+function applyAgentOverlays(config, agentInfo, overlays, rawOverlays) {
   const id = agentInfo.category ? `${agentInfo.category}/${agentInfo.name}` : agentInfo.name;
   const categoryOverlay = agentInfo.category ? overlays.categoriesByKey.get(agentInfo.category) : undefined;
   const exactOverlay = overlays.agentsByTargetId.get(id);
@@ -512,15 +517,40 @@ function applyAgentOverlays(config, agentInfo, overlays) {
   if (hasPermissionOverlay && isRecord(config.permission)) {
     addPermissionRules(permissionRules, config.permission);
   }
-  applyAgentOverlay(result, categoryOverlay?.value, permissionRules);
-  applyAgentOverlay(result, exactOverlay?.value, permissionRules);
+  const routing = resolveRouting({
+    overlays: rawOverlays,
+    piSubagentsOverlays: EMPTY_PI_SUBAGENTS_OVERLAYS,
+    target: { agentKey: agentInfo.name, category: agentInfo.category ?? "" },
+    harness: "opencode"
+  });
+  applyAgentOverlayPass(result, categoryOverlay?.value, permissionRules, routing, "category");
+  applyAgentOverlayPass(result, exactOverlay?.value, permissionRules, routing, "agent");
   applyPermissionOverlay(result, permissionRules, hasPermissionOverlay);
   return result;
 }
-function applyAgentOverlay(target, overlay, permissionRules) {
+function applyAgentOverlayPass(target, overlay, permissionRules, routing, level) {
+  if (routing.source.model?.level === level) {
+    applyRoutingModel(target, routing.model);
+  }
+  if (routing.source.qualifier?.level === level) {
+    target.variant = routing.qualifier;
+  }
   if (overlay === undefined)
     return;
-  applyOverlayObjectWithVariantClearing(target, overlay, permissionRules);
+  applyOverlayObjectFields(target, overlay);
+  if (isRecord(overlay.permission)) {
+    addPermissionRules(permissionRules, overlay.permission);
+  }
+  if (Array.isArray(overlay.skills)) {
+    addManagedSkillRules(permissionRules, overlay.skills);
+  }
+}
+function applyRoutingModel(target, model) {
+  if (model === null) {
+    delete target.model;
+  } else if (model !== undefined) {
+    target.model = model;
+  }
 }
 function applyPermissionOverlay(target, permissionRules, hasPermissionOverlay) {
   if (!hasPermissionOverlay)
@@ -536,8 +566,6 @@ function overlayControlsPermission(overlay) {
   return overlay !== undefined && (Object.hasOwn(overlay, "permission") || Object.hasOwn(overlay, "skills"));
 }
 var OVERLAY_ASSIGN_FIELDS = [
-  "model",
-  "variant",
   "temperature",
   "top_p",
   "mode",
@@ -545,27 +573,12 @@ var OVERLAY_ASSIGN_FIELDS = [
   "steps",
   "hidden"
 ];
-function applyOverlayObjectWithVariantClearing(target, overlay, permissionRules) {
-  const overlayHasModel = Object.hasOwn(overlay, "model");
-  const overlayHasVariant = Object.hasOwn(overlay, "variant");
-  if (overlayHasModel && !overlayHasVariant) {
-    delete target.variant;
-  }
+function applyOverlayObjectFields(target, overlay) {
   for (const field of OVERLAY_ASSIGN_FIELDS) {
     if (Object.hasOwn(overlay, field)) {
-      if (field === "model" && overlay[field] === null) {
-        delete target[field];
-      } else {
-        target[field] = overlay[field];
-      }
+      target[field] = overlay[field];
     }
   }
-  if (isRecord(overlay.permission)) {
-    addPermissionRules(permissionRules, overlay.permission);
-  }
-  if (Array.isArray(overlay.skills)) {
-    addManagedSkillRules(permissionRules, overlay.skills);
-  }
 }
 function createPermissionRuleAccumulator() {
   return new Map;
@@ -708,7 +721,7 @@ function createConfigHandler(deps) {
       enabledSkills: enabledSkillNames
     });
     const resolvedOverlays = resolveAgentOverlaySet(validatedOverlays);
-    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents, nativeAgents, resolvedOverlays);
+    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents, nativeAgents, resolvedOverlays, overlays);
     const bundledCommands = collectCommands(bundledCommandsDir, systematicConfig.disabled_commands);
     const discoveredSkillCommands = systematicConfig.skills_as_commands !== false ? collectDiscoveredSkillsAsCommands(directory, homeDir, opencodeConfigDir, opencodeConfigDirOverride, systematicConfig.disabled_commands) : {};
     const bundledAgentKeys = new Set(Object.keys(bundledAgents));

package/dist/lib/agent-resolver.d.ts

@@ -1,7 +1,7 @@
 /** Runtime persona catalog for `systematic_delegate`. Pi has no agent-discovery of its own, so category is dropped when flattening `agents/<category>/<name>.md` into this catalog. */
 /** A single resolved persona entry in the flattened catalog. */
 export interface AgentCatalogEntry {
-    /** Flat persona name (category dropped). */
+    /** Flat persona name (category dropped). Used for dispatch matching (`resolveAgent`); may differ from `key` if frontmatter `name` and the file stem diverge. */
     name: string;
     /** Human-readable description, used in tool description/parameter hints. */
     description: string;
@@ -9,6 +9,12 @@ export interface AgentCatalogEntry {
     body: string;
     /** Raw comma-separated `tools:` frontmatter value, if declared. Undefined = not declared. */
     toolsSource: string | undefined;
+    /** The agent's source file stem (filename without `.md`), used to key into `agents.<key>` overlays for routing (distinct from the display `name`). */
+    key: string;
+    /** The agent's category (source subdirectory name), used to key into `categories.<category>` overlays. `''` when the file has no category subdirectory -- the same no-category sentinel `config-handler.ts` and `pi-subagents-export.ts` use. */
+    category: string;
+    /** Qualified `category/key` id, mirroring `agent-overlays.ts`'s target-id convention, for callers that want a single stable identity. */
+    id: string;
 }
 /** Fails closed if the same persona name appears under more than one category. */
 export declare function buildAgentCatalog(agentsDir: string): AgentCatalogEntry[];

package/dist/lib/capability-snapshot.d.ts

@@ -3,7 +3,7 @@ declare const CAPABILITY_SNAPSHOT_COMMAND: 'systematic capabilities';
 declare const CAPABILITY_SOURCE_IDS: readonly ['config:custom', 'config:global', 'config:project', 'config:user', 'discovery:agents', 'discovery:skills', 'host:runtime', 'package'];
 declare const CONFIG_SOURCE_KINDS: readonly ['custom', 'project', 'user'];
 declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands', 'workflow_guard.debug', 'workflow_guard.mode'];
-declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant'];
+declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'profiles', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
 declare const CONFIG_SOURCE_ERROR_CODES: readonly ['parse-failed', 'read-failed', 'schema-invalid', 'source-invalid'];
 declare const CAPABILITY_SOURCE_PRESENCE: readonly ['absent', 'invalid', 'present'];
 declare const CAPABILITY_STATUSES: readonly ['available', 'unknown', 'unavailable'];

package/dist/lib/config-schema.d.ts

@@ -54,6 +54,22 @@ export declare const AgentOverlaySchema: z.ZodObject<{
         ask: "ask";
         deny: "deny";
     }>>]>>>;
+    opencode: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variant: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    pi: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        thinking: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const CategoryOverlaySchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -86,6 +102,52 @@ export declare const CategoryOverlaySchema: z.ZodObject<{
         ask: "ask";
         deny: "deny";
     }>>]>>>;
+    opencode: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variant: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    pi: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        thinking: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * Routing-only projection of the agent/category overlay fields, permitted
+ * inside a named `profiles` bundle. Deliberately excludes every non-routing
+ * field (`mode`, `color`, `steps`, `hidden`, `disable`, `skills`,
+ * `permission`) so a profile cannot smuggle in UI/execution/permission
+ * changes through the profile-selection mechanism — only the fields a
+ * profile exists to carry: model, variant/thinking, and sampling knobs.
+ */
+export declare const ProfileOverlaySchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variant: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    opencode: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variant: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    pi: z.ZodOptional<z.ZodObject<{
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        thinking: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            off: "off";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const PiSubagentsAgentOverlaySchema: z.ZodObject<{
     thinking: z.ZodOptional<z.ZodEnum<{
@@ -201,4 +263,4 @@ export declare function validateConfig(input: unknown): ValidationResult;
  *
  * Matches the hand-coded `SECURITY_OVERLAY_FIELDS` set in `src/lib/config.ts`.
  */
-export declare const SECURITY_OVERLAY_FIELDS: readonly ['model', 'variant', 'skills', 'permission'];
+export declare const SECURITY_OVERLAY_FIELDS: readonly ['model', 'variant', 'skills', 'permission', 'opencode', 'pi'];

package/dist/lib/config.d.ts

@@ -1,3 +1,4 @@
+import { type RoutingTarget } from './routing-resolver.js';
 export interface BootstrapConfig {
     enabled: boolean;
     file?: string;
@@ -19,7 +20,7 @@ export interface SourcedOverlayConfigMap {
     categories: Record<string, SourcedOverlayConfig>;
 }
 export declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands', 'workflow_guard.debug', 'workflow_guard.mode'];
-export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant'];
+export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'profiles', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
 export type ConfigSourceKind = 'custom' | 'project' | 'user';
 export type ConfigSourcePresence = 'absent' | 'invalid' | 'present';
 export type ConfigSourceErrorCode = 'parse-failed' | 'read-failed' | 'schema-invalid' | 'source-invalid';
@@ -39,15 +40,48 @@ export interface ConfigProtectedFieldMetadata {
     readonly outcome: 'blocked';
     readonly sourceKind: ConfigSourceKind;
 }
+/**
+ * The source kind that supplied the winning `profile` selector value, or
+ * `null` when no source set `profile` at all (case 1 of the selection table
+ * in plan 2026-09-04-002-feat-model-config-profiles, Unit 2). This names
+ * whichever source's value won the `custom ?? project ?? user` selector
+ * lookup -- including when that value turned out to name a missing bundle
+ * and the loader fell back to the user's own default (see
+ * {@link ConfigObservationMetadata.profileFallback}).
+ */
+export type ProfileSelectorSource = ConfigSourceKind | null;
+/**
+ * Present when the winning `profile` selector named a bundle absent from
+ * the user source's `profiles` map. `usedDefault` names the user's own
+ * default profile if it resolved instead, or `null` if the loader fell back
+ * to base configuration (no profile).
+ */
+export interface ProfileFallbackMetadata {
+    readonly requested: string;
+    readonly usedDefault: string | null;
+}
 export interface ConfigObservationMetadata {
     readonly authorities: readonly ConfigAuthorityMetadata[];
     readonly protectedFields: readonly ConfigProtectedFieldMetadata[];
     readonly sources: readonly ConfigSourceMetadata[];
+    /** The active profile's name, or `null` when base configuration is active. */
+    readonly activeProfile: string | null;
+    readonly profileSelectorSource: ProfileSelectorSource;
+    readonly profileFallback: ProfileFallbackMetadata | null;
 }
 export interface SourceAwareConfigResult {
     config: SystematicConfig;
     metadata: ConfigObservationMetadata;
     overlays: SourcedOverlayConfigMap;
+    /**
+     * Merged `pi_subagents.{agents,categories}` overlays (three-entry chain --
+     * user, project, custom; no profile pseudo-entry, see the merge-order
+     * comment in `loadConfigWithSources`). Exposed so a caller building a
+     * routing table (e.g. `systematic config show`) can pass the exact same
+     * legacy-`thinking`-fallback input `resolveRouting` uses internally for
+     * the post-merge qualifier check, without recomputing it.
+     */
+    piSubagentsOverlays: SourcedOverlayConfigMap;
 }
 export interface PiSubagentsOverlayMap {
     categories?: OverlayConfigMap;
@@ -95,6 +129,30 @@ export interface LoadConfigOptions {
 }
 export declare function loadConfig(projectDir: string, options?: LoadConfigOptions): SystematicConfig;
 export declare function loadConfigWithSources(projectDir: string, options?: LoadConfigOptions): SourceAwareConfigResult;
+/**
+ * Enumerate every routing-resolver target implied by the merged overlays:
+ * every raw agent-overlay key that resolves to a real bundled agent (bare or
+ * qualified `category/key`), plus every bundled agent whose category has a
+ * category overlay (R3b's "categories are not checked in isolation" --
+ * `categories.review.variant` with no category model is fine as long as
+ * every agent in `review` resolves its own model, so every agent in an
+ * overlaid category must be walked, not just the category itself).
+ *
+ * A raw overlay key that does not resolve to any known bundled agent (e.g.
+ * an unrestricted `profiles.<name>.agents.<key>` entry naming something that
+ * isn't a real bundled agent) is silently skipped here -- it is not a valid
+ * routing target and this check has no stronger claim to make about it than
+ * schema validation already does elsewhere.
+ *
+ * A disabled agent is excluded from the result: matched by bare key or
+ * qualified `category/key` id in `disabledAgents` (the merged
+ * `disabled_agents` list), or by its own effective overlay's
+ * `disable: true` (bare key checked before the qualified id, mirroring
+ * `config-handler.ts`'s `collectAgents`/`applyAgentOverlays` precedence).
+ * A disabled agent is never emitted to OpenCode at all, so it must never
+ * block config load over a routing invariant it can't violate in practice.
+ */
+export declare function collectRoutingTargets(overlays: SourcedOverlayConfigMap, disabledAgents?: ReadonlySet<string>): RoutingTarget[];
 interface ConfigPathOptions {
     readonly homeDir?: string;
     readonly userConfigDir?: string;

package/dist/lib/pi-delegate-session.d.ts

@@ -22,6 +22,8 @@ export declare function buildDelegateAgentSessionOptions(options: {
     cwd: string;
     agentDir: string;
     model: CreateAgentSessionOptions['model'];
+    /** Omitted (not `undefined`-valued) when unset, so the child inherits Pi's default thinking level instead of an explicit `undefined` overriding it. */
+    thinkingLevel?: CreateAgentSessionOptions['thinkingLevel'];
     allowedToolNames: string[];
     resourceLoader: ResourceLoader;
     sessionManager: ReturnType<typeof SessionManager.inMemory>;

package/dist/lib/pi-delegate-tool.d.ts

@@ -1,7 +1,8 @@
 /** Pi-specific adapter factory for the `systematic_delegate` tool. `noExtensions: true` is the structural depth-1 boundary; max turns is fixed at 20. */
-import type { ExtensionContext, ToolDefinition } from '@earendil-works/pi-coding-agent';
+import type { CreateAgentSessionOptions, ExtensionContext, ToolDefinition } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 import { type AgentCatalogEntry } from './agent-resolver.js';
+import type { PiSubagentsOverlayMap, SourcedOverlayConfigMap } from './config.js';
 /** Fixed, non-configurable delegation bounds (LOCKED). */
 export declare const MAX_DELEGATE_TURNS = 20;
 export declare const DELEGATE_TOOL_NAME = "systematic_delegate";
@@ -9,6 +10,16 @@ export declare const DELEGATE_EXECUTION_MODE: 'sequential';
 export type DelegateOutcome = 'completed' | 'turn_limit' | 'aborted' | 'failed';
 /** The parent session's model, narrowed to always-defined (validated before use). */
 export type DelegateParentModel = NonNullable<ExtensionContext['model']>;
+/**
+ * Derived from the pinned Pi SDK's own `CreateAgentSessionOptions` type
+ * (`'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'` as of
+ * @earendil-works/pi-coding-agent@0.83.0) rather than hand-declared, so a
+ * future SDK bump that changes the union surfaces as a type error here
+ * instead of silently drifting. Value-for-value identical to Systematic's
+ * own `piSubagentsThinkingSchema` enum in config-schema.ts today — see
+ * `isKnownThinkingLevel`'s runtime guard for the defence-in-depth check.
+ */
+export type DelegateThinkingLevel = NonNullable<CreateAgentSessionOptions['thinkingLevel']>;
 export interface DelegateToolDetails {
     persona: string;
     turnCount: number;
@@ -26,6 +37,8 @@ export interface DelegateSessionLike {
 export type CreateDelegateSession = (options: {
     agentName: string;
     model: DelegateParentModel;
+    /** Omitted for a config-neutral or thinking-neutral dispatch — the child then inherits Pi's default thinking level. Resolved from `pi.thinking` (or the legacy `pi_subagents.thinking`) the same way `model` is; the pinned Pi SDK's `CreateAgentSessionOptions.thinkingLevel` field is what makes this a real session option, not just an export-time one. */
+    thinkingLevel?: DelegateThinkingLevel;
     cwd: string;
     systemPromptOverride: string;
     allowedToolNames: string[];
@@ -33,6 +46,25 @@ export type CreateDelegateSession = (options: {
 export interface PiDelegateToolDeps {
     catalog: AgentCatalogEntry[];
     createDelegateSession: CreateDelegateSession;
+    /**
+     * Merged agent/category routing overlays from `loadConfigWithSources`'s
+     * `overlays` field. Omit for a config-neutral tool — routing then always
+     * inherits `ctx.model` (matches pre-Unit-5 behaviour).
+     */
+    overlays?: SourcedOverlayConfigMap;
+    /**
+     * The final config's merged `pi_subagents` map (`SystematicConfig.pi_subagents`,
+     * already project-stripped by the loader), for `resolveRouting`'s legacy
+     * `thinking` fallback (R5). Model resolution never reads this map.
+     */
+    piSubagentsOverlays?: PiSubagentsOverlayMap;
+    /**
+     * The active profile's name, from `ConfigObservationMetadata.activeProfile`.
+     * Echoed in the R4a routing notice so a user with multiple profiles can
+     * tell which one produced the model. `null`/omitted means no profile is
+     * active.
+     */
+    activeProfile?: string | null;
 }
 export declare function createPiDelegateTool(deps: PiDelegateToolDeps): ToolDefinition<ReturnType<typeof buildDelegateParametersSchema>, DelegateToolDetails>;
 declare function buildDelegateParametersSchema(catalog: AgentCatalogEntry[]): Type.TObject<{

package/dist/lib/routing-resolver.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Routing resolver: answers "what model and qualifier does target T get on
+ * harness H, and from where" from a set of already-merged config overlays.
+ *
+ * Part of the model-config-profiles feature (plan
+ * 2026-09-04-002-feat-model-config-profiles, Unit 3). One routing precedence,
+ * shared by every consumer that needs to know an agent's effective model:
+ * the OpenCode config hook, the Pi delegate tool, the Pi persona export, and
+ * `config show` (Units 4-6). This module is pure — it takes already-merged
+ * overlay data and returns a resolution; it never reads files, never throws,
+ * and never calls `console.warn`. The post-merge qualifier-requires-model
+ * invariant check and any warning emission live in the caller
+ * (`src/lib/config.ts`), which has the `warningSink` this module deliberately
+ * does not.
+ */
+import type { OverlayConfigMap, PiSubagentsOverlayMap, SourcedOverlayConfig, SourcedOverlayConfigMap } from './config.js';
+export type Harness = 'opencode' | 'pi';
+/**
+ * One resolution target: a bundled agent's bare file-stem key plus its
+ * category, keyed the same way `agent-overlays.ts` keys bundled agents
+ * (`resolveAgentOverlaySet`'s `agentsByTargetId` uses the qualified
+ * `category/key` id internally; this module accepts the split form since
+ * that's what a category-driven walk naturally produces).
+ */
+export interface RoutingTarget {
+    readonly agentKey: string;
+    readonly category: string;
+}
+/**
+ * Where a resolved `model` or qualifier value came from.
+ *
+ * `form` is `'legacy-pi-subagents'` only for a `pi` harness qualifier
+ * resolved from the deprecated `pi_subagents.<agents|categories>.<key>.thinking`
+ * location (R5) — `model` and `variant` never resolve from there.
+ */
+export interface RoutingFieldSource {
+    readonly level: 'agent' | 'category';
+    readonly form: 'block' | 'flat' | 'legacy-pi-subagents';
+}
+export interface RoutingResolution {
+    /**
+     * `undefined` when no layer set a model at all (inherit from the parent
+     * agent/session with no explicit source). `null` is itself a resolved
+     * value meaning "inherit", explicitly set by some layer — it is NOT the
+     * same as `undefined` and beats a lower layer's explicit model string,
+     * per R3a/the plan's KTD on `model: null` precedence.
+     */
+    readonly model: string | null | undefined;
+    /** `undefined` when no layer set a qualifier for this harness. */
+    readonly qualifier: string | undefined;
+    readonly source: {
+        readonly model: RoutingFieldSource | undefined;
+        readonly qualifier: RoutingFieldSource | undefined;
+    };
+    /**
+     * True when the deprecated `pi_subagents.<key>.thinking` value is present
+     * for this target (agent overlay checked before category, mirroring
+     * `pi-subagents-export.ts`'s existing precedence) — regardless of whether
+     * it actually won as `qualifier`'s source. Always `false` for the
+     * `opencode` harness.
+     *
+     * R5 requires one deprecation warning whenever the legacy field is
+     * present, even when a `pi.thinking` block is also set and wins (the user
+     * still has stale config to migrate away from). Callers should branch on
+     * this flag, not on `source.qualifier.form === 'legacy-pi-subagents'`, to
+     * decide whether to warn — the latter is `true` only when legacy actually
+     * supplied the resolved value.
+     */
+    readonly legacyPiSubagentsThinkingPresent: boolean;
+    /**
+     * Which harness this resolution was computed for. Carried on the result
+     * (not just the input) so `qualifierResolvesWithoutModel` can self-guard
+     * against ever flagging a Pi resolution as a violation, regardless of
+     * caller discipline — see that function's doc comment.
+     */
+    readonly harness: Harness;
+}
+export interface ResolveRoutingInput {
+    /** The `overlays` value `loadConfigWithSources` returns (agents/categories, already merged). */
+    readonly overlays: SourcedOverlayConfigMap;
+    /** The merged `pi_subagents` overlays, for the legacy `thinking` fallback. */
+    readonly piSubagentsOverlays: SourcedOverlayConfigMap;
+    readonly target: RoutingTarget;
+    readonly harness: Harness;
+}
+/**
+ * `loadConfigWithSources` exposes the merged `agents`/`categories` routing
+ * overlays in `SourcedOverlayConfigMap` form (value + source metadata), but
+ * some callers (the Pi delegate tool, Pi persona export) only have a plain,
+ * already-flattened overlay map on hand -- e.g. `SystematicConfig.pi_subagents`,
+ * which retains no per-value source metadata past its own merge.
+ * `resolveRouting`'s `piSubagentsOverlays` parameter only ever reads
+ * `.value` off each entry (see `getOverlayValue` above), so wrapping each
+ * plain value with placeholder source fields is a safe, purely-shape
+ * adapter for feeding the resolver -- it never changes what resolves.
+ * Exported so every consumer shares one implementation instead of each
+ * defining its own copy.
+ */
+export declare function toSourcedOverlayMap(map: OverlayConfigMap | undefined): Record<string, SourcedOverlayConfig>;
+/**
+ * Apply {@link toSourcedOverlayMap} to both halves of a plain
+ * `pi_subagents`-shaped map (`{agents, categories}`), producing a
+ * `SourcedOverlayConfigMap` ready to pass as `resolveRouting`'s
+ * `piSubagentsOverlays` argument.
+ */
+export declare function toSourcedPiSubagentsOverlays(map: PiSubagentsOverlayMap | undefined): SourcedOverlayConfigMap;
+/**
+ * Resolve the effective `{ model, qualifier, source }` for one target on one
+ * harness. Pure — same inputs always produce the same output; no I/O, no
+ * console output, no throwing.
+ */
+export declare function resolveRouting(input: ResolveRoutingInput): RoutingResolution;
+/**
+ * True when the OpenCode `variant` resolved but no model resolved at any
+ * layer (`model` is `undefined` — `null` counts as a resolved model meaning
+ * "inherit", so it does NOT trigger this). Used by the loader's post-merge
+ * check to raise a config error naming the target and harness (R3b).
+ *
+ * ALWAYS false for the `pi` harness: Pi's `thinking` qualifier is
+ * independent of `model` by design (see `resolveRouting`'s Pi branch) — it
+ * applies to whatever model the delegate ends up running, including one
+ * inherited from the parent session, so "thinking with no model anywhere"
+ * is a normal, valid configuration, not an error. This function self-guards
+ * on `resolution.harness` rather than relying on every caller to only ever
+ * invoke it for opencode resolutions.
+ */
+export declare function qualifierResolvesWithoutModel(resolution: RoutingResolution): boolean;
+/**
+ * Format the one-line deprecation message for a WRITTEN
+ * `pi_subagents.<scope>.<key>.thinking` field, naming the exact path the
+ * user wrote and the replacement path it should move to. `scope` is
+ * `'agents'` or `'categories'`, matching whichever map the field was
+ * actually written under -- a category-level write is never renamed to
+ * look like an agent-level path (or vice versa).
+ */
+export declare function formatWrittenLegacyPiSubagentsThinkingWarning(scope: 'agents' | 'categories', key: string): string;
+/**
+ * Collect one deprecation-warning message per WRITTEN
+ * `pi_subagents.<scope>.<key>.thinking` field found directly in the merged
+ * `pi_subagents` overlays -- NOT one per agent the field happens to
+ * resolve for. A category-level write (`pi_subagents.categories.<c>.thinking`)
+ * fans out to every bundled agent in that category when resolved through
+ * `resolveRouting` (by design -- that is how the legacy fallback applies),
+ * but the user only wrote ONE field, so they should see exactly ONE
+ * warning naming exactly the field they wrote, not N warnings each naming
+ * an agent-level path they never touched. The warning fires whenever the
+ * field is written, regardless of whether a higher-priority `pi.thinking`
+ * block ends up winning for any given agent -- a written legacy field is
+ * always deprecated, whether or not it is currently shadowed.
+ */
+export declare function collectWrittenLegacyPiSubagentsThinkingWarnings(piSubagentsOverlays: SourcedOverlayConfigMap): string[];