pi-pstack-native 0.0.0-stage → 1.0.0

package/dist/loop/scheduler.js

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { loadConfig } from "../runtime/config.js";
+import { lockPath } from "../runtime/home.js";
+import { FileLock } from "../runtime/lock.js";
+import { createLoop, loadLoops, updateLoops } from "./store.js";
+const MAX_TIMER = 2_147_000_000;
+const DEFAULT_RETRY_BASE_MS = 250;
+const DEFAULT_RETRY_MAX_MS = 5_000;
+function executionLockName(loop) {
+    const key = createHash("sha256").update(`${loop.sessionId}\0${loop.id}`).digest("hex");
+    return `loop-run-${key}`;
+}
+class LoopExecutionBusyError extends Error {
+    constructor(loopId) {
+        super(`scheduled loop ${loopId} is already running in another Pi process`);
+        this.name = "LoopExecutionBusyError";
+    }
+}
+/**
+ * Schedules durable loop occurrences. The state file lock makes claiming one
+ * occurrence atomic across cooperating Pi processes. Claiming advances
+ * nextRunAt before the external send, so delivery is at-most-once per claimed
+ * occurrence, not exactly-once: a host crash between claim and send can lose
+ * that delivery. A failed store lock does not claim or advance anything.
+ */
+export class LoopScheduler {
+    timer;
+    ctx;
+    pi;
+    retryBaseMs;
+    retryMaxMs;
+    logger;
+    generation = 0;
+    retryAttempt = 0;
+    tickRunning = false;
+    pendingRetryDelay;
+    refreshAfterTick = false;
+    constructor(pi, options = {}) {
+        this.pi = pi;
+        this.retryBaseMs = Math.max(1, options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS);
+        this.retryMaxMs = Math.max(this.retryBaseMs, options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS);
+        this.logger = options.logger ?? ((message, error) => console.error(message, error));
+    }
+    /** Start scheduling for a Pi session. Calling bind again replaces its timer. */
+    bind(ctx) {
+        this.stop();
+        this.ctx = ctx;
+        const generation = this.generation;
+        try {
+            const catchUpCompleted = this.catchUp();
+            if (!catchUpCompleted)
+                return;
+            this.retryAttempt = 0;
+            this.arm(generation);
+        }
+        catch (error) {
+            this.report("pstack-native loop catch-up failed; retrying", error);
+            this.scheduleRetry(generation);
+        }
+    }
+    /** Alias for callers that use explicit start/stop lifecycle naming. */
+    start(ctx) { this.bind(ctx); }
+    /** Stop and invalidate old timer callbacks. In-flight Pi sends are not preempted. */
+    stop() {
+        this.generation += 1;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.ctx = undefined;
+        this.retryAttempt = 0;
+        this.pendingRetryDelay = undefined;
+        this.refreshAfterTick = false;
+    }
+    close() { this.stop(); }
+    list(sessionId) { return loadLoops().loops.filter((x) => x.sessionId === sessionId); }
+    get(sessionId, id) { return this.list(sessionId).find((loop) => loop.id === id); }
+    remove(sessionId, id) {
+        const removed = updateLoops((file) => {
+            const before = file.loops.length;
+            file.loops = file.loops.filter((loop) => !(loop.sessionId === sessionId && loop.id === id));
+            return file.loops.length !== before;
+        });
+        this.arm();
+        return removed;
+    }
+    create(sessionId, intervalMs, task) {
+        const loop = createLoop(sessionId, intervalMs, task, loadConfig().loopMissedPolicy);
+        updateLoops((file) => { file.loops.push(loop); });
+        this.arm();
+        return loop;
+    }
+    setEnabled(sessionId, id, enabled) {
+        const updated = updateLoops((file) => {
+            const loop = file.loops.find((x) => x.sessionId === sessionId && x.id === id);
+            if (!loop)
+                throw new Error(`Unknown loop ${id} in this session.`);
+            loop.enabled = enabled;
+            if (enabled && Date.parse(loop.nextRunAt) <= Date.now())
+                loop.nextRunAt = new Date(Date.now() + loop.intervalMs).toISOString();
+            return structuredClone(loop);
+        });
+        this.arm();
+        return updated;
+    }
+    runNow(sessionId, id) {
+        const current = this.get(sessionId, id);
+        if (!current?.enabled)
+            throw new Error(`Unknown active loop ${id} in this session.`);
+        const lock = this.acquireExecutionLock(current);
+        if (!lock)
+            throw new LoopExecutionBusyError(id);
+        let updated;
+        try {
+            updated = updateLoops((file) => {
+                const loop = file.loops.find((x) => x.sessionId === sessionId && x.id === id && x.enabled);
+                if (!loop)
+                    throw new Error(`Unknown active loop ${id} in this session.`);
+                const now = Date.now();
+                loop.lastRunAt = new Date(now).toISOString();
+                loop.nextRunAt = new Date(now + loop.intervalMs).toISOString();
+                return structuredClone(loop);
+            });
+        }
+        catch (error) {
+            this.releaseExecutionLock(lock, id);
+            throw error;
+        }
+        void this.dispatch(updated, lock);
+        this.arm();
+        return updated;
+    }
+    catchUp() {
+        if (!this.ctx)
+            return true;
+        const sessionId = this.ctx.sessionManager.getSessionId();
+        const { due, busyLoopIds } = this.claimDue(sessionId, Date.now(), true);
+        for (const claim of due)
+            void this.dispatch(claim.loop, claim.lock);
+        if (busyLoopIds.length) {
+            this.report("pstack-native loop catch-up found an occurrence already running; retrying", new LoopExecutionBusyError(busyLoopIds.join(", ")));
+            this.scheduleRetry(this.generation);
+            return false;
+        }
+        return true;
+    }
+    async tick(generation) {
+        if (!this.isActive(generation))
+            return;
+        if (this.tickRunning) {
+            this.refreshAfterTick = true;
+            return;
+        }
+        this.tickRunning = true;
+        try {
+            const sessionId = this.ctx.sessionManager.getSessionId();
+            const { due, busyLoopIds } = this.claimDue(sessionId, Date.now(), false);
+            if (busyLoopIds.length) {
+                this.report("pstack-native loop occurrence is still running in another Pi process; retrying", new LoopExecutionBusyError(busyLoopIds.join(", ")));
+                this.scheduleRetry(generation);
+            }
+            else {
+                this.retryAttempt = 0;
+            }
+            await Promise.all(due.map((claim) => this.dispatch(claim.loop, claim.lock)));
+        }
+        catch (error) {
+            this.report("pstack-native loop timer tick failed; retrying", error);
+            this.scheduleRetry(generation);
+        }
+        finally {
+            this.tickRunning = false;
+            if (!this.ctx)
+                return;
+            const currentGeneration = this.generation;
+            const retryDelay = this.pendingRetryDelay;
+            this.pendingRetryDelay = undefined;
+            const needsRefresh = this.refreshAfterTick;
+            this.refreshAfterTick = false;
+            if (this.timer === undefined && (retryDelay !== undefined || needsRefresh || this.isActive(currentGeneration))) {
+                this.arm(currentGeneration, retryDelay);
+            }
+        }
+    }
+    claimDue(sessionId, now, catchUp) {
+        const candidates = loadLoops().loops.filter((loop) => loop.enabled
+            && loop.sessionId === sessionId
+            && Date.parse(loop.nextRunAt) <= now
+            && (!catchUp || loop.missedPolicy === "run-once"));
+        const locks = new Map();
+        const busy = new Set();
+        try {
+            for (const loop of candidates) {
+                const key = executionLockName(loop);
+                if (locks.has(key) || busy.has(loop.id))
+                    continue;
+                const lock = this.acquireExecutionLock(loop);
+                if (lock)
+                    locks.set(key, lock);
+                else
+                    busy.add(loop.id);
+            }
+            const claimed = updateLoops((file) => {
+                const result = [];
+                for (const loop of file.loops) {
+                    if (!loop.enabled || loop.sessionId !== sessionId || Date.parse(loop.nextRunAt) > now)
+                        continue;
+                    const shouldDispatch = !catchUp || loop.missedPolicy === "run-once";
+                    const key = executionLockName(loop);
+                    if (shouldDispatch && !locks.has(key)) {
+                        busy.add(loop.id);
+                        continue;
+                    }
+                    if (shouldDispatch) {
+                        loop.lastRunAt = new Date(now).toISOString();
+                        result.push({ loop: structuredClone(loop), key });
+                    }
+                    loop.nextRunAt = new Date(now + loop.intervalMs).toISOString();
+                }
+                return result;
+            });
+            const used = new Set(claimed.map((claim) => claim.key));
+            for (const [key, lock] of locks)
+                if (!used.has(key))
+                    this.releaseExecutionLock(lock, key);
+            return {
+                due: claimed.map((claim) => ({ loop: claim.loop, lock: locks.get(claim.key) })),
+                busyLoopIds: [...busy],
+            };
+        }
+        catch (error) {
+            for (const [key, lock] of locks)
+                this.releaseExecutionLock(lock, key);
+            throw error;
+        }
+    }
+    acquireExecutionLock(loop) {
+        const lock = new FileLock(lockPath(executionLockName(loop)));
+        return lock.acquire() ? lock : undefined;
+    }
+    releaseExecutionLock(lock, label) {
+        try {
+            lock.release();
+        }
+        catch (error) {
+            this.report(`pstack-native loop execution lock release failed for ${label}`, error);
+        }
+    }
+    dispatch(loop, executionLock) {
+        const ctx = this.ctx;
+        if (!ctx) {
+            if (executionLock)
+                this.releaseExecutionLock(executionLock, loop.id);
+            return Promise.resolve();
+        }
+        const text = `/skill:poteto-mode Scheduled loop ${loop.id}. ${loop.task}`;
+        try {
+            const delivery = this.pi.sendUserMessage(text, ctx.isIdle()
+                ? { expandPromptTemplates: true }
+                : { expandPromptTemplates: true, deliverAs: "followUp" });
+            return Promise.resolve(delivery).catch((error) => {
+                this.report(`pstack-native loop delivery failed for ${loop.id}; the claimed occurrence will not be replayed`, error);
+            }).finally(() => { if (executionLock)
+                this.releaseExecutionLock(executionLock, loop.id); });
+        }
+        catch (error) {
+            this.report(`pstack-native loop delivery failed for ${loop.id}; the claimed occurrence will not be replayed`, error);
+            if (executionLock)
+                this.releaseExecutionLock(executionLock, loop.id);
+            return Promise.resolve();
+        }
+    }
+    isActive(generation) { return this.ctx !== undefined && generation === this.generation; }
+    scheduleRetry(generation) {
+        if (!this.isActive(generation))
+            return;
+        this.retryAttempt += 1;
+        const exponent = Math.min(this.retryAttempt - 1, 30);
+        const delay = Math.min(this.retryMaxMs, this.retryBaseMs * (2 ** exponent));
+        this.arm(generation, delay);
+    }
+    arm(generation = this.generation, delayOverride) {
+        if (!this.isActive(generation))
+            return;
+        if (this.tickRunning) {
+            if (delayOverride !== undefined)
+                this.pendingRetryDelay = delayOverride;
+            else
+                this.refreshAfterTick = true;
+            return;
+        }
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        let delay;
+        if (delayOverride !== undefined) {
+            delay = Math.max(0, Math.min(MAX_TIMER, delayOverride));
+        }
+        else {
+            try {
+                const sessionId = this.ctx.sessionManager.getSessionId();
+                const active = loadLoops().loops
+                    .filter((x) => x.enabled && x.sessionId === sessionId)
+                    .sort((a, b) => Date.parse(a.nextRunAt) - Date.parse(b.nextRunAt));
+                if (!active.length)
+                    return;
+                delay = Math.max(0, Math.min(MAX_TIMER, Date.parse(active[0].nextRunAt) - Date.now()));
+            }
+            catch (error) {
+                this.report("pstack-native loop scheduler could not read loop state; retrying", error);
+                this.scheduleRetry(generation);
+                return;
+            }
+        }
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            if (!this.isActive(generation))
+                return;
+            // Promise.resolve().then() contains synchronous throws as well as async rejections.
+            void Promise.resolve().then(() => this.tick(generation)).catch((error) => {
+                this.report("pstack-native loop timer callback failed; retrying", error);
+                this.scheduleRetry(generation);
+            });
+        }, delay);
+        this.timer.unref?.();
+    }
+    report(message, error) {
+        try {
+            this.logger(message, error);
+        }
+        catch (loggingError) {
+            console.error("pstack-native loop scheduler logger failed", { message, error, loggingError });
+        }
+    }
+}

