@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/model/agent/entry-limits.js

@@ -0,0 +1,133 @@
+/**
+ * Bounded view state (tui-render-performance L1 / R5).
+ *
+ * `ViewState.entries` used to grow without any ceiling: `argsRaw`, assistant
+ * `text` and `thinking` all concatenated forever, and the entry array was never
+ * trimmed. That makes the per-frame cost of the renderer proportional to the
+ * total number of characters the session has ever produced, because Ink's
+ * `renderNodeToOutput` walks and measures every mounted text node whether or not
+ * `overflow: hidden` clips it.
+ *
+ * Two bounds live here, both pure and React-free:
+ *   - `appendBounded` caps one field by eliding its MIDDLE, and
+ *   - `trimEntries` ring-trims the entry array itself.
+ *
+ * ASCII ONLY. This module is produced outside `src/ui/**`, where no terminal
+ * capabilities are available, so the elision marker has to be safe on a legacy
+ * `cmd.exe` -- the same rule `PREVIEW_TRUNCATION_MARK` in `reducer.ts` records.
+ */
+import { DEFAULT_TRANSCRIPT_RETAIN } from '../config/schema.js';
+/**
+ * The per-field ceilings.
+ *
+ * `text` is the generous one on purpose: a 256 KiB answer is already far past
+ * anything a terminal can usefully show, and the middle is what gets elided, so
+ * both the opening and the live cursor survive. `argsRaw` is the tight one --
+ * it is a streamed JSON fragment rendered as a 60-character card summary, so
+ * anything past a few KiB is invisible by construction.
+ */
+export const ENTRY_LIMITS = {
+    text: 262_144,
+    thinking: 65_536,
+    argsRaw: 16_384,
+};
+/** Marker inserted at the elision point. ASCII -- produced outside `src/ui/**`. */
+export const ELISION_MARK_PREFIX = '\n[... ';
+export const ELISION_MARK_SUFFIX = ' characters elided ...]\n';
+/** Matches a marker this module wrote, so re-elision collapses rather than nests. */
+const ELISION_RE = /\n\[\.\.\. (\d+) characters elided \.\.\.\]\n/;
+/** Fixed cost of the marker, before the digits of the count. */
+const MARKER_FIXED = ELISION_MARK_PREFIX.length + ELISION_MARK_SUFFIX.length;
+/**
+ * Fraction of the cap reserved for the HEAD. The tail gets the rest because that
+ * is where the cursor is; the head exists so the answer still starts where the
+ * model started it.
+ */
+const HEAD_FRACTION = 4;
+/** Undo one elision, so a second one merges into it rather than nesting. */
+function splitElided(prev) {
+    const m = ELISION_RE.exec(prev);
+    if (!m)
+        return { head: '', elided: 0, tail: prev };
+    const index = m.index;
+    return {
+        head: prev.slice(0, index),
+        elided: Number.parseInt(m[1], 10) || 0,
+        tail: prev.slice(index + m[0].length),
+    };
+}
+/**
+ * Append `delta` to `prev`, keeping the result at or below `cap` by eliding the
+ * MIDDLE. Head and tail are both preserved: the head is the answer's opening,
+ * the tail is where the cursor is. Idempotent -- re-eliding an already elided
+ * string collapses the two markers into one.
+ *
+ * The returned string is NEVER longer than `cap` (AC-7). The marker's own digit
+ * count is bounded before the tail budget is computed, so the arithmetic cannot
+ * overshoot by a digit the way a naive `cap - marker.length` would.
+ */
+export function appendBounded(prev, delta, cap) {
+    if (!Number.isFinite(cap) || cap <= 0)
+        return '';
+    const split = splitElided(prev);
+    let head = split.head;
+    let tail = split.tail + delta;
+    let elided = split.elided;
+    // Fast path: nothing has ever been elided and it still fits. This is the path
+    // every ordinary answer takes, so it must allocate nothing beyond the concat.
+    if (elided === 0 && tail.length <= cap)
+        return tail;
+    const headBudget = Math.max(0, Math.min(Math.floor(cap / HEAD_FRACTION), cap - MARKER_FIXED - 1));
+    if (elided === 0) {
+        // First elision: the head has to be carved out of the accumulated text.
+        head = tail.slice(0, headBudget);
+        tail = tail.slice(headBudget);
+    }
+    else if (head.length > headBudget) {
+        // A later `cap` reduction can leave the stored head oversized; charge the
+        // difference to the elision count rather than silently keeping it.
+        elided += head.length - headBudget;
+        head = head.slice(0, headBudget);
+    }
+    if (head.length + MARKER_FIXED >= cap) {
+        // Degenerate cap (only reachable from a hand-written test): keep the tail.
+        return tail.slice(Math.max(0, tail.length - cap));
+    }
+    // `elided + tail.length` is an UPPER BOUND on the final count, so its digit
+    // count is an upper bound on the marker's width. Budgeting against the bound
+    // is what makes the `<= cap` guarantee hold without a second pass.
+    const digitBound = String(elided + tail.length).length;
+    const markerBound = MARKER_FIXED + digitBound;
+    const tailKeep = Math.max(0, Math.min(tail.length, cap - head.length - markerBound));
+    const total = elided + (tail.length - tailKeep);
+    return `${head}${ELISION_MARK_PREFIX}${total}${ELISION_MARK_SUFFIX}${tail.slice(tail.length - tailKeep)}`;
+}
+/**
+ * Ring-trim to `retain` entries; returns the SAME array reference when no-op.
+ *
+ * The identity return is load-bearing: the reducer spreads this result into a
+ * new `ViewState` on every append, and a fresh array on every action would
+ * defeat the `React.memo` boundaries L2 installs on the transcript.
+ */
+export function trimEntries(entries, retain) {
+    const keep = Math.max(1, Math.floor(retain));
+    if (entries.length <= keep)
+        return { entries, dropped: 0 };
+    return { entries: entries.slice(entries.length - keep), dropped: entries.length - keep };
+}
+// ---------------------------------------------------------------------------
+// The resolved retain ceiling
+// ---------------------------------------------------------------------------
+/**
+ * `viewReducer` is pure and takes no config, so the resolved `transcriptRetain`
+ * reaches it through a module-level singleton -- the shape `prompt-history.ts`
+ * already uses for `setHistoryEnabled`. `load.ts` is the ONLY writer.
+ */
+let resolvedRetain = DEFAULT_TRANSCRIPT_RETAIN;
+export function setEntryRetain(value) {
+    if (Number.isFinite(value) && value > 0)
+        resolvedRetain = Math.floor(value);
+}
+export function entryRetain() {
+    return resolvedRetain;
+}

