@fro.bot/systematic 3.15.0 → 3.16.0

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[];