pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/role-catalog.js

@@ -0,0 +1,123 @@
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+const EVENT = "pi-herdr-subagents:roles:discover:v1";
+const SPAWNING = new Set(["subagent", "subagent_interrupt", "subagents_list", "subagent_resume", "subagent_cancel"]);
+const LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const config = () => process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+const fm = (s, k) => s.split("\n").find(x => x.startsWith(`${k}:`))?.slice(k.length + 1).trim() || undefined;
+function parse(s, fallback) { const m = s.match(/^---\n([\s\S]*?)\n---/); if (!m)
+    return null; const f = m[1], mode = fm(f, "session-mode"), prompt = fm(f, "system-prompt"), thinking = fm(f, "thinking"); const b = (k) => { const x = fm(f, k); return x == null ? undefined : x === "true"; }; return { name: fm(f, "name") ?? fallback, description: fm(f, "description"), model: fm(f, "model"), tools: fm(f, "tools"), skills: fm(f, "skills") ?? fm(f, "skill"), denyTools: fm(f, "deny-tools"), spawning: b("spawning"), allowSelfSpawn: b("allow-self-spawn"), autoExit: b("auto-exit"), interactive: b("interactive"), sessionMode: mode === "standalone" || mode === "lineage-only" || mode === "fork" ? mode : undefined, cwd: fm(f, "cwd"), body: s.replace(/^---\n[\s\S]*?\n---\n*/, "").trim() || undefined, systemPromptMode: prompt === "append" || prompt === "replace" ? prompt : undefined, thinking: LEVELS.has(thinking ?? "") ? thinking : undefined, disableModelInvocation: fm(f, "disable-model-invocation")?.toLowerCase() === "true" }; }
+function markdown(path) { const s = statSync(path); if (s.isFile())
+    return path.endsWith(".md") ? [path] : []; return s.isDirectory() ? readdirSync(path).filter(x => x.endsWith(".md")).sort().map(x => join(path, x)) : []; }
+function packageMeta(path) { let d = statSync(path).isDirectory() ? path : dirname(path); for (;;) {
+    const p = join(d, "package.json");
+    if (existsSync(p))
+        try {
+            const x = JSON.parse(readFileSync(p, "utf8"));
+            return { provider: typeof x.name === "string" ? x.name : undefined, providerVersion: typeof x.version === "string" ? x.version : undefined };
+        }
+        catch {
+            return {};
+        }
+    const parent = dirname(d);
+    if (parent === d)
+        return {};
+    d = parent;
+} }
+function legacy(content, name, path) { const m = content.match(/^---\n([\s\S]*?)\n---/), cli = m ? fm(m[1], "cli") : undefined; if (!cli)
+    return null; const n = fm(m[1], "name") ?? name; return { code: "external-cli-unsupported", message: `Role "${n}" requests external CLI "${cli}" in ${path}. pi-agent-replicate is Pi-only; remove the cli and cli-model fields and select Claude through an authenticated Pi provider/model ID.`, path, agentName: n }; }
+export function resolveDenyTools(agent) { const out = new Set(); if (!agent)
+    return out; if (agent.spawning === false)
+    for (const x of SPAWNING)
+        out.add(x); for (const x of (agent.denyTools ?? "").split(",").map(x => x.trim()).filter(Boolean))
+    out.add(x); return out; }
+export function effectiveRoleTools(requested, agent) { const allow = agent?.tools ? new Set(agent.tools.split(",").map(x => x.trim()).filter(Boolean)) : undefined; const deny = resolveDenyTools(agent); const out = [...new Set(requested)].filter(x => (!allow || allow.has(x)) && !deny.has(x)); if (!out.length)
+    throw new Error("effective child tool list is empty"); return out; }
+export function discoverAgentCatalog(pi) { const agents = new Map(), diagnostics = []; const add = (path, source) => { if (!existsSync(path))
+    return; for (const p of markdown(path)) {
+    const n = basename(p, ".md");
+    let c;
+    try {
+        c = readFileSync(p, "utf8");
+    }
+    catch (e) {
+        diagnostics.push({ code: "unreadable-role-definition", message: `Cannot read role definition ${p}: ${e instanceof Error ? e.message : String(e)}`, path: p, agentName: n });
+        continue;
+    }
+    const old = legacy(c, n, p);
+    if (old) {
+        diagnostics.push(old);
+        agents.delete(old.agentName ?? n);
+        continue;
+    }
+    const a = parse(c, n);
+    if (a)
+        agents.set(a.name, { ...a, source, path: p });
+} }; const paths = []; try {
+    pi?.events?.emit?.(EVENT, { apiVersion: 1, register(path) { if (typeof path !== "string" || !isAbsolute(path))
+            diagnostics.push({ code: "invalid-role-pack-path", message: "Role packs must register an absolute file or directory path." });
+        else
+            paths.push(resolve(path)); } });
+}
+catch (e) {
+    diagnostics.push({ code: "role-pack-discovery-failed", message: `Role-pack discovery failed: ${e instanceof Error ? e.message : String(e)}` });
+} const packs = new Map(); for (const p of new Set(paths)) {
+    if (!existsSync(p)) {
+        diagnostics.push({ code: "missing-role-pack-path", message: `Registered role-pack path does not exist: ${p}`, path: p });
+        continue;
+    }
+    let files, meta;
+    try {
+        if (statSync(p).isFile() && !p.endsWith(".md")) {
+            diagnostics.push({ code: "invalid-role-pack-file", message: `Registered role-pack file must use the .md extension: ${p}`, path: p });
+            continue;
+        }
+    }
+    catch { }
+    try {
+        files = markdown(p);
+        meta = packageMeta(p);
+    }
+    catch (e) {
+        diagnostics.push({ code: "unreadable-role-pack-path", message: `Cannot read registered role-pack path ${p}: ${e instanceof Error ? e.message : String(e)}`, path: p });
+        continue;
+    }
+    for (const f of files) {
+        const n = basename(f, ".md");
+        let c;
+        try {
+            c = readFileSync(f, "utf8");
+        }
+        catch (e) {
+            diagnostics.push({ code: "unreadable-role-definition", message: `Cannot read role definition ${f}: ${e instanceof Error ? e.message : String(e)}`, path: f, agentName: n, provider: meta.provider });
+            continue;
+        }
+        const old = legacy(c, n, f);
+        if (old) {
+            diagnostics.push({ ...old, provider: meta.provider });
+            continue;
+        }
+        const a = parse(c, n);
+        if (!a) {
+            diagnostics.push({ code: "invalid-role-definition", message: `Role definition must start with frontmatter: ${f}`, path: f, agentName: n, provider: meta.provider });
+            continue;
+        }
+        if (a.name !== n) {
+            diagnostics.push({ code: "role-name-mismatch", message: `Role name "${a.name}" must match filename "${n}" in ${f}`, path: f, agentName: n, provider: meta.provider });
+            continue;
+        }
+        if (!a.description) {
+            diagnostics.push({ code: "missing-role-description", message: `Role "${a.name}" must declare a description in ${f}`, path: f, agentName: a.name, provider: meta.provider });
+            continue;
+        }
+        packs.set(a.name, [...(packs.get(a.name) ?? []), { ...a, source: "package", path: f, ...meta }]);
+    }
+} for (const [n, defs] of packs) {
+    if (defs.length > 1) {
+        diagnostics.push({ code: "duplicate-package-role", message: `Role "${n}" is contributed by multiple role packs: ${defs.map(x => x.provider ?? x.path).sort().join(", ")}`, agentName: n });
+        continue;
+    }
+    agents.set(n, defs[0]);
+} add(join(config(), "agents"), "global"); add(join(process.cwd(), ".pi", "agents"), "project"); return { agents: [...agents.values()], diagnostics }; }
+export function resolveAgent(name, pi) { return discoverAgentCatalog(pi).agents.find(x => x.name === name); }