package/dist/model/agent/governance-view.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The governance slice of the view model: the small pure folds `reducer.ts` delegates to
+ * (governance-mode section 14.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`agent/` is glyph-scanned).
+ *
+ * WHY A FILE OF ITS OWN. `reducer.ts` is already past the file-size ceiling and the repo
+ * rule is "wiring-style growth only": each governance `case` in the reducer is a line or
+ * two that calls a function here, so the logic is unit-testable without a `ViewState`.
+ */
+import type { AgentMode } from './agent-mode.js';
+import type { GovernanceSnapshot } from '../governance/types.js';
+import { type Posture } from '../governance/posture.js';
+/** The posture half of a `setAgentMode` action. */
+export interface AdoptedPostureInput {
+    mode: AgentMode;
+    pending: AgentMode | null;
+    /** Written from the controller's adopted state; absent for callers that predate postures. */
+    posture?: Posture;
+    pendingPosture?: Posture | null;
+}
+/**
+ * The pair of posture fields one `setAgentMode` dispatch writes.
+ *
+ * "NEVER DISPATCH THE REQUESTED VALUE, ONLY THE ADOPTED ONE" (spec 4.3): the controller
+ * reports all four values together and the reducer mirrors them, so the badge and the gate
+ * cannot disagree. A dispatch that carries only the gate mode (every pre-governance call
+ * site) keeps the governance dimension the view already has and swaps the mode half, which
+ * is exactly what such a caller meant.
+ */
+export declare function adoptPosture(current: Posture, action: AdoptedPostureInput): {
+    posture: Posture;
+    pendingPosture: Posture | null;
+};
+/**
+ * Fold a pushed snapshot into the view: a snapshot OLDER than the one held, for the same
+ * run, is dropped (the wiring throttles, and a late flush must not roll the panel back).
+ * Returns the held object unchanged when nothing should change.
+ */
+export declare function foldGovernanceSnapshot(held: GovernanceSnapshot | null, incoming: GovernanceSnapshot): GovernanceSnapshot;