package/dist/loop/store.d.ts

@@ -0,0 +1,16 @@
+import type { LoopRecord } from "../runtime/types.js";
+export type LoopFile = {
+    version: 1;
+    loops: LoopRecord[];
+};
+export declare class LoopStoreBusyError extends Error {
+    readonly code = "PSTACK_LOOP_STORE_BUSY";
+    constructor();
+}
+export declare function loadLoops(): LoopFile;
+export declare function saveLoops(file: LoopFile): void;
+/** Atomic read-modify-write for the shared loop file. Prevents multiple Pi processes from losing updates. */
+export declare function updateLoops<T>(mutate: (file: LoopFile) => T): T;
+export declare function parseInterval(raw: string): number | undefined;
+export declare function formatInterval(ms: number): string;
+export declare function createLoop(sessionId: string, intervalMs: number, task: string, missedPolicy: LoopRecord["missedPolicy"], now?: number): LoopRecord;

package/dist/loop/store.js

@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import { lockPath, loopsPath } from "../runtime/home.js";
+import { FileLock } from "../runtime/lock.js";
+import { readJson, writeJsonAtomic } from "../runtime/store.js";
+const MIN = 60_000;
+const MAX = 7 * 24 * 60 * 60_000;
+const EMPTY = { version: 1, loops: [] };
+export class LoopStoreBusyError extends Error {
+    code = "PSTACK_LOOP_STORE_BUSY";
+    constructor() {
+        super("pstack loop state is busy in another Pi process; retry shortly.");
+        this.name = "LoopStoreBusyError";
+    }
+}
+export function loadLoops() { return readJson(loopsPath(), EMPTY); }
+export function saveLoops(file) { writeJsonAtomic(loopsPath(), file); }
+/** Atomic read-modify-write for the shared loop file. Prevents multiple Pi processes from losing updates. */
+export function updateLoops(mutate) {
+    const lock = new FileLock(lockPath("loops"));
+    if (!lock.acquire())
+        throw new LoopStoreBusyError();
+    try {
+        const file = loadLoops();
+        const result = mutate(file);
+        saveLoops(file);
+        return result;
+    }
+    finally {
+        lock.release();
+    }
+}
+export function parseInterval(raw) {
+    const match = /^(\d+)(m|h|d)$/i.exec(raw.trim());
+    if (!match)
+        return undefined;
+    const n = Number(match[1]);
+    if (!Number.isSafeInteger(n) || n < 1)
+        return undefined;
+    const factor = match[2].toLowerCase() === "m" ? 60_000 : match[2].toLowerCase() === "h" ? 3_600_000 : 86_400_000;
+    const ms = n * factor;
+    return ms >= MIN && ms <= MAX ? ms : undefined;
+}
+export function formatInterval(ms) {
+    if (ms % 86_400_000 === 0)
+        return `${ms / 86_400_000}d`;
+    if (ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    return `${ms / 60_000}m`;
+}
+export function createLoop(sessionId, intervalMs, task, missedPolicy, now = Date.now()) {
+    if (intervalMs < MIN || intervalMs > MAX)
+        throw new Error("Interval must be from 1m to 7d.");
+    const clean = task.trim();
+    if (!clean)
+        throw new Error("Loop task cannot be empty.");
+    return {
+        id: `loop_${randomUUID().replaceAll("-", "").slice(0, 8)}`,
+        sessionId,
+        intervalMs,
+        task: clean,
+        enabled: true,
+        createdAt: new Date(now).toISOString(),
+        nextRunAt: new Date(now + intervalMs).toISOString(),
+        missedPolicy,
+    };
+}

package/dist/models/router.d.ts

@@ -0,0 +1,25 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ThinkingLevelName } from "../runtime/types.js";
+export type ResolvedModel = {
+    requestedSelector: string;
+    selector: string;
+    model: ExtensionContext["model"];
+    thinkingLevel: ExtensionContext["thinkingLevel"] | ThinkingLevelName | undefined;
+    notes: string[];
+};
+export declare function supportsThinking(model: ExtensionContext["model"], level: ThinkingLevelName): boolean;
+export declare function lowerSupportedThinking(model: ExtensionContext['model'], level: ThinkingLevelName): ThinkingLevelName | undefined;
+/** Identify only recognizable model families; provider names alone do not establish family. */
+export declare function modelFamily(selector: string): string | undefined;
+/** Prefer a known family different from the parent; never infer a family from provider names. */
+export declare function selectJudgeFromPool(ctx: ExtensionContext, pool: string[]): {
+    model?: string;
+    notes: string[];
+};
+export declare function resolveModelSelector(ctx: ExtensionContext, role: string, selector: string): ExtensionContext["model"];
+export declare function resolveRoleModel(ctx: ExtensionContext, role: string, explicit?: string, taskThinking?: ThinkingLevelName): ResolvedModel;
+export declare function availableModelSelectors(ctx: ExtensionContext): string[];
+/** Suggest only models visible to this Pi session. Repeated seats are explicitly reported. */
+export declare function suggestedPanels(ctx: ExtensionContext): Record<string, string[]>;
+/** Drop unavailable configured seats, then retain the upstream minimum using a real survivor or parent. */
+export declare function resolvePanelSeats(ctx: ExtensionContext, selectors: string[], minimum: number, notes: string[]): string[];