package/pi-extension/subagents/role-catalog.ts

@@ -0,0 +1,24 @@
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+
+export type AgentSource = "package" | "global" | "project";
+export type SessionMode = "standalone" | "lineage-only" | "fork";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface AgentDefinition { name:string; description?:string; model?:string; tools?:string; skills?:string; denyTools?:string; spawning?:boolean; allowSelfSpawn?:boolean; autoExit?:boolean; interactive?:boolean; thinking?:ThinkingLevel; sessionMode?:SessionMode; cwd?:string; body?:string; systemPromptMode?:"append"|"replace"; disableModelInvocation:boolean; }
+export interface ListedAgentDefinition extends AgentDefinition { source:AgentSource; path:string; provider?:string; providerVersion?:string; }
+export interface AgentDiagnostic { code:string; message:string; path?:string; agentName?:string; provider?:string; }
+export interface AgentCatalog { agents:ListedAgentDefinition[]; diagnostics:AgentDiagnostic[]; }
+const EVENT="pi-herdr-subagents:roles:discover:v1";
+const SPAWNING=new Set(["subagent","subagent_interrupt","subagents_list","subagent_resume","subagent_cancel"]);
+const LEVELS=new Set(["off","minimal","low","medium","high","xhigh","max"]);
+const config=()=>process.env.PI_CODING_AGENT_DIR??join(homedir(),".pi","agent");
+const fm=(s:string,k:string)=>s.split("\n").find(x=>x.startsWith(`${k}:`))?.slice(k.length+1).trim()||undefined;
+function parse(s:string,fallback:string):AgentDefinition|null { const m=s.match(/^---\n([\s\S]*?)\n---/); if(!m)return null; const f=m[1], mode=fm(f,"session-mode"), prompt=fm(f,"system-prompt"), thinking=fm(f,"thinking"); const b=(k:string)=>{const x=fm(f,k);return x==null?undefined:x==="true";}; return {name:fm(f,"name")??fallback,description:fm(f,"description"),model:fm(f,"model"),tools:fm(f,"tools"),skills:fm(f,"skills")??fm(f,"skill"),denyTools:fm(f,"deny-tools"),spawning:b("spawning"),allowSelfSpawn:b("allow-self-spawn"),autoExit:b("auto-exit"),interactive:b("interactive"),sessionMode:mode==="standalone"||mode==="lineage-only"||mode==="fork"?mode:undefined,cwd:fm(f,"cwd"),body:s.replace(/^---\n[\s\S]*?\n---\n*/,"").trim()||undefined,systemPromptMode:prompt==="append"||prompt==="replace"?prompt:undefined,thinking:LEVELS.has(thinking??"")?thinking as ThinkingLevel:undefined,disableModelInvocation:fm(f,"disable-model-invocation")?.toLowerCase()==="true"}; }
+function markdown(path:string):string[] { const s=statSync(path); if(s.isFile())return path.endsWith(".md")?[path]:[]; return s.isDirectory()?readdirSync(path).filter(x=>x.endsWith(".md")).sort().map(x=>join(path,x)):[]; }
+function packageMeta(path:string):{provider?:string;providerVersion?:string}{ let d=statSync(path).isDirectory()?path:dirname(path); for(;;){const p=join(d,"package.json");if(existsSync(p))try{const x=JSON.parse(readFileSync(p,"utf8"));return {provider:typeof x.name==="string"?x.name:undefined,providerVersion:typeof x.version==="string"?x.version:undefined};}catch{return {};}const parent=dirname(d);if(parent===d)return {};d=parent;} }
+function legacy(content:string,name:string,path:string):AgentDiagnostic|null { const m=content.match(/^---\n([\s\S]*?)\n---/),cli=m?fm(m[1],"cli"):undefined;if(!cli)return null;const n=fm(m![1],"name")??name;return {code:"external-cli-unsupported",message:`Role "${n}" requests external CLI "${cli}" in ${path}. pi-agent-replicate is Pi-only; remove the cli and cli-model fields and select Claude through an authenticated Pi provider/model ID.`,path,agentName:n}; }
+export function resolveDenyTools(agent:Pick<AgentDefinition,"spawning"|"denyTools">|null|undefined):Set<string>{const out=new Set<string>();if(!agent)return out;if(agent.spawning===false)for(const x of SPAWNING)out.add(x);for(const x of (agent.denyTools??"").split(",").map(x=>x.trim()).filter(Boolean))out.add(x);return out;}
+export function effectiveRoleTools(requested:readonly string[],agent:Pick<AgentDefinition,"spawning"|"tools"|"denyTools">|null|undefined):string[]{const allow=agent?.tools?new Set(agent.tools.split(",").map(x=>x.trim()).filter(Boolean)):undefined;const deny=resolveDenyTools(agent);const out=[...new Set(requested)].filter(x=>(!allow||allow.has(x))&&!deny.has(x));if(!out.length)throw new Error("effective child tool list is empty");return out;}
+export function discoverAgentCatalog(pi?:{events?:{emit?:(event:string,payload:unknown)=>void}}):AgentCatalog {const agents=new Map<string,ListedAgentDefinition>(),diagnostics:AgentDiagnostic[]=[];const add=(path:string,source:AgentSource)=>{if(!existsSync(path))return;for(const p of markdown(path)){const n=basename(p,".md");let c:string;try{c=readFileSync(p,"utf8");}catch(e){diagnostics.push({code:"unreadable-role-definition",message:`Cannot read role definition ${p}: ${e instanceof Error?e.message:String(e)}`,path:p,agentName:n});continue;}const old=legacy(c,n,p);if(old){diagnostics.push(old);agents.delete(old.agentName??n);continue;}const a=parse(c,n);if(a)agents.set(a.name,{...a,source,path:p});}};const paths:string[]=[];try{pi?.events?.emit?.(EVENT,{apiVersion:1,register(path:unknown){if(typeof path!=="string"||!isAbsolute(path))diagnostics.push({code:"invalid-role-pack-path",message:"Role packs must register an absolute file or directory path."});else paths.push(resolve(path));}});}catch(e){diagnostics.push({code:"role-pack-discovery-failed",message:`Role-pack discovery failed: ${e instanceof Error?e.message:String(e)}`});}const packs=new Map<string,ListedAgentDefinition[]>();for(const p of new Set(paths)){if(!existsSync(p)){diagnostics.push({code:"missing-role-pack-path",message:`Registered role-pack path does not exist: ${p}`,path:p});continue;}let files:string[],meta:ReturnType<typeof packageMeta>;try{if(statSync(p).isFile()&&!p.endsWith(".md")){diagnostics.push({code:"invalid-role-pack-file",message:`Registered role-pack file must use the .md extension: ${p}`,path:p});continue;}}catch{}try{files=markdown(p);meta=packageMeta(p);}catch(e){diagnostics.push({code:"unreadable-role-pack-path",message:`Cannot read registered role-pack path ${p}: ${e instanceof Error?e.message:String(e)}`,path:p});continue;}for(const f of files){const n=basename(f,".md");let c:string;try{c=readFileSync(f,"utf8");}catch(e){diagnostics.push({code:"unreadable-role-definition",message:`Cannot read role definition ${f}: ${e instanceof Error?e.message:String(e)}`,path:f,agentName:n,provider:meta.provider});continue;}const old=legacy(c,n,f);if(old){diagnostics.push({...old,provider:meta.provider});continue;}const a=parse(c,n);if(!a){diagnostics.push({code:"invalid-role-definition",message:`Role definition must start with frontmatter: ${f}`,path:f,agentName:n,provider:meta.provider});continue;}if(a.name!==n){diagnostics.push({code:"role-name-mismatch",message:`Role name "${a.name}" must match filename "${n}" in ${f}`,path:f,agentName:n,provider:meta.provider});continue;}if(!a.description){diagnostics.push({code:"missing-role-description",message:`Role "${a.name}" must declare a description in ${f}`,path:f,agentName:a.name,provider:meta.provider});continue;}packs.set(a.name,[...(packs.get(a.name)??[]),{...a,source:"package",path:f,...meta}]);}}for(const [n,defs] of packs){if(defs.length>1){diagnostics.push({code:"duplicate-package-role",message:`Role "${n}" is contributed by multiple role packs: ${defs.map(x=>x.provider??x.path).sort().join(", ")}`,agentName:n});continue;}agents.set(n,defs[0]);}add(join(config(),"agents"),"global");add(join(process.cwd(),".pi","agents"),"project");return {agents:[...agents.values()],diagnostics};}
+export function resolveAgent(name:string,pi?:{events?:{emit?:(event:string,payload:unknown)=>void}}){return discoverAgentCatalog(pi).agents.find(x=>x.name===name);}