package/dist/model/agent/governance-view.js

@@ -0,0 +1,40 @@
+/**
+ * The governance slice of the view model: the small pure folds `reducer.ts` delegates to
+ * (governance-mode section 14.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`agent/` is glyph-scanned).
+ *
+ * WHY A FILE OF ITS OWN. `reducer.ts` is already past the file-size ceiling and the repo
+ * rule is "wiring-style growth only": each governance `case` in the reducer is a line or
+ * two that calls a function here, so the logic is unit-testable without a `ViewState`.
+ */
+import { composePosture, isGovernancePosture } from '../governance/posture.js';
+/**
+ * The pair of posture fields one `setAgentMode` dispatch writes.
+ *
+ * "NEVER DISPATCH THE REQUESTED VALUE, ONLY THE ADOPTED ONE" (spec 4.3): the controller
+ * reports all four values together and the reducer mirrors them, so the badge and the gate
+ * cannot disagree. A dispatch that carries only the gate mode (every pre-governance call
+ * site) keeps the governance dimension the view already has and swaps the mode half, which
+ * is exactly what such a caller meant.
+ */
+export function adoptPosture(current, action) {
+    const governed = isGovernancePosture(current);
+    const posture = action.posture ?? composePosture(action.mode, governed);
+    const pendingPosture = action.pendingPosture !== undefined
+        ? action.pendingPosture
+        : action.pending === null
+            ? null
+            : composePosture(action.pending, governed);
+    return { posture, pendingPosture };
+}
+/**
+ * Fold a pushed snapshot into the view: a snapshot OLDER than the one held, for the same
+ * run, is dropped (the wiring throttles, and a late flush must not roll the panel back).
+ * Returns the held object unchanged when nothing should change.
+ */
+export function foldGovernanceSnapshot(held, incoming) {
+    if (held !== null && held.runId === incoming.runId && incoming.rev < held.rev)
+        return held;
+    return incoming;
+}

package/dist/model/agent/invocation-card.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Invocation cards (tui-invocation-cards): what a transcript shows INSTEAD of the
+ * system prompt a command submitted on the user's behalf.
+ *
+ * Pure and total: no IO, no React, no Ink, nothing but `import type`. ASCII ONLY -
+ * `src/agent/**` new files sit inside the `glyphs.test.ts` scan scope.
+ *
+ * ONE CONSTRUCTOR (I-3). `buildInvocationCard` is the only function that turns raw
+ * command-layer material into a card, `App.submitMessage` is its only caller, and
+ * `sanitizeInvocationCard` (the session-load path) shares its normaliser so a card
+ * written today and a card read back tomorrow cannot drift apart.
+ *
+ * ORDER IS REDACT -> NORMALISE -> LIMIT, and it is the load-bearing part (I-6). Cut
+ * first and a secret that straddles the cut leaves a prefix shorter than the
+ * redaction patterns' minimum length: the half-key sails through into the
+ * transcript, the session file and the exit replay.
+ */
+export type InvocationVariant = 'skill' | 'team' | 'todo' | 'govern';
+/** Everything one card needs; persisted, queued and rendered in this one shape. */
+export interface InvocationCard {
+    readonly variant: InvocationVariant;
+    /** Skill name / 'continue' / 'resume'; '' for team. */
+    readonly name: string;
+    /** What the user typed (or its equivalent), redacted and capped; also `Entry.text`. */
+    readonly commandLine: string;
+    /** The user's own words (args / brief), redacted and trimmed; may be ''. */
+    readonly input: string;
+    /** Characters cut from `input`; 0 when nothing was cut. */
+    readonly inputHidden: number;
+    /** Fact fragments, each at most `factMaxChars`, at most `factsMax` of them. */
+    readonly facts: readonly string[];
+    /** One disclosure sentence. */
+    readonly note?: string;
+}
+/**
+ * The renderer, the height estimate and the loader all read THESE numbers (I-4).
+ * A card's height is a function of its data and these limits, so it is bounded:
+ * header + `inputMaxLines` + hidden tail + note.
+ */
+export declare const INVOCATION_LIMITS: {
+    readonly commandLineMaxChars: 2000;
+    readonly inputMaxChars: 480;
+    readonly inputMaxLines: 8;
+    readonly nameMaxChars: 64;
+    readonly factsMax: 5;
+    readonly factMaxChars: 28;
+    readonly noteMaxChars: 140;
+};
+/**
+ * Raw material from the command layer: NOT redacted, NOT trimmed. Commands must not
+ * cut or scrub it themselves - both happen exactly once, in `buildInvocationCard`.
+ */
+export interface InvocationCardInput {
+    variant: InvocationVariant;
+    name?: string;
+    commandLine: string;
+    input?: string;
+    facts?: readonly string[];
+    note?: string;
+}
+/**
+ * Total, never throws. `redact` is injected (the same closure `Command:` echo uses) so
+ * this module depends on nothing; the default is the identity for tests and the loader.
+ */
+export declare function buildInvocationCard(input: InvocationCardInput, redact?: (text: string) => string): InvocationCard;
+/**
+ * Session-load path: `null` for anything that is not a plausible card, so the caller
+ * drops the field and the entry degrades to a plain user message (I-7). Re-derives
+ * `inputHidden` from nothing - it trusts the stored count only when it is a sane integer.
+ */
+export declare function sanitizeInvocationCard(value: unknown): InvocationCard | null;
+/**
+ * Emergency kill switch (`ARAGON_NO_INVOCATION_CARDS=1`): every command and the App fall
+ * back to the pre-card behaviour. Read at call time, not import time, so a test (or a
+ * wrapper script) that sets the variable after load is honoured.
+ */
+export declare function invocationCardsEnabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/model/agent/invocation-card.js