package/dist/models/router.js

@@ -0,0 +1,183 @@
+import { loadModels } from "../runtime/config.js";
+function parseSelector(selector) {
+    const slash = selector.indexOf("/");
+    if (slash <= 0 || slash === selector.length - 1)
+        return undefined;
+    return { provider: selector.slice(0, slash), id: selector.slice(slash + 1) };
+}
+export function supportsThinking(model, level) {
+    if (!model)
+        return false;
+    if (level === "off")
+        return true;
+    const candidate = model;
+    if (!candidate.reasoning)
+        return false;
+    const mapped = candidate.thinkingLevelMap?.[level];
+    if (mapped === null)
+        return false;
+    if ((level === "xhigh" || level === "max") && mapped === undefined)
+        return false;
+    return true;
+}
+const EFFORTS = ['max', 'xhigh', 'high', 'medium', 'low', 'minimal'];
+export function lowerSupportedThinking(model, level) {
+    const index = EFFORTS.indexOf(level);
+    return index < 0 ? undefined : EFFORTS.slice(index + 1).find(candidate => supportsThinking(model, candidate));
+}
+/** Identify only recognizable model families; provider names alone do not establish family. */
+export function modelFamily(selector) {
+    const id = parseSelector(selector)?.id.toLowerCase() ?? '';
+    for (const [family, pattern] of [
+        ['claude', /(?:^|[\/_-])claude(?:[\d_-]|$)/],
+        ['grok', /(?:^|[\/_-])(?:grok|composer)(?:[\d_.-]|$)/],
+        ['gpt', /(?:^|[\/_-])gpt(?:[\d_.-]|$)/],
+        ['gemini', /(?:^|[\/_-])gemini(?:[\d_.-]|$)/],
+        ['deepseek', /(?:^|[\/_-])deepseek(?:[\d_.-]|$)/],
+        ['qwen', /(?:^|[\/_-])qwen(?:[\d_.-]|$)/],
+        ['llama', /(?:^|[\/_-])llama(?:[\d_.-]|$)/],
+        ['mistral', /(?:^|[\/_-])mistral(?:[\d_.-]|$)/],
+    ])
+        if (pattern.test(id))
+            return family;
+    return undefined;
+}
+function sameFamilyFallback(ctx, selector) {
+    const wanted = parseSelector(selector), family = modelFamily(selector);
+    if (!wanted || !family)
+        return undefined;
+    const score = (candidate) => {
+        const parsed = parseSelector(candidate);
+        const a = wanted.id.toLowerCase(), b = parsed.id.toLowerCase();
+        let prefix = 0;
+        while (prefix < Math.min(a.length, b.length) && a[prefix] === b[prefix])
+            prefix++;
+        return (parsed.provider === wanted.provider ? 10_000 : 0) + prefix;
+    };
+    return availableModelSelectors(ctx).filter(candidate => candidate !== selector && parseSelector(candidate)?.provider === wanted.provider && modelFamily(candidate) === family)
+        .sort((a, b) => score(b) - score(a) || a.localeCompare(b))[0];
+}
+/** Prefer a known family different from the parent; never infer a family from provider names. */
+export function selectJudgeFromPool(ctx, pool) {
+    const notes = [];
+    const choices = [];
+    const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    const parentFamily = parent ? modelFamily(parent) : undefined;
+    const eligible = (candidate) => parentFamily ? Boolean(modelFamily(candidate) && modelFamily(candidate) !== parentFamily) : candidate !== parent;
+    const resolve = (selector) => {
+        if (selector === 'inherit-parent' || selector === 'auto')
+            return;
+        try {
+            const resolved = resolveRoleModel(ctx, 'judge', selector);
+            if (!resolved.model)
+                throw new Error(`Parent model unavailable for ${selector}`);
+            notes.push(...resolved.notes);
+            choices.push(`${resolved.model.provider}/${resolved.model.id}`);
+        }
+        catch (error) {
+            notes.push(`Judge pool entry ${selector} unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    for (const selector of pool)
+        resolve(selector);
+    if (!choices.some(eligible) && typeof ctx.modelRegistry.getAvailable === 'function') {
+        for (const selector of availableModelSelectors(ctx))
+            if (!pool.includes(selector))
+                resolve(selector);
+    }
+    const selected = choices.find(eligible);
+    if (!parentFamily)
+        notes.push('The parent model family is unknown; judge family independence cannot be established.');
+    if (!selected)
+        notes.push('No eligible cross-judge is available; the coordinator must compare and select the base.');
+    return { model: selected, notes };
+}
+export function resolveModelSelector(ctx, role, selector) {
+    let model;
+    if (selector === "inherit-parent" || selector === "auto")
+        model = ctx.model;
+    else {
+        const parsed = parseSelector(selector);
+        if (!parsed)
+            throw new Error(`Invalid model selector for ${role}: ${selector}. Use provider/model, inherit-parent, or auto.`);
+        model = ctx.modelRegistry.find(parsed.provider, parsed.id);
+        if (!model)
+            throw new Error(`Model for ${role} is not available in this Pi session: ${selector}`);
+    }
+    return model;
+}
+export function resolveRoleModel(ctx, role, explicit, taskThinking) {
+    const config = loadModels();
+    const requested = explicit?.trim() || config.roles[role] || "inherit-parent";
+    let selector = requested;
+    const notes = [];
+    const parsed = parseSelector(requested);
+    if (config.fallbackPolicy === 'same-family' && parsed && !ctx.modelRegistry.find(parsed.provider, parsed.id)) {
+        const fallback = sameFamilyFallback(ctx, requested);
+        if (fallback) {
+            selector = fallback;
+            notes.push(`Model ${requested} is unavailable; using same-family ${fallback}.`);
+        }
+    }
+    const model = resolveModelSelector(ctx, role, selector);
+    const configuredThinking = taskThinking ?? config.thinkingLevel;
+    let thinkingLevel = configuredThinking === "inherit-parent" ? ctx.thinkingLevel : configuredThinking;
+    // Explicit pstack reasoning choices fail closed. `inherit-parent` intentionally delegates
+    // compatibility/clamping to Pi's native AgentSession, just as the parent session does.
+    if (configuredThinking !== "inherit-parent" && thinkingLevel && model && !supportsThinking(model, thinkingLevel)) {
+        const lower = config.fallbackPolicy === 'same-family' ? lowerSupportedThinking(model, thinkingLevel) : undefined;
+        if (!lower)
+            throw new Error(`Configured pstack child reasoning level ${thinkingLevel} is not supported by ${model.provider}/${model.id}. Run /setup-pstack and choose another level or inherit-parent.`);
+        notes.push(`Reasoning level ${thinkingLevel} is unavailable on ${model.provider}/${model.id}; using ${lower}.`);
+        thinkingLevel = lower;
+    }
+    return { requestedSelector: requested, selector, model, thinkingLevel, notes };
+}
+export function availableModelSelectors(ctx) {
+    const source = ctx.scopedModels.length ? ctx.scopedModels.map((x) => x.model) : ctx.modelRegistry.getAvailable();
+    return [...new Set(source.map((m) => `${m.provider}/${m.id}`))].sort();
+}
+/** Suggest only models visible to this Pi session. Repeated seats are explicitly reported. */
+export function suggestedPanels(ctx) {
+    const available = availableModelSelectors(ctx);
+    const parent = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+    const first = parent && available.includes(parent) ? parent : available[0] ?? 'inherit-parent';
+    const family = modelFamily(first);
+    const second = available.find(item => item !== first && family && modelFamily(item) && modelFamily(item) !== family)
+        ?? available.find(item => item !== first) ?? first;
+    const runners = [first, second];
+    // A judge pool is ordered by preference, not a copy of the entire registry.
+    // Keep it bounded even when the user has hundreds of available models.
+    const judges = available.length ? [...new Set(runners)] : ['inherit-parent'];
+    return { arena: [...runners], architect: [...runners], interrogate: [...runners], 'arena-judges': [...judges] };
+}
+/** Drop unavailable configured seats, then retain the upstream minimum using a real survivor or parent. */
+export function resolvePanelSeats(ctx, selectors, minimum, notes) {
+    const models = selectors.flatMap(selector => {
+        try {
+            const resolved = resolveRoleModel(ctx, 'panel', selector);
+            notes.push(...resolved.notes);
+            if (!resolved.model)
+                throw new Error(`PARENT_MODEL_UNAVAILABLE: ${selector}`);
+            return [`${resolved.model.provider}/${resolved.model.id}`];
+        }
+        catch (error) {
+            notes.push(`Panel seat ${selector} was dropped: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    });
+    if (!models.length && ctx.model) {
+        const parent = resolveRoleModel(ctx, 'panel', 'inherit-parent');
+        if (parent.model) {
+            models.push(`${parent.model.provider}/${parent.model.id}`);
+            notes.push(`No configured panel seats resolved; using parent model ${models[0]}.`);
+        }
+    }
+    if (!models.length)
+        throw new Error('NO_AVAILABLE_PANEL_MODELS');
+    while (models.length < minimum) {
+        models.push(models[0]);
+        notes.push('Repeated the remaining model to replace a dropped seat; model diversity is not established.');
+    }
+    return models;
+}