package/pi-extension/subagents/runtime-routing.js

@@ -0,0 +1,154 @@
+import { clampThinkingLevel, getSupportedThinkingLevels, } from "@earendil-works/pi-ai";
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+export function isThinkingLevel(value) {
+    return THINKING_LEVELS.includes(value);
+}
+export class RuntimeResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RuntimeResolutionError";
+    }
+}
+export function parseExactModelRef(reference) {
+    const trimmed = reference.trim();
+    const separator = trimmed.indexOf("/");
+    if (separator <= 0 || separator === trimmed.length - 1)
+        return undefined;
+    const provider = trimmed.slice(0, separator).trim();
+    const modelId = trimmed.slice(separator + 1).trim();
+    return provider && modelId ? { provider, modelId } : undefined;
+}
+function toRoutingModel(value) {
+    if (!value || typeof value.provider !== "string" || typeof value.id !== "string") {
+        return undefined;
+    }
+    return {
+        provider: value.provider,
+        id: value.id,
+        reasoning: value.reasoning ?? false,
+        thinkingLevelMap: value.thinkingLevelMap,
+        input: Array.isArray(value.input) ? value.input : undefined,
+        contextWindow: typeof value.contextWindow === "number" ? value.contextWindow : undefined,
+        maxTokens: typeof value.maxTokens === "number" ? value.maxTokens : undefined,
+        cost: value.cost,
+    };
+}
+export function wrapPiModelRegistry(registry) {
+    return {
+        find(provider, modelId) {
+            return toRoutingModel(registry.find(provider, modelId));
+        },
+        available() {
+            const direct = registry.getAvailable?.() ?? [];
+            const source = direct.length > 0 ? direct : registry.getAll?.() ?? [];
+            const models = [];
+            const seen = new Set();
+            for (const raw of source) {
+                const candidate = toRoutingModel(raw);
+                if (!candidate)
+                    continue;
+                if (direct.length === 0 && registry.hasConfiguredAuth && !registry.hasConfiguredAuth(raw))
+                    continue;
+                const ref = `${candidate.provider}/${candidate.id}`;
+                if (seen.has(ref))
+                    continue;
+                seen.add(ref);
+                models.push(candidate);
+            }
+            return models;
+        },
+        hasConfiguredAuth(model) {
+            if (!registry.hasConfiguredAuth) {
+                return (registry.getAvailable?.() ?? []).some((candidate) => candidate.provider === model.provider && candidate.id === model.id);
+            }
+            const original = registry.find(model.provider, model.id);
+            return !!original && registry.hasConfiguredAuth(original);
+        },
+    };
+}
+function asPiModel(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        name: model.id,
+        api: "openai-completions",
+        baseUrl: "",
+        reasoning: model.reasoning,
+        thinkingLevelMap: model.thinkingLevelMap,
+        input: (model.input?.filter((entry) => entry === "text" || entry === "image") ?? ["text"]),
+        contextWindow: model.contextWindow ?? 0,
+        maxTokens: model.maxTokens ?? 0,
+        cost: {
+            input: model.cost?.input ?? 0,
+            output: model.cost?.output ?? 0,
+            cacheRead: model.cost?.cacheRead ?? 0,
+            cacheWrite: model.cost?.cacheWrite ?? 0,
+        },
+    };
+}
+function formatSupported(model) {
+    const levels = getSupportedThinkingLevels(asPiModel(model));
+    return levels.length > 0 ? levels.join(", ") : "(none)";
+}
+/** Resolve a subagent runtime from role frontmatter, then the parent runtime. */
+export function resolveRuntimePlan(role, parent, registry) {
+    let provider = parent.provider;
+    let modelId = parent.modelId;
+    let selectedModel = registry.find(provider, modelId);
+    const modelSource = role.model ? "agent" : "parent";
+    if (role.model) {
+        const parsed = parseExactModelRef(role.model);
+        if (!parsed || role.model !== `${parsed.provider}/${parsed.modelId}`) {
+            throw new RuntimeResolutionError(`role model ${JSON.stringify(role.model)} must be one exact authenticated provider/model-id`);
+        }
+        const found = registry.find(parsed.provider, parsed.modelId);
+        if (!found)
+            throw new RuntimeResolutionError(`unknown role model ${JSON.stringify(role.model)}`);
+        if (!registry.hasConfiguredAuth(found)) {
+            throw new RuntimeResolutionError(`role model ${JSON.stringify(role.model)} has no configured authentication`);
+        }
+        provider = found.provider;
+        modelId = found.id;
+        selectedModel = found;
+    }
+    const thinkingSource = role.thinking ? "agent" : "parent";
+    const preferredThinking = role.thinking ?? parent.thinking;
+    let thinking = preferredThinking;
+    let thinkingAdjustment;
+    if (role.thinking) {
+        if (!selectedModel) {
+            throw new RuntimeResolutionError("model capability information is unavailable; cannot validate role thinking");
+        }
+        const supported = getSupportedThinkingLevels(asPiModel(selectedModel));
+        if (!supported.includes(preferredThinking)) {
+            throw new RuntimeResolutionError(`role thinking ${JSON.stringify(preferredThinking)} is not supported by ${JSON.stringify(`${provider}/${modelId}`)}; supported: ${formatSupported(selectedModel)}`);
+        }
+    }
+    else if (selectedModel) {
+        thinking = clampThinkingLevel(asPiModel(selectedModel), preferredThinking);
+        if (thinking !== preferredThinking) {
+            thinkingAdjustment = {
+                from: preferredThinking,
+                to: thinking,
+                reason: selectedModel.reasoning ? "inherited-clamp" : "non-reasoning",
+            };
+        }
+    }
+    return {
+        provider,
+        modelId,
+        model: `${provider}/${modelId}`,
+        thinking,
+        modelSource,
+        thinkingSource,
+        ...(thinkingAdjustment ? { thinkingAdjustment } : {}),
+    };
+}