@@ -0,0 +1,169 @@
+/**
+ * Invocation cards (tui-invocation-cards): what a transcript shows INSTEAD of the
+ * system prompt a command submitted on the user's behalf.
+ *
+ * Pure and total: no IO, no React, no Ink, nothing but `import type`. ASCII ONLY -
+ * `src/agent/**` new files sit inside the `glyphs.test.ts` scan scope.
+ *
+ * ONE CONSTRUCTOR (I-3). `buildInvocationCard` is the only function that turns raw
+ * command-layer material into a card, `App.submitMessage` is its only caller, and
+ * `sanitizeInvocationCard` (the session-load path) shares its normaliser so a card
+ * written today and a card read back tomorrow cannot drift apart.
+ *
+ * ORDER IS REDACT -> NORMALISE -> LIMIT, and it is the load-bearing part (I-6). Cut
+ * first and a secret that straddles the cut leaves a prefix shorter than the
+ * redaction patterns' minimum length: the half-key sails through into the
+ * transcript, the session file and the exit replay.
+ */
+/**
+ * The renderer, the height estimate and the loader all read THESE numbers (I-4).
+ * A card's height is a function of its data and these limits, so it is bounded:
+ * header + `inputMaxLines` + hidden tail + note.
+ */
+export const INVOCATION_LIMITS = {
+    commandLineMaxChars: 2000,
+    inputMaxChars: 480,
+    inputMaxLines: 8,
+    nameMaxChars: 64,
+    factsMax: 5,
+    factMaxChars: 28,
+    noteMaxChars: 140,
+};
+const VARIANTS = ['skill', 'team', 'todo', 'govern'];
+// C0 except TAB (\x09) and LF (\x0a), then DEL and C1 (which includes the 8-bit CSI
+// \x9b). Matches the range `QueueOverlay` strips, so the card is no more permissive.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+const CAP_MARK = '...';
+/** Cut at a code-point boundary: a surrogate pair is never split. */
+function sliceCodePoints(text, count) {
+    if (count <= 0)
+        return '';
+    if (text.length <= count)
+        return text;
+    let end = count;
+    const last = text.charCodeAt(end - 1);
+    // A high surrogate at the cut would orphan its low half.
+    if (last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return text.slice(0, end);
+}
+function countCodePoints(text) {
+    let count = 0;
+    for (const _ of text)
+        count += 1;
+    return count;
+}
+/** CRLF and bare CR to LF (a bare CR returns Ink's cursor to column 0), then strip controls. */
+function normalizeText(text) {
+    return text.replace(/\r\n?/g, '\n').replace(CONTROL_CHARS, '');
+}
+function capCommandLine(text) {
+    const max = INVOCATION_LIMITS.commandLineMaxChars;
+    if (text.length <= max)
+        return text;
+    return sliceCodePoints(text, max - CAP_MARK.length) + CAP_MARK;
+}
+function capInput(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return { input: '', hidden: 0 };
+    const lines = trimmed.split('\n');
+    let kept = lines.length > INVOCATION_LIMITS.inputMaxLines
+        ? lines.slice(0, INVOCATION_LIMITS.inputMaxLines).join('\n') : trimmed;
+    kept = sliceCodePoints(kept, INVOCATION_LIMITS.inputMaxChars).trimEnd();
+    return { input: kept, hidden: countCodePoints(trimmed) - countCodePoints(kept) };
+}
+function capSingleLine(text, max) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (countCodePoints(flat) <= max)
+        return flat;
+    return sliceCodePoints(flat, max - CAP_MARK.length) + CAP_MARK;
+}
+function capFacts(facts) {
+    return facts
+        .map((fact) => capSingleLine(fact, INVOCATION_LIMITS.factMaxChars))
+        .filter((fact) => fact !== '')
+        .slice(0, INVOCATION_LIMITS.factsMax);
+}
+function capNote(note) {
+    if (note === undefined)
+        return undefined;
+    const capped = capSingleLine(note, INVOCATION_LIMITS.noteMaxChars);
+    return capped === '' ? undefined : capped;
+}
+/** Shared by the write path and the load path so the two cannot diverge. */
+function assemble(parts) {
+    const { input, hidden } = capInput(normalizeText(parts.input));
+    const note = capNote(normalizeText(parts.note ?? ''));
+    return {
+        variant: parts.variant,
+        name: capSingleLine(normalizeText(parts.name), INVOCATION_LIMITS.nameMaxChars),
+        commandLine: capCommandLine(normalizeText(parts.commandLine).trim()),
+        input,
+        inputHidden: hidden,
+        facts: capFacts(parts.facts.map(normalizeText)),
+        ...(note !== undefined ? { note } : {}),
+    };
+}
+/**
+ * Total, never throws. `redact` is injected (the same closure `Command:` echo uses) so
+ * this module depends on nothing; the default is the identity for tests and the loader.
+ */
+export function buildInvocationCard(input, redact = (text) => text) {
+    const scrub = (text) => {
+        if (text === undefined)
+            return '';
+        try {
+            return redact(text);
+        }
+        catch {
+            return '';
+        }
+    };
+    return assemble({
+        variant: input.variant,
+        name: scrub(input.name),
+        commandLine: scrub(input.commandLine),
+        input: scrub(input.input),
+        facts: (input.facts ?? []).map((fact) => scrub(fact)),
+        note: input.note === undefined ? undefined : scrub(input.note),
+    });
+}
+function asString(value) {
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Session-load path: `null` for anything that is not a plausible card, so the caller
+ * drops the field and the entry degrades to a plain user message (I-7). Re-derives
+ * `inputHidden` from nothing - it trusts the stored count only when it is a sane integer.
+ */
+export function sanitizeInvocationCard(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    const variant = VARIANTS.find((candidate) => candidate === raw.variant);
+    const commandLine = asString(raw.commandLine);
+    if (variant === undefined || commandLine === null)
+        return null;
+    const name = asString(raw.name) ?? '';
+    const input = asString(raw.input) ?? '';
+    const facts = Array.isArray(raw.facts)
+        ? raw.facts.filter((fact) => typeof fact === 'string') : [];
+    const note = asString(raw.note) ?? undefined;
+    const card = assemble({ variant, name, commandLine, input, facts, note });
+    // A stored card that was already capped must keep its recorded `inputHidden`; the
+    // re-cap above can only ever add to it.
+    const stored = raw.inputHidden;
+    const storedHidden = typeof stored === 'number' && Number.isInteger(stored) && stored > 0
+        ? Math.min(stored, 10_000_000) : 0;
+    return { ...card, inputHidden: Math.max(card.inputHidden, storedHidden) };
+}
+/**
+ * Emergency kill switch (`ARAGON_NO_INVOCATION_CARDS=1`): every command and the App fall
+ * back to the pre-card behaviour. Read at call time, not import time, so a test (or a
+ * wrapper script) that sets the variable after load is honoured.
+ */
+export function invocationCardsEnabled(env = process.env) {
+    return env.ARAGON_NO_INVOCATION_CARDS !== '1';
+}

package/dist/model/agent/model-probe-limits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Structural bounds for the profile connection probe (model-profile-connection-test §7).
+ *
+ * STRUCTURAL, NOT POLICY: nothing here is clamped, persisted or user-tunable. These
+ * are the physical limits of one probe - how long a single round trip may take, how
+ * many lines and characters a result may occupy, how many models a list page can
+ * carry before it must truncate. The user-tunable keys live in `config/schema.ts`.
+ *
+ * THE OUTPUT-TOKEN CAP IS DELIBERATELY ABSENT. It must come from core's
+ * `MIN_MAX_OUTPUT_TOKENS`, or this file becomes a second authority for "how many
+ * tokens may this model produce" - which is exactly what `output-limits.ts` exists
+ * to prevent.
+ *
+ * ASCII ONLY: this module lives in `agent/`, which `glyphs.test.ts::inScope` scans.
+ */
+export interface ProbeLimits {
+    /** Ceiling on ONE real round trip (`complete`). */
+    testTimeoutMs: number;
+    /**
+     * Sub-budget for the best-effort model list that runs CONCURRENTLY with the
+     * completion. It never decides the verdict (§4.3 / RV-P1-1): a slow `/models`
+     * that ate the adapter's own 15 s discovery timeout would turn a healthy
+     * connection into a false `timeout`.
+     */
+    listModelsBudgetMs: number;
+    /** Ceiling on a discovery (`listModels`) issued from the list page. */
+    discoveryTimeoutMs: number;
+    /** Characters of the model's reply kept for the `Reply:` line. */
+    replyChars: number;
+    /** Characters of a locally composed failure sentence. */
+    detailChars: number;
+    /** Rows a list page may carry before `truncated` becomes true. */
+    maxListedModels: number;
+    /** Above this many rows the list page grows a search line (picker parity). */
+    searchThreshold: number;
+    /** Characters of a model's display name kept in one list row. */
+    maxNameChars: number;
+}
+export declare const PROBE_LIMITS: ProbeLimits;

package/dist/model/agent/model-probe-limits.js

@@ -0,0 +1,25 @@
+/**
+ * Structural bounds for the profile connection probe (model-profile-connection-test §7).
+ *
+ * STRUCTURAL, NOT POLICY: nothing here is clamped, persisted or user-tunable. These
+ * are the physical limits of one probe - how long a single round trip may take, how
+ * many lines and characters a result may occupy, how many models a list page can
+ * carry before it must truncate. The user-tunable keys live in `config/schema.ts`.
+ *
+ * THE OUTPUT-TOKEN CAP IS DELIBERATELY ABSENT. It must come from core's
+ * `MIN_MAX_OUTPUT_TOKENS`, or this file becomes a second authority for "how many
+ * tokens may this model produce" - which is exactly what `output-limits.ts` exists
+ * to prevent.
+ *
+ * ASCII ONLY: this module lives in `agent/`, which `glyphs.test.ts::inScope` scans.
+ */
+export const PROBE_LIMITS = {
+    testTimeoutMs: 20_000,
+    listModelsBudgetMs: 5_000,
+    discoveryTimeoutMs: 20_000,
+    replyChars: 60,
+    detailChars: 160,
+    maxListedModels: 400,
+    searchThreshold: 8,
+    maxNameChars: 48,
+};

package/dist/model/agent/model-probe.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The connection probe behind `Test connection` and `Discover models`
+ * (model-profile-connection-test §4.2-§4.8).
+ *
+ * WHY THIS IS NOT `ModelRegistry.discoverModels()`: that path folds every exception
+ * into `[]` and stores the result in a five-minute process-wide cache. Using it here
+ * would (a) collapse "wrong key", "wrong URL" and "this account owns no models" into
+ * one sentence, and (b) let a probe of an UNSAVED draft endpoint poison `/model`,
+ * `/context` and the main session's window resolution for five minutes. So the probe
+ * talks to the adapter directly and classifies by `LLMError.errorType`.
+ *
+ * WHY `complete()` AND NOT ONLY `listModels()`: a model can be listed and still be
+ * unable to generate (gateway aliases, permission layers). One real round trip is the
+ * only honest answer to "does this work right now", and it is also the only evidence
+ * that can produce `model_not_found`.
+ *
+ * ASCII ONLY: `agent/` is inside `glyphs.test.ts::inScope`.
+ */
+import { type ProviderRegistry } from '@aragon-agent/core';
+/** Every way a probe can fail, once and for all (§7). */
+export type ProbeFailureKind = 'missing_key' | 'unsupported_provider' | 'invalid_base_url' | 'auth' | 'model_not_found' | 'invalid_request' | 'rate_limit' | 'provider_unavailable' | 'network' | 'timeout' | 'cancelled' | 'unknown';
+export interface ProbeTarget {
+    provider: string;
+    /** `''` means "no model typed yet" - the probe then only lists models. */
+    model: string;
+    baseUrl: string | null;
+    /** The RESOLVED plaintext key from `resolveDraftKey()`, never `editor.apiKey`. */
+    apiKey: string | null;
+}
+export interface ProbeRequest extends ProbeTarget {
+    signal?: AbortSignal;
+}
+export interface ProbeOutcome {
+    ok: boolean;
+    /** Fingerprint of the target this outcome describes (§4.6). */
+    targetId: string;
+    latencyMs: number;
+    kind?: ProbeFailureKind;
+    /** Locally composed, already redacted sentence. Never provider response text. */
+    detail?: string;
+    reply?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    availableModels?: number;
+    modelListed?: boolean;
+}
+export interface ModelCandidate {
+    id: string;
+    name: string;
+    contextWindow?: number;
+    supportsTools: boolean;
+}
+export interface DiscoveryOutcome {
+    ok: boolean;
+    connectionId: string;
+    kind?: ProbeFailureKind;
+    detail?: string;
+    models: ModelCandidate[];
+    truncated: boolean;
+    /**
+     * How many models the endpoint returned BEFORE truncation. The truncation line
+     * needs the real number ("Showing first 400 of 960"), and re-deriving it from a
+     * clamped array is impossible.
+     */
+    total?: number;
+}
+export interface ModelProbe {
+    test(request: ProbeRequest): Promise<ProbeOutcome>;
+    discover(request: ProbeRequest): Promise<DiscoveryOutcome>;
+    targetFingerprint(target: ProbeTarget): string;
+    connectionFingerprint(target: ProbeTarget): string;
+}
+export interface ProbeDeps {
+    registry: Pick<ProviderRegistry, 'get'>;
+    /** Injected clock; tests pin `latencyMs` through it. */
+    now?: () => number;
+}
+/**
+ * Which key this draft would actually use (§4.2.1).
+ *
+ * The editor's `apiKey` field is ALWAYS the empty string: it is the replacement
+ * input, not the live credential. `finishProfileEditor` resolves `keep` to the
+ * saved entry key and `shared` to `null`, and the runtime then falls back to the
+ * shared per-provider key. Without this table the most common path - editing an
+ * existing profile, whose credential mode defaults to `keep` - would report
+ * `(no key)` for a profile that has one.
+ */
+export declare function resolveDraftKey(input: {
+    credentialMode: 'keep' | 'replace' | 'shared';
+    draftKey: string;
+    existingKey: string | null;
+    sharedKey?: string;
+}): string | null;
+/**
+ * The host a failure sentence names - same four clauses as
+ * `profileEndpointSummary()` in `ui/overlays/ModelProfilePicker.tsx`, which this
+ * layer may not import (agent -> ui would invert the layering). `model-probe.test.ts`
+ * asserts the two agree, so the duplication cannot drift silently.
+ */
+export declare function endpointHost(baseUrl: string | null): string;
+/** Create the probe port. One instance per App; `SettingsScreen` only passes it down. */
+export declare function createModelProbe(deps: ProbeDeps): ModelProbe;