@fro.bot/systematic 3.15.1 → 3.16.1

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