@automatalabs/acp-agents 1.2.7 → 2.0.0

package/dist/backends/pi.js

@@ -2,8 +2,9 @@
 // pi-acp consumes the same client-hosted StructuredOutput MCP server as other HTTP-capable agents.
 import { dirname, join } from "node:path";
 import { createRequire } from "node:module";
+import { META_KEYS } from "@automatalabs/shared-types";
 import { splitArgs } from "../backend.js";
-import { BUILTIN_PROTOCOL_COVERAGE } from "../protocol-coverage.js";
+import { BUILTIN_PROTOCOL_COVERAGE, systemPromptSupport } from "../protocol-coverage.js";
 import { defineBuiltinBackend } from "./define.js";
 const require = createRequire(import.meta.url);
 // pi-acp advertises a single ambient method since ACP schema 1.21.0 removed the `env_var` variant
@@ -30,6 +31,9 @@ export class PiBackend {
     }
     embedSchemaInPrompt = true;
     injectStructuredOutputTool = true;
+    /** pi-acp reads `_meta.systemPrompt` `{ replace?, append? }` on session/new, resume, load, and
+     *  fork and folds it into pi's `DefaultResourceLoader` system-prompt overrides. */
+    systemPrompt = systemPromptSupport("pi");
     classifyProviderError(error, metadata) {
         const providerCode = errorDataString(error, "errorKind");
         if (providerCode === "rate_limit" || providerCode === "billing_error") {
@@ -64,8 +68,16 @@ export class PiBackend {
             return { command: "npx", args: ["-y", "@automatalabs/pi-acp"], env };
         }
     }
-    sessionMeta() {
-        return undefined;
+    sessionMeta(_schema, inputs) {
+        // The schema rides the client-hosted StructuredOutput tool and the prompt, never session
+        // `_meta`. The neutral instructions ride pi-acp's `_meta.systemPrompt` object VERBATIM (only
+        // the defined fields), so an unconfigured session sends no `_meta` at all.
+        const systemPrompt = inputs?.systemPrompt;
+        const value = {
+            ...(systemPrompt?.replace !== undefined ? { replace: systemPrompt.replace } : {}),
+            ...(systemPrompt?.append !== undefined ? { append: systemPrompt.append } : {}),
+        };
+        return Object.keys(value).length > 0 ? { [META_KEYS.systemPrompt]: value } : undefined;
     }
     promptMeta(_schema) {
         return undefined;

package/dist/config-catalog.d.ts

@@ -0,0 +1,173 @@
+import type { SessionConfigOption, SessionModeState } from "@agentclientprotocol/sdk";
+import { type CustomBackendConfig } from "./registry.js";
+import { type ProbedConfigOptions } from "./runner.js";
+export interface ValidateProbeRunner {
+    probeConfigOptions(spec?: string, opts?: {
+        cwd?: string;
+        selectModel?: boolean;
+        backends?: Record<string, CustomBackendConfig>;
+        signal?: AbortSignal;
+    }): Promise<ProbedConfigOptions>;
+    /** Every host-routable backend name. Used by protocol-native discovery. */
+    listBackends?(): string[];
+    /** Host-registered custom names, including deliberate built-in shadows. */
+    listCustomBackends?(): string[];
+    /** The host's backend selected when a workflow omits model. */
+    defaultBackendId?(): string;
+    /** Present on owned probe runners; shared host runners are never disposed by validation. */
+    dispose?(): Promise<void>;
+}
+export type ConfigProbeFactory = (backends: Record<string, CustomBackendConfig> | undefined) => ValidateProbeRunner;
+/** Package-internal hermetic test seam. Deliberately absent from the public index export. */
+export declare function setConfigProbeFactoryForTests(factory: ConfigProbeFactory): () => void;
+export interface ValidateHarnessOptions {
+    backendId: string;
+    /** AgentPrism's explicit mode when the call omits mode; absent for no-mode/custom backends. */
+    defaultModeId?: string;
+    /** The call's verbatim selected model; absent means the harness/session default. */
+    model?: string;
+    probed: boolean;
+    /** Present when probed=false: the harness's spawn/auth/session error. */
+    error?: string;
+    /** Effective advertised ACP modes; null means this backend/model supports no session modes. */
+    modes?: SessionModeState | null;
+    options?: SessionConfigOption[];
+}
+type SelectConfigOption = Extract<SessionConfigOption, {
+    type: "select";
+}>;
+/** Every leaf {value,label} the select advertises, flattening any advertised optgroups. */
+export declare function selectChoicePairs(option: SelectConfigOption): {
+    value: string;
+    label?: string;
+}[];
+export interface SelectChoiceGroup {
+    group: string;
+    count: number;
+}
+export interface SelectChoiceSummary {
+    total: number;
+    groups: SelectChoiceGroup[];
+}
+/**
+ * Group a select's choices for summary display. Prefers the harness-advertised optgroup
+ * labels; absent those, groups by the first "/"-segment of each value. Groups come back
+ * largest-first, ties broken by first appearance.
+ */
+export declare function summarizeSelectChoices(option: SelectConfigOption): SelectChoiceSummary;
+export interface ProbeHarnessConfigOptions {
+    /** Harness names to probe (built-in `claude` / `codex` / `opencode` / `pi` or a registered
+     *  custom name; any model spec routes like an agent() call's). Default: every routable
+     *  harness — the four built-ins plus each registered custom backend. */
+    harnesses?: string[];
+    /** Exact routed model specs to select before reading their model-specific option catalogs. */
+    modelSpecs?: string[];
+    /** Programmatic custom-backend registry, merged over the AGENTPRISM_BACKENDS env var
+     *  exactly like `createAcpRunner({ backends })`. */
+    backends?: Record<string, CustomBackendConfig>;
+    /** Session cwd for the probes. Default `process.cwd()` — harnesses may resolve
+     *  project-level configuration (and hence their catalog) from it. */
+    cwd?: string;
+    /** Host-owned no-prompt probe runner. When supplied it is reused and never disposed. */
+    probeRunner?: ValidateProbeRunner;
+    /** Per-probe cancellation deadline in milliseconds. Default 60,000; lifecycle
+     *  diagnostics can use a shorter bound. Must be a positive timer-safe integer. */
+    probeTimeoutMs?: number;
+    /** Maximum concurrent probes, from 1 to 16. Default 4. */
+    probeConcurrency?: number;
+    /** Shared discovery cancellation budget. Completed catalogs are retained; active
+     * probes are aborted and queued targets become failed entries without starting. */
+    signal?: AbortSignal;
+}
+export interface HarnessConfigReport {
+    /** True when every requested harness probed successfully. */
+    ok: boolean;
+    /** 0 = all probed; 1 = at least one probe failed. */
+    exitCode: 0 | 1;
+    /** One entry per requested harness, in request order — the same shape validate reports. */
+    harnessOptions: ValidateHarnessOptions[];
+    /** Bounded presentation alongside the complete supported catalog. */
+    authoringSummary?: HarnessConfigSummary;
+}
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 60000;
+/**
+ * Probe each requested harness's advertised config-option catalog. A per-harness
+ * spawn/auth/session failure (or timeout) is reported as `probed:false` on that entry —
+ * never thrown. Only caller configuration errors throw: a malformed AGENTPRISM_BACKENDS /
+ * `backends` registry (loud at construction, mirroring `createAcpRunner`) or invalid options.
+ */
+export declare function probeHarnessConfig(options?: ProbeHarnessConfigOptions): Promise<HarnessConfigReport>;
+/** One harness's slice of the `config <harness> --models[=<filter>]` view. Without a
+ *  filter it carries the provider/group breakdown (never the leaf ids); with a filter it
+ *  carries only the matching leaf ids. There is no unfiltered leaf dump on any surface. */
+export interface HarnessModelsView {
+    backendId: string;
+    probed: boolean;
+    /** Present when probed=false. */
+    error?: string;
+    /** False when the harness advertises no `model` select option. */
+    hasModelOption: boolean;
+    /** The filter as given, when one was supplied. */
+    filter?: string;
+    /** Breakdown mode (no filter): total leaf count and per-group counts. */
+    total?: number;
+    groups?: SelectChoiceGroup[];
+    /** Filter mode: the leaf model ids matching the filter. */
+    matches?: string[];
+}
+/** Compile a `--models=<filter>` value into a leaf-value matcher. A value wrapped in
+ *  slashes (`/.../`) is a case-insensitive regex; anything else is a case-insensitive
+ *  substring. Throws a TypeError on an invalid regex (surfaced as a CLI usage error). */
+export declare function buildModelFilter(filter: string): (value: string) => boolean;
+/** Build the per-harness `--models` view. `filter` undefined = breakdown mode. */
+export declare function buildHarnessModelsView(report: HarnessConfigReport, filter?: string): HarnessModelsView[];
+export interface HarnessConfigSummaryModel {
+    modelId: string;
+    /** Exact executable route; browse selectors never appear here. */
+    route: string;
+}
+export interface HarnessConfigSummaryGroup {
+    provider: string;
+    count: number;
+    kind: "provider" | "aggregator";
+    /** Presentation only. Expand with modelFilter; never pass to agent(). */
+    selector?: string;
+    modelFilter: string;
+}
+export interface HarnessConfigSummaryEntry {
+    backendId: string;
+    /** Exact-model probe scope, when selected before reading options. */
+    model?: string;
+    probed: boolean;
+    error?: string;
+    hasModelOption: boolean;
+    /** Actual complete live catalog size, before presentation limits/preferences. */
+    total: number;
+    /** Current selection is separate from preferred models; it need not be preferred. */
+    currentModel?: string;
+    /** Present only when the current model is an advertised executable leaf. */
+    currentRoute?: string;
+    omittedCurrentModel?: true;
+    models: HarnessConfigSummaryModel[];
+    omittedModels: number;
+    groups: HarnessConfigSummaryGroup[];
+    omittedGroups: number;
+    omittedGroupModels: number;
+    preferenceSource?: "enabledModels";
+    /** Available preferred models before presentation limits. */
+    preferredTotal?: number;
+    unmatched: string[];
+    omittedUnmatched: number;
+}
+export interface HarnessConfigSummary {
+    /** One entry per requested probe, including unavailable backends, in request order. */
+    harnesses: HarnessConfigSummaryEntry[];
+}
+/** Compact live authoring guidance. Does not mutate or restrict the supported catalog.
+ * Lists are bounded per harness; omitted counts and exact expansion filters are explicit.
+ * Options such as effort remain authoritative only for the exact probed model. */
+export declare function buildHarnessConfigSummary(report: Pick<HarnessConfigReport, "harnessOptions">): HarnessConfigSummary;
+/** Format the bounded summary for both explicit discovery and missing-route diagnostics. */
+export declare function formatHarnessConfigSummary(summary: HarnessConfigSummary): string;
+export {};
+//# sourceMappingURL=config-catalog.d.ts.map

package/dist/config-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-catalog.d.ts","sourceRoot":"","sources":["../src/config-catalog.ts"],"names":[],"mappings":"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"}

package/dist/config-catalog.js

@@ -0,0 +1,408 @@
+// Harness config discovery — the token-free catalog probe behind `agentprism-workflows config`
+// (the CLI lives in @automatalabs/workflows; that facade re-exports everything here) and the
+// SDK's `AcpAgent.probe`. Where validate probes only the harnesses a script routes to, this
+// probes any requested (or every routable) harness WITHOUT a script: one no-prompt ACP session
+// per harness, returning the agent-advertised session config-option catalog plus the effective
+// ACP session-mode catalog — model ids (including bracket variants), effort levels, modes, and
+// every other negotiable option. Zero tokens. Authoring flows run this FIRST so `model` /
+// `configOptions` values come from the live catalog, not memory.
+import { redactText } from "@automatalabs/shared-types";
+import { BUILTIN_BACKEND_IDS } from "./backends/builtins.js";
+import { resolveBackendRegistry } from "./registry.js";
+import { AcpAgentRunner } from "./runner.js";
+let probeFactory = (backends) => new AcpAgentRunner({ backends });
+/** Package-internal hermetic test seam. Deliberately absent from the public index export. */
+export function setConfigProbeFactoryForTests(factory) {
+    const previous = probeFactory;
+    probeFactory = factory;
+    return () => {
+        probeFactory = previous;
+    };
+}
+/** Every leaf {value,label} the select advertises, flattening any advertised optgroups. */
+export function selectChoicePairs(option) {
+    return option.options
+        .flatMap((entry) => ("options" in entry ? entry.options : [entry]))
+        .map((entry) => ({ value: entry.value, label: entry.name }));
+}
+/** The group a bare (ungrouped) choice value belongs to: its first "/"-segment
+ *  (pi/opencode ids are "<provider>/<model>"); a value with no "/" is "(ungrouped)". */
+function groupOfValue(value) {
+    const slash = value.indexOf("/");
+    return slash > 0 ? value.slice(0, slash) : "(ungrouped)";
+}
+/**
+ * Group a select's choices for summary display. Prefers the harness-advertised optgroup
+ * labels; absent those, groups by the first "/"-segment of each value. Groups come back
+ * largest-first, ties broken by first appearance.
+ */
+export function summarizeSelectChoices(option) {
+    const counts = new Map();
+    const order = [];
+    const bump = (name, n) => {
+        if (!counts.has(name))
+            order.push(name);
+        counts.set(name, (counts.get(name) ?? 0) + n);
+    };
+    const hasAdvertisedGroups = option.options.some((entry) => "options" in entry);
+    for (const entry of option.options) {
+        if ("options" in entry)
+            bump(entry.name ?? entry.group, entry.options.length);
+        else if (hasAdvertisedGroups)
+            bump(groupOfValue(entry.value), 1); // stray leaf beside groups
+        else
+            bump(groupOfValue(entry.value), 1);
+    }
+    const total = [...counts.values()].reduce((sum, n) => sum + n, 0);
+    const groups = order
+        .map((group) => ({ group, count: counts.get(group) ?? 0 }))
+        .sort((a, b) => b.count - a.count || order.indexOf(a.group) - order.indexOf(b.group));
+    return { total, groups };
+}
+export const DEFAULT_PROBE_TIMEOUT_MS = 60_000;
+/**
+ * Probe each requested harness's advertised config-option catalog. A per-harness
+ * spawn/auth/session failure (or timeout) is reported as `probed:false` on that entry —
+ * never thrown. Only caller configuration errors throw: a malformed AGENTPRISM_BACKENDS /
+ * `backends` registry (loud at construction, mirroring `createAcpRunner`) or invalid options.
+ */
+export async function probeHarnessConfig(options = {}) {
+    const timeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const concurrency = options.probeConcurrency ?? 4;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new TypeError("probeTimeoutMs must be a positive integer no greater than 2147483647");
+    }
+    if (!Number.isInteger(concurrency) || concurrency <= 0 || concurrency > 16) {
+        throw new TypeError("probeConcurrency must be an integer between 1 and 16");
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const registry = resolveBackendRegistry(options.backends);
+    const defaultHarnesses = options.probeRunner?.listBackends?.() ?? [...BUILTIN_BACKEND_IDS, ...registry.keys()];
+    const harnessTargets = options.harnesses && options.harnesses.length > 0
+        ? options.harnesses
+        : options.modelSpecs && options.modelSpecs.length > 0
+            ? []
+            : defaultHarnesses;
+    const targets = [
+        ...new Map([
+            ...harnessTargets.map((spec) => ({ spec, selectModel: false })),
+            ...(options.modelSpecs ?? []).map((spec) => ({ spec, selectModel: true })),
+        ].map((target) => [JSON.stringify([target.spec, target.selectModel]), target])).values(),
+    ];
+    const harnessOptions = new Array(targets.length);
+    const ownsRunner = options.probeRunner === undefined;
+    const runner = options.probeRunner ?? probeFactory(options.backends);
+    try {
+        let nextTarget = 0;
+        await Promise.all(Array.from({ length: Math.min(concurrency, targets.length) }, async () => {
+            while (nextTarget < targets.length) {
+                const index = nextTarget++;
+                const target = targets[index];
+                try {
+                    const result = await withProbeTimeout((signal) => runner.probeConfigOptions(target.spec, {
+                        cwd,
+                        selectModel: target.selectModel,
+                        backends: options.backends,
+                        signal,
+                    }), timeoutMs, options.signal);
+                    harnessOptions[index] = {
+                        backendId: result.backendId,
+                        ...(result.defaultModeId === undefined ? {} : { defaultModeId: result.defaultModeId }),
+                        ...(target.selectModel ? { model: target.spec } : {}),
+                        probed: true,
+                        modes: result.modes ?? null,
+                        options: result.options,
+                    };
+                }
+                catch (error) {
+                    harnessOptions[index] = {
+                        backendId: target.spec.split("/", 1)[0] ?? target.spec,
+                        ...(target.selectModel ? { model: target.spec } : {}),
+                        probed: false,
+                        error: probeErrorMessage(error),
+                    };
+                }
+            }
+        }));
+    }
+    finally {
+        if (ownsRunner) {
+            try {
+                // Always initiate owned cleanup, including after cancellation, without
+                // letting stalled disposal extend the caller's discovery budget.
+                const disposal = Promise.resolve().then(() => runner.dispose?.());
+                void disposal.catch(() => { });
+                await withProbeTimeout(() => disposal, timeoutMs, options.signal);
+            }
+            catch {
+                // Probe results are already complete; disposal (e.g. of a timed-out process) is best-effort.
+            }
+        }
+    }
+    const ok = harnessOptions.every((harness) => harness.probed);
+    return {
+        ok, exitCode: ok ? 0 : 1, harnessOptions,
+        authoringSummary: buildHarnessConfigSummary({ harnessOptions }),
+    };
+}
+/** The `model` select option a harness advertises, if any. */
+function modelSelectOption(harness) {
+    return (harness.options ?? []).find((option) => option.type === "select" && option.id === "model");
+}
+/** Compile a `--models=<filter>` value into a leaf-value matcher. A value wrapped in
+ *  slashes (`/.../`) is a case-insensitive regex; anything else is a case-insensitive
+ *  substring. Throws a TypeError on an invalid regex (surfaced as a CLI usage error). */
+export function buildModelFilter(filter) {
+    if (filter.length >= 2 && filter.startsWith("/") && filter.endsWith("/")) {
+        let re;
+        try {
+            re = new RegExp(filter.slice(1, -1), "i");
+        }
+        catch (error) {
+            throw new TypeError(`--models: invalid regex ${filter} — ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return (value) => re.test(value);
+    }
+    const needle = filter.toLowerCase();
+    return (value) => value.toLowerCase().includes(needle);
+}
+/** Build the per-harness `--models` view. `filter` undefined = breakdown mode. */
+export function buildHarnessModelsView(report, filter) {
+    const match = filter === undefined ? undefined : buildModelFilter(filter);
+    return report.harnessOptions.map((harness) => {
+        if (!harness.probed) {
+            return { backendId: harness.backendId, probed: false, error: harness.error, hasModelOption: false };
+        }
+        const model = modelSelectOption(harness);
+        if (!model) {
+            return { backendId: harness.backendId, probed: true, hasModelOption: false };
+        }
+        if (match === undefined) {
+            const { total, groups } = summarizeSelectChoices(model);
+            return { backendId: harness.backendId, probed: true, hasModelOption: true, total, groups };
+        }
+        const matches = selectChoicePairs(model)
+            .map((pair) => pair.value)
+            .filter((value) => match(value));
+        return { backendId: harness.backendId, probed: true, hasModelOption: true, filter, matches };
+    });
+}
+/** Bound one probe; the underlying promise keeps its handlers, so a late settle is inert. */
+function withProbeTimeout(op, ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error("config discovery cancelled"));
+            return;
+        }
+        const controller = new AbortController();
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const abort = (reason) => {
+            cleanup();
+            controller.abort(reason);
+            reject(reason);
+        };
+        const onAbort = () => abort(signal?.reason ?? new Error("config discovery cancelled"));
+        const timer = setTimeout(() => abort(new Error(`probe timed out after ${ms}ms`)), ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        // Keep the deadline alive even if a stalled runner has no referenced handles.
+        // Defer invocation so synchronous throws also clear the timer through this path.
+        Promise.resolve().then(() => {
+            controller.signal.throwIfAborted();
+            return op(controller.signal);
+        }).then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+function probeErrorMessage(error) {
+    return redactText(error instanceof Error ? error.message : String(error)).value;
+}
+// ── The bounded authoring summary ──
+const MAX_ENTRIES = 24;
+const MAX_VALUE_LENGTH = 240;
+// Deliberate classification by exact provider id, never a substring/name heuristic.
+const OPENCODE_AGGREGATORS = new Set([
+    "openrouter", "opencode", "opencode-go", "huggingface", "amazon-bedrock", "github-copilot",
+]);
+const MODEL_DISCOVERY_META = "@automatalabs/agentprism.modelDiscovery";
+function boundedLabel(value) {
+    return value.length <= MAX_VALUE_LENGTH
+        ? value
+        : `${value.slice(0, MAX_VALUE_LENGTH)}… (${value.length - MAX_VALUE_LENGTH} characters omitted)`;
+}
+function display(value) {
+    return boundedLabel(redactText(value).value);
+}
+function providerOf(value) {
+    const slash = value.indexOf("/");
+    return slash > 0 ? value.slice(0, slash) : "(ungrouped)";
+}
+function providerFilter(provider) {
+    return provider === "(ungrouped)"
+        ? "/^[^/]+$/"
+        : `/^${provider.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\//`;
+}
+function preferences(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const meta = value;
+    if (meta.source !== "enabledModels" || !Array.isArray(meta.preferred) || !Array.isArray(meta.unmatched)) {
+        return undefined;
+    }
+    if (!meta.preferred.every((id) => typeof id === "string") || !meta.unmatched.every((id) => typeof id === "string")) {
+        return undefined;
+    }
+    return { preferred: meta.preferred, unmatched: meta.unmatched };
+}
+/** Compact live authoring guidance. Does not mutate or restrict the supported catalog.
+ * Lists are bounded per harness; omitted counts and exact expansion filters are explicit.
+ * Options such as effort remain authoritative only for the exact probed model. */
+export function buildHarnessConfigSummary(report) {
+    return {
+        harnesses: report.harnessOptions.map((harness) => {
+            const entry = {
+                backendId: boundedLabel(harness.backendId),
+                ...(harness.model === undefined ? {} : { model: boundedLabel(harness.model) }),
+                probed: harness.probed,
+                ...(!harness.probed ? { error: display(harness.error ?? "unknown error") } : {}),
+                hasModelOption: false,
+                total: 0, models: [], omittedModels: 0, groups: [], omittedGroups: 0,
+                omittedGroupModels: 0, unmatched: [], omittedUnmatched: 0,
+            };
+            if (!harness.probed)
+                return entry;
+            const model = harness.options?.find((option) => option.id === "model" && option.type === "select");
+            if (!model || model.type !== "select")
+                return entry;
+            entry.hasModelOption = true;
+            const ids = selectChoicePairs(model).map(({ value }) => value);
+            entry.total = ids.length;
+            if (model.currentValue) {
+                const route = `${harness.backendId}/${model.currentValue}`;
+                if (route.length <= MAX_VALUE_LENGTH) {
+                    entry.currentModel = model.currentValue;
+                    if (ids.includes(model.currentValue) && !model.currentValue.includes("*"))
+                        entry.currentRoute = route;
+                }
+                else
+                    entry.omittedCurrentModel = true;
+            }
+            const groups = new Map();
+            for (const id of ids) {
+                const provider = providerOf(id);
+                groups.set(provider, (groups.get(provider) ?? 0) + 1);
+            }
+            const isAggregator = (provider) => harness.backendId === "opencode" && OPENCODE_AGGREGATORS.has(provider);
+            // Stable sorting preserves catalog provider order within each classification.
+            const orderedGroups = [...groups].sort(([a], [b]) => Number(isAggregator(a)) - Number(isAggregator(b)));
+            for (const [provider, count] of orderedGroups) {
+                if (entry.groups.length >= MAX_ENTRIES || provider.length > MAX_VALUE_LENGTH) {
+                    entry.omittedGroups++;
+                    entry.omittedGroupModels += count;
+                    continue;
+                }
+                entry.groups.push({
+                    provider, count,
+                    kind: isAggregator(provider) ? "aggregator" : "provider",
+                    ...(isAggregator(provider) ? { selector: `${provider}/*` } : {}),
+                    modelFilter: providerFilter(provider),
+                });
+            }
+            const preferred = harness.backendId === "pi" ? preferences(model._meta?.[MODEL_DISCOVERY_META]) : undefined;
+            let candidates;
+            if (preferred) {
+                const available = new Set(ids);
+                candidates = [...new Set(preferred.preferred)].filter((id) => available.has(id));
+                entry.preferenceSource = "enabledModels";
+                entry.preferredTotal = candidates.length;
+                entry.unmatched = preferred.unmatched.slice(0, MAX_ENTRIES).map(display);
+                entry.omittedUnmatched = preferred.unmatched.length - entry.unmatched.length;
+            }
+            else if (harness.backendId === "pi") {
+                candidates = [];
+            }
+            else if (harness.backendId === "opencode") {
+                // When direct catalogs exceed the display bound, represent each configured
+                // direct provider before filling more rows from any one provider.
+                const direct = new Map();
+                for (const id of ids) {
+                    const provider = providerOf(id);
+                    if (isAggregator(provider))
+                        continue;
+                    const group = direct.get(provider) ?? [];
+                    group.push(id);
+                    direct.set(provider, group);
+                }
+                candidates = [];
+                for (let index = 0; [...direct.values()].some((values) => index < values.length); index++) {
+                    for (const values of direct.values())
+                        if (values[index] !== undefined)
+                            candidates.push(values[index]);
+                }
+            }
+            else {
+                candidates = ids.filter((id) => !isAggregator(providerOf(id)));
+            }
+            for (const id of candidates) {
+                const route = `${harness.backendId}/${id}`;
+                if (entry.models.length >= MAX_ENTRIES || route.length > MAX_VALUE_LENGTH || id.includes("*"))
+                    continue;
+                entry.models.push({ modelId: id, route });
+            }
+            entry.omittedModels = entry.total - entry.models.length;
+            return entry;
+        }),
+    };
+}
+/** Format the bounded summary for both explicit discovery and missing-route diagnostics. */
+export function formatHarnessConfigSummary(summary) {
+    const lines = ["authoring model summary:"];
+    if (!summary.harnesses.length)
+        lines.push("  (no harnesses requested)");
+    for (const harness of summary.harnesses) {
+        const label = harness.model ?? harness.backendId;
+        if (!harness.probed) {
+            lines.push(`  ${JSON.stringify(label)}: unavailable — ${JSON.stringify(harness.error)}`);
+            continue;
+        }
+        if (!harness.hasModelOption) {
+            lines.push(`  ${JSON.stringify(label)}: no model option advertised`);
+            continue;
+        }
+        lines.push(`  ${JSON.stringify(label)}: ${harness.total} supported model(s)`);
+        if (harness.currentModel !== undefined) {
+            lines.push(`    current model: ${JSON.stringify(harness.currentRoute ?? harness.currentModel)}`);
+        }
+        if (harness.omittedCurrentModel)
+            lines.push("    current model omitted by summary length limit; inspect the model config option");
+        if (harness.preferenceSource) {
+            lines.push(`    Pi enabledModels: ${harness.preferredTotal} available preferred model(s); presentation shortlist, not an execution allowlist`);
+        }
+        else if (harness.backendId === "pi") {
+            lines.push("    No enabledModels preference metadata; showing available provider groups");
+        }
+        for (const model of harness.models)
+            lines.push(`    model: ${JSON.stringify(model.route)}`);
+        if (harness.omittedModels)
+            lines.push(`    ${harness.omittedModels} supported model(s) not listed as exact routes here; expand with modelFilter`);
+        for (const group of harness.groups) {
+            lines.push(`    ${group.kind === "aggregator" ? "browse only (not executable)" : "provider"}: ${JSON.stringify(group.selector ?? group.provider)} (${group.count} models); modelFilter: ${JSON.stringify(group.modelFilter)}`);
+        }
+        if (harness.omittedGroups)
+            lines.push(`    ${harness.omittedGroups} provider group(s), ${harness.omittedGroupModels} models omitted by summary limits; use config modelFilter`);
+        if (harness.unmatched.length)
+            lines.push(`    unmatched enabledModels patterns: ${harness.unmatched.map((value) => JSON.stringify(value)).join(", ")}`);
+        if (harness.omittedUnmatched)
+            lines.push(`    ${harness.omittedUnmatched} additional unmatched enabledModels pattern(s) omitted by summary limits`);
+    }
+    lines.push('  Browse wildcards are not executable. Expand with config harnesses:["<backend>"], modelFilter:"<substring or /regex/>"; use an exact returned leaf route in agent(prompt, { model }).');
+    lines.push('  Default-model options do not describe every model. Probe config modelSpecs:["<exact route>"] before choosing mode/effort/configOptions. A backend-only model route explicitly selects its configured default.');
+    return lines.join("\n");
+}