package/pi-extension/subagents/runtime-routing.ts

@@ -0,0 +1,239 @@
+import {
+  clampThinkingLevel,
+  getSupportedThinkingLevels,
+  type Model,
+  type ModelThinkingLevel,
+} from "@earendil-works/pi-ai";
+
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+export function isThinkingLevel(value: string): value is ThinkingLevel {
+  return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export type RuntimeSource = "agent" | "parent";
+
+export interface RoleRuntime {
+  model?: string;
+  thinking?: ThinkingLevel;
+}
+
+export interface ParentRuntime {
+  provider: string;
+  modelId: string;
+  thinking: ThinkingLevel;
+}
+
+export interface RoutingModel {
+  provider: string;
+  id: string;
+  reasoning: boolean;
+  thinkingLevelMap?: Model<any>["thinkingLevelMap"];
+  input?: string[];
+  contextWindow?: number;
+  maxTokens?: number;
+  cost?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+}
+
+export interface ModelRegistryAdapter {
+  find(provider: string, modelId: string): RoutingModel | undefined;
+  available(): RoutingModel[];
+  hasConfiguredAuth(model: { provider: string; id: string }): boolean;
+}
+
+export interface ResolvedRuntimePlan {
+  provider: string;
+  modelId: string;
+  model: string;
+  thinking: ThinkingLevel;
+  modelSource: RuntimeSource;
+  thinkingSource: RuntimeSource;
+  thinkingAdjustment?: {
+    from: ThinkingLevel;
+    to: ThinkingLevel;
+    reason: "non-reasoning" | "inherited-clamp";
+  };
+  observed?: {
+    model?: string;
+    thinking?: ThinkingLevel;
+  };
+  runtimeMismatch?: string;
+}
+
+export class RuntimeResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RuntimeResolutionError";
+  }
+}
+
+export function parseExactModelRef(
+  reference: string,
+): { provider: string; modelId: string } | undefined {
+  const trimmed = reference.trim();
+  const separator = trimmed.indexOf("/");
+  if (separator <= 0 || separator === trimmed.length - 1) return undefined;
+  const provider = trimmed.slice(0, separator).trim();
+  const modelId = trimmed.slice(separator + 1).trim();
+  return provider && modelId ? { provider, modelId } : undefined;
+}
+
+function toRoutingModel(value: any): RoutingModel | undefined {
+  if (!value || typeof value.provider !== "string" || typeof value.id !== "string") {
+    return undefined;
+  }
+  return {
+    provider: value.provider,
+    id: value.id,
+    reasoning: value.reasoning ?? false,
+    thinkingLevelMap: value.thinkingLevelMap,
+    input: Array.isArray(value.input) ? value.input : undefined,
+    contextWindow: typeof value.contextWindow === "number" ? value.contextWindow : undefined,
+    maxTokens: typeof value.maxTokens === "number" ? value.maxTokens : undefined,
+    cost: value.cost,
+  };
+}
+
+export function wrapPiModelRegistry(registry: {
+  find(provider: string, modelId: string): any;
+  getAvailable?: () => any[];
+  getAll?: () => any[];
+  hasConfiguredAuth?: (model: any) => boolean;
+}): ModelRegistryAdapter {
+  return {
+    find(provider, modelId) {
+      return toRoutingModel(registry.find(provider, modelId));
+    },
+    available() {
+      const direct = registry.getAvailable?.() ?? [];
+      const source = direct.length > 0 ? direct : registry.getAll?.() ?? [];
+      const models: RoutingModel[] = [];
+      const seen = new Set<string>();
+      for (const raw of source) {
+        const candidate = toRoutingModel(raw);
+        if (!candidate) continue;
+        if (direct.length === 0 && registry.hasConfiguredAuth && !registry.hasConfiguredAuth(raw)) continue;
+        const ref = `${candidate.provider}/${candidate.id}`;
+        if (seen.has(ref)) continue;
+        seen.add(ref);
+        models.push(candidate);
+      }
+      return models;
+    },
+    hasConfiguredAuth(model) {
+      if (!registry.hasConfiguredAuth) {
+        return (registry.getAvailable?.() ?? []).some(
+          (candidate) => candidate.provider === model.provider && candidate.id === model.id,
+        );
+      }
+      const original = registry.find(model.provider, model.id);
+      return !!original && registry.hasConfiguredAuth(original);
+    },
+  };
+}
+
+function asPiModel(model: RoutingModel): Model<any> {
+  return {
+    provider: model.provider,
+    id: model.id,
+    name: model.id,
+    api: "openai-completions",
+    baseUrl: "",
+    reasoning: model.reasoning,
+    thinkingLevelMap: model.thinkingLevelMap,
+    input: (model.input?.filter((entry): entry is "text" | "image" =>
+      entry === "text" || entry === "image") ?? ["text"]),
+    contextWindow: model.contextWindow ?? 0,
+    maxTokens: model.maxTokens ?? 0,
+    cost: {
+      input: model.cost?.input ?? 0,
+      output: model.cost?.output ?? 0,
+      cacheRead: model.cost?.cacheRead ?? 0,
+      cacheWrite: model.cost?.cacheWrite ?? 0,
+    },
+  };
+}
+
+function formatSupported(model: RoutingModel): string {
+  const levels = getSupportedThinkingLevels(asPiModel(model));
+  return levels.length > 0 ? levels.join(", ") : "(none)";
+}
+
+/** Resolve a subagent runtime from role frontmatter, then the parent runtime. */
+export function resolveRuntimePlan(
+  role: RoleRuntime,
+  parent: ParentRuntime,
+  registry: ModelRegistryAdapter,
+): ResolvedRuntimePlan {
+  let provider = parent.provider;
+  let modelId = parent.modelId;
+  let selectedModel = registry.find(provider, modelId);
+  const modelSource: RuntimeSource = role.model ? "agent" : "parent";
+
+  if (role.model) {
+    const parsed = parseExactModelRef(role.model);
+    if (!parsed || role.model !== `${parsed.provider}/${parsed.modelId}`) {
+      throw new RuntimeResolutionError(
+        `role model ${JSON.stringify(role.model)} must be one exact authenticated provider/model-id`,
+      );
+    }
+    const found = registry.find(parsed.provider, parsed.modelId);
+    if (!found) throw new RuntimeResolutionError(`unknown role model ${JSON.stringify(role.model)}`);
+    if (!registry.hasConfiguredAuth(found)) {
+      throw new RuntimeResolutionError(`role model ${JSON.stringify(role.model)} has no configured authentication`);
+    }
+    provider = found.provider;
+    modelId = found.id;
+    selectedModel = found;
+  }
+
+  const thinkingSource: RuntimeSource = role.thinking ? "agent" : "parent";
+  const preferredThinking = role.thinking ?? parent.thinking;
+  let thinking = preferredThinking;
+  let thinkingAdjustment: ResolvedRuntimePlan["thinkingAdjustment"];
+
+  if (role.thinking) {
+    if (!selectedModel) {
+      throw new RuntimeResolutionError("model capability information is unavailable; cannot validate role thinking");
+    }
+    const supported = getSupportedThinkingLevels(asPiModel(selectedModel));
+    if (!supported.includes(preferredThinking as ModelThinkingLevel)) {
+      throw new RuntimeResolutionError(
+        `role thinking ${JSON.stringify(preferredThinking)} is not supported by ${JSON.stringify(`${provider}/${modelId}`)}; supported: ${formatSupported(selectedModel)}`,
+      );
+    }
+  } else if (selectedModel) {
+    thinking = clampThinkingLevel(asPiModel(selectedModel), preferredThinking) as ThinkingLevel;
+    if (thinking !== preferredThinking) {
+      thinkingAdjustment = {
+        from: preferredThinking,
+        to: thinking,
+        reason: selectedModel.reasoning ? "inherited-clamp" : "non-reasoning",
+      };
+    }
+  }
+
+  return {
+    provider,
+    modelId,
+    model: `${provider}/${modelId}`,
+    thinking,
+    modelSource,
+    thinkingSource,
+    ...(thinkingAdjustment ? { thinkingAdjustment } : {}),
+  };
+}