@aragon-agent/cli 0.6.33 → 0.6.35

package/dist/config/kit-resolution.js

@@ -0,0 +1,226 @@
+/**
+ * Where the ACTIVE kit comes from, and the two places a session kit has to be
+ * re-applied (agent-model-kits §4.3 / D-5 / D-6).
+ *
+ * ASCII ONLY - `src/config/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * ONE TRUTH, PURELY DERIVED. `CliConfig` carries only `sessionKit: {id, held}`;
+ * everything a surface prints about "which kit is running" comes out of
+ * `resolveActiveKit(config)`. There is no `config.activeKit` field, because a
+ * second copy of that answer is a copy that can disagree with the first.
+ */
+import { getLogger } from '../logging/logger.js';
+import { normalizeProfileBaseUrl, projectModelProfiles, resolveModelProfileState } from './model-profile-resolution.js';
+import { findKit, kitCandidate, kitSlotConnections } from './model-kits.js';
+/** The three slots, in the order every surface prints them. */
+export const ALL_SLOTS = ['main', 'fast', 'subagent'];
+/** The name the UI gives "no kit is in effect" (D-13). */
+export const CURRENT_SETUP_NAME = 'Current setup';
+/**
+ * The answer when there is no kit, or when the host has no kit support at all.
+ *
+ * A CONSTANT SO CALLERS CANNOT INVENT A SECOND SHAPE: `App` needs one value that
+ * renders "no chip, `Current setup` row" for a controller that predates this
+ * port (a test double, an embedded host), and re-deriving it there would be a
+ * second definition of "nothing".
+ */
+export const INACTIVE_KIT = { source: 'none', id: null,
+    name: CURRENT_SETUP_NAME, held: [], modified: false, driftReasons: [],
+    missingProfiles: [] };
+function driftOfMain(config, connection) {
+    if (!connection)
+        return [];
+    const changed = [];
+    if (config.provider !== connection.provider)
+        changed.push('provider');
+    if (config.model !== connection.model)
+        changed.push('model');
+    if (normalizeProfileBaseUrl(config.baseUrl) !== normalizeProfileBaseUrl(connection.baseUrl)) {
+        changed.push('endpoint');
+    }
+    return changed.length ? [`main: ${changed.join(', ')} changed`] : [];
+}
+function driftOfFast(config, kit, connection) {
+    if (kit.fastProfileId === null) {
+        // D-8: this kit TURNS THE TIER OFF, so the endpoints are irrelevant - only
+        // "is it on" can disagree. Comparing endpoints here would report drift for
+        // every user who ever ran a fast tier before applying a fast-off kit.
+        return config.fast.enabled ? ['fast: turned back on'] : [];
+    }
+    if (!connection)
+        return [];
+    const changed = [];
+    if (!config.fast.enabled)
+        changed.push('off');
+    if (config.fast.provider !== connection.provider)
+        changed.push('provider');
+    if (config.fast.model !== connection.model)
+        changed.push('model');
+    if (normalizeProfileBaseUrl(config.fast.baseUrl)
+        !== normalizeProfileBaseUrl(connection.baseUrl))
+        changed.push('endpoint');
+    return changed.length ? [`fast: ${changed.join(', ')} changed`] : [];
+}
+function driftOfSubagent(config, kit, connection) {
+    if (!connection)
+        return [];
+    const sameMode = config.team?.model === kit.subagent.model;
+    const sameId = kit.subagent.model === 'profile'
+        ? (config.team?.modelProfileId ?? null) === kit.subagent.modelProfileId : true;
+    return sameMode && sameId ? [] : ['subagent: changed'];
+}
+function subagentConnection(config, kit) {
+    if (kit.subagent.model === 'profile')
+        return kit.subagent.modelProfileId;
+    return kit.subagent.model === 'main' ? 'main' : 'fast';
+}
+/** Build the verdict for a kit that exists, whatever installed it. */
+function describe(config, library, kit, source, held) {
+    const connections = kitSlotConnections(library, kit);
+    const drift = { reasons: [], missing: [] };
+    if (held.includes('main')) {
+        if (!connections.main)
+            drift.missing.push('main');
+        else
+            drift.reasons.push(...driftOfMain(config, connections.main));
+    }
+    if (held.includes('fast')) {
+        if (kit.fastProfileId !== null && !connections.fast)
+            drift.missing.push('fast');
+        else
+            drift.reasons.push(...driftOfFast(config, kit, connections.fast));
+    }
+    if (held.includes('subagent')) {
+        const missingProfile = kit.subagent.model === 'profile' && !connections.subagent.name;
+        if (missingProfile)
+            drift.missing.push('subagent');
+        else
+            drift.reasons.push(...driftOfSubagent(config, kit, subagentConnection(config, kit)));
+    }
+    if (held.length < ALL_SLOTS.length)
+        drift.reasons.push(`holds ${held.join('+') || 'nothing'}`);
+    return { source, id: kit.id, name: kit.name, held: [...held],
+        modified: held.length < ALL_SLOTS.length || drift.reasons.length > 0
+            || drift.missing.length > 0,
+        driftReasons: drift.reasons, missingProfiles: drift.missing };
+}
+/**
+ * Which kit is in effect, and whether it has drifted (§4.8).
+ *
+ * Precedence is D-6's: session kit, then the persisted default, then the disk
+ * bindings (which the UI calls `Current setup`).
+ */
+export function resolveActiveKit(config) {
+    const library = config.modelProfiles;
+    const state = config.sessionKit;
+    const session = state ? findKit(library, state.id) : undefined;
+    if (state && session) {
+        const held = state.held.filter((slot) => ALL_SLOTS.includes(slot));
+        return describe(config, library, session, 'session', held.length ? held : []);
+    }
+    const fallback = findKit(library, library?.defaultKitId ?? null);
+    if (library && fallback)
+        return describe(config, library, fallback, 'default', [...ALL_SLOTS]);
+    return { source: 'none', id: null, name: CURRENT_SETUP_NAME, held: [], modified: false,
+        driftReasons: [], missingProfiles: [] };
+}
+function slotSurvives(library, kit, slot) {
+    const ids = new Set(library.entries.map((entry) => entry.id));
+    if (slot === 'main')
+        return ids.has(kit.mainProfileId);
+    if (slot === 'fast')
+        return kit.fastProfileId === null || ids.has(kit.fastProfileId);
+    return kit.subagent.model !== 'profile'
+        || (!!kit.subagent.modelProfileId && ids.has(kit.subagent.modelProfileId));
+}
+/**
+ * Re-apply the still-`held` slots of a session kit onto a candidate.
+ *
+ * THE RETURN VALUE MAY ONLY EVER FEED `liveCandidate`. It must NEVER be handed
+ * to `commitModelSettings` (I-14 / RV-P0-1): "this session only" is a claim
+ * about the FILE, and a held slot that reaches the commit turns one unrelated
+ * save into a permanent, invisible change of the user's defaults. The one
+ * caller is `prepareModelSettings` in `agent/model-profile-settings.ts`, which
+ * keeps the two candidates in separate variables for exactly this reason.
+ *
+ * Slots whose kit, or whose referenced profile, disappeared are DROPPED and
+ * reported, so the caller can log the release instead of silently forgetting it.
+ */
+export function applyHeldToLive(candidate, sessionKit) {
+    const heldIn = sessionKit?.held ?? [];
+    if (!sessionKit || heldIn.length === 0)
+        return { candidate, dropped: [] };
+    const library = candidate.modelProfiles;
+    const kit = findKit(library, sessionKit.id);
+    if (!library || !kit)
+        return { candidate, dropped: [...heldIn] };
+    const held = heldIn.filter((slot) => slotSurvives(library, kit, slot));
+    const dropped = heldIn.filter((slot) => !held.includes(slot));
+    if (!held.length)
+        return { candidate, dropped };
+    const patch = kitCandidate({ library, kit });
+    const next = {
+        ...candidate,
+        modelProfiles: { ...library,
+            ...(held.includes('main') ? { mainId: kit.mainProfileId } : {}),
+            ...(held.includes('fast') ? { fastId: kit.fastProfileId } : {}) },
+    };
+    if (held.includes('subagent')) {
+        next.team = { ...candidate.team, ...patch.team };
+    }
+    if (held.includes('fast')) {
+        next.fast = { ...candidate.fast, enabled: kit.fastProfileId !== null };
+    }
+    return { candidate: next, dropped };
+}
+/**
+ * Keep a session kit alive across `Reload settings` (D-6).
+ *
+ * THE PROJECTION HAS TO BE RECOMPUTED, not just the bindings: `I-3` says a
+ * library's projections never depend on whether a kit exists, so a live config
+ * whose `mainId` says "kit" while `provider`/`model` still name the reloaded
+ * file would break the equivalence every other surface relies on. Hence the
+ * round trip through `projectModelProfiles` + `resolveModelProfileState`.
+ */
+export function carrySessionKit(input) {
+    const state = input.previous.sessionKit;
+    const { resolved } = input;
+    if (!state)
+        return resolved;
+    const library = resolved.modelProfiles;
+    const kit = findKit(library, state.id);
+    if (!library || !kit) {
+        getLogger().warn('config', 'session_kit_released', { reason: 'kit_missing' });
+        return { ...resolved, sessionKit: undefined };
+    }
+    const applied = applyHeldToLive(resolved, state);
+    const held = state.held.filter((slot) => !applied.dropped.includes(slot));
+    if (!held.length) {
+        getLogger().warn('config', 'session_kit_released', { reason: 'slots_dropped' });
+        return { ...resolved, sessionKit: undefined };
+    }
+    const file = applied.candidate;
+    const projected = projectModelProfiles(file).file;
+    const next = { ...resolved, modelProfiles: projected.modelProfiles };
+    if (held.includes('main')) {
+        next.provider = projected.provider;
+        next.model = projected.model;
+        next.baseUrl = projected.baseUrl ?? undefined;
+        if (next.contextWindowOrigin !== 'env') {
+            next.contextWindow = projected.contextWindow ?? null;
+            next.contextWindowOrigin = next.contextWindow === null ? undefined : 'profile';
+        }
+    }
+    if (held.includes('fast') && projected.fast) {
+        next.fast = { ...next.fast, provider: projected.fast.provider ?? '',
+            model: projected.fast.model ?? '', baseUrl: projected.fast.baseUrl ?? '' };
+    }
+    if (held.includes('subagent') && file.team)
+        next.team = { ...next.team, ...file.team };
+    next.modelProfileState = resolveModelProfileState(next);
+    next.sessionKit = { id: kit.id, held };
+    if (applied.dropped.length) {
+        getLogger().warn('config', 'session_kit_slots_dropped', { slots: applied.dropped });
+    }
+    return next;
+}

package/dist/config/model-kits.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Agent model kits: a named preset that pins the THREE model roles
+ * (main / fast / subagent) to profiles that already live in the library
+ * (agent-model-kits D-1 / D-2).
+ *
+ * ASCII ONLY - `src/config/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * A KIT STORES REFERENCES, NEVER COPIES (D-1): every slot is a profile id, so
+ * editing the profile changes the meaning of every kit that names it, which is
+ * exactly the promise a "preset" makes. That is also why deleting a profile has
+ * to delete the kits that reference it (D-9) instead of leaving a preset nobody
+ * can repair from the UI.
+ *
+ * EVERY CROSS-LAYER IMPORT HERE IS `import type` (RV-P2-5): `schema.ts` names
+ * `model-profiles.ts` through an inline `import('./model-profiles.js')` type
+ * query, so `model-profiles -> model-kits -> schema` is already a TYPE cycle. A
+ * value import (`DEFAULT_FAST_CONFIG`, `clampTeamConfig`) would turn it into a
+ * runtime cycle, and vitest surfaces that as an empty module at import time.
+ */
+import type { CliConfig, FastConfig, TeamConfig } from './schema.js';
+import type { ModelProfilesConfig, ProfileValidationIssue } from './model-profiles.js';
+import type { ModelSettingsSaveResult } from './model-profile-store.js';
+export type KitSlot = 'main' | 'fast' | 'subagent';
+/**
+ * The session kit's runtime shape (D-5): the kit plus the slots it still owns.
+ *
+ * `held` is the ONLY mutable part. It shrinks when a save explicitly decides a
+ * slot (§4.3 / D-6), so "the user changed subagent, so subagent is theirs now"
+ * needs no second bookkeeping structure.
+ */
+export interface SessionKitState {
+    id: string;
+    held: KitSlot[];
+}
+/**
+ * The kit's subagent slot.
+ *
+ * `model` is typed with `TeamConfig['model']` rather than by importing
+ * `team/model.ts`: `team/model.ts` already imports `config/`, so the reverse
+ * edge would be a cycle. `import type` keeps even this one erased.
+ */
+export interface AgentKitSubagent {
+    model: TeamConfig['model'];
+    /** Non-null IF AND ONLY IF `model === 'profile'` (I-2, guaranteed by normalize). */
+    modelProfileId: string | null;
+}
+export interface AgentKit {
+    id: string;
+    /** 1..48 code points, no control characters. Names MAY repeat (§6.6). */
+    name: string;
+    /** Required (D-8). A dangling reference is NOT a validation error - see I-8. */
+    mainProfileId: string;
+    /** `null` = this kit turns the fast tier OFF for its session (D-8). */
+    fastProfileId: string | null;
+    subagent: AgentKitSubagent;
+}
+export declare const KIT_LIMITS: {
+    /**
+     * Structural ceiling. The EFFECTIVE ceiling is lower and implicit: every kit
+     * references at least one profile, so 200 entries cap the reachable kits
+     * (RV-P2-7) - recorded, not cross-validated, because the two numbers answer
+     * different questions.
+     */
+    readonly maxKits: 50;
+    readonly nameMaxChars: 48;
+    readonly maxSlots: 3;
+};
+/**
+ * STRUCTURAL ONLY (RV-P1-1). Reference existence is a RESOLUTION-time concern,
+ * exactly as it is for `team.modelProfileId` (`schema.ts` clampTeamConfig):
+ * `createModelProfileState` blanks the whole settings page when validation
+ * fails, so promoting "a hand-edited file left one dangling id" into "the page
+ * and `/team model` are both dead" is a wildly disproportionate blast radius.
+ *
+ * `duplicate_name` is deliberately NOT a code: two kits may share a name
+ * (§6.6), and `/kit use` disambiguates with an `#id` prefix.
+ */
+export interface KitIssue {
+    path: string;
+    code: 'invalid' | 'duplicate_id';
+    message: string;
+}
+/** One resolved slot; `null` on the slot itself means the entry is gone. */
+export interface KitConnection {
+    provider: string;
+    model: string;
+    baseUrl: string | null;
+    name: string;
+}
+export interface KitSlotConnections {
+    /** `null` = the referenced entry is gone; render `Profile missing`, never throw. */
+    main: KitConnection | null;
+    fast: KitConnection | null;
+    subagent: {
+        /**
+         * The SLOT MODE (`main` / `fast` / `profile`). Named `mode` rather than
+         * `model` because the resolved connection below carries a model ID of its
+         * own, and two `model` keys in one object literal is a TypeScript error
+         * (recorded as an implementation-time fix in the spec's issues section).
+         */
+        mode: TeamConfig['model'];
+        provider: string | null;
+        model: string | null;
+        baseUrl: string | null;
+        name: string | null;
+    };
+}
+/**
+ * A consequence of applying a kit that the user MUST be told about (§4.2).
+ *
+ * Not one of these is a failure: applying a kit is allowed to turn the fast tier
+ * on (which is real money - `DEFAULT_FAST_CONFIG.review` is `true`), to leave a
+ * profile without a usable key, or to name a tier this kit just switched off.
+ * The rule is the one every other subsystem in this package follows: no silent
+ * decisions, especially about spend.
+ */
+export type KitNote = 'fast_tier_enabled' | 'fast_review_enabled' | 'fast_tier_off' | 'restart_required' | 'main_key_missing' | 'subagent_key_missing' | 'subagent_fast_unavailable';
+/**
+ * What a session-kit action did, or why it did nothing.
+ *
+ * THE CODE SET IS THE SAVE SET PLUS TWO (RV-P1-3): every code the reused
+ * prepare/commit chain can produce is spelled here, so `kitApplyMessage` has no
+ * gap to fall through. A missing message would be rendered by a non-null
+ * assertion as the literal string `undefined`.
+ */
+export interface KitApplyResult {
+    ok: boolean;
+    code?: ModelSettingsSaveResult['code'] | 'kit_missing' | 'kit_references_missing_profile';
+    /** `clearSessionKit` only: the session is back on the config file. */
+    released?: boolean;
+    notes: KitNote[];
+    /** Set when `kit_references_missing_profile` refused the apply (I-8). */
+    issues?: ProfileValidationIssue[];
+}
+export interface KitsNormalization {
+    kits: AgentKit[];
+    /** Self-healed: a pointer at a kit that did not survive becomes `null`. */
+    defaultKitId: string | null;
+    /** Forward migration marker (D-3). Never anything but 1. */
+    kitsVersion: 1;
+    /** Entries thrown away because they were structurally unsalvageable. */
+    dropped: number;
+}
+export declare const SUBAGENT_MODES: readonly ["main", "fast", "profile"];
+/** The one mapping from a kit to a persisted-config patch (§4.2). */
+export interface KitCandidate {
+    modelProfiles: ModelProfilesConfig;
+    team: Partial<TeamConfig>;
+    fast: Partial<FastConfig>;
+}
+/**
+ * Validate the `kits` array STRUCTURALLY (RV-P1-1).
+ *
+ * Returns `[]` for `undefined`/`null`/`[]` so a library written by a pre-KIT
+ * build keeps validating - the whole point of D-3's additive migration.
+ */
+export declare function validateKits(value: unknown): KitIssue[];
+/**
+ * White-list normalization of `kits` + `defaultKitId` (F-3 / R-2).
+ *
+ * TOTAL: no input throws. `normalizeModelProfiles` calls this on whatever the
+ * file holds, and a throw there would take the whole library - including the
+ * user's credentials - down with one malformed kit.
+ *
+ * `defaultKitRef` is a SEPARATE argument because `defaultKitId` is a sibling of
+ * `kits` in the library, not a member of the array; keeping it here is what
+ * lets the pointer self-heal against the kits that actually survived.
+ */
+export declare function normalizeKits(kitsValue: unknown, defaultKitRef?: unknown): KitsNormalization;
+/** Create a kit with a stable UUID, normalized like `createModelProfile`. */
+export declare function createAgentKit(input: Omit<AgentKit, 'id'>): AgentKit;
+/** Copy a kit under a free ` (copy)` name - the manager's `Duplicate` action. */
+export declare function duplicateAgentKit(kit: AgentKit, existing: readonly AgentKit[]): AgentKit;
+/**
+ * Every kit a reference text may mean.
+ *
+ * ONE parser for `ctrl+K`, `/kit use` and the settings manager, so "what did I
+ * just type" has a single answer. `ref` is an exact id, an `#id` prefix, or an
+ * exact name; an ambiguous reference returns more than one hit and the caller
+ * reports it rather than silently taking the first (§4.9).
+ */
+export declare function kitMatches(library: ModelProfilesConfig | undefined, ref: string | null | undefined): AgentKit[];
+/** Resolve one kit, or `undefined` when the reference is missing or ambiguous. */
+export declare function findKit(library: ModelProfilesConfig | undefined, ref: string | null | undefined): AgentKit | undefined;
+/**
+ * THE ONE mapping from a kit to a persisted-config patch (§4.2).
+ *
+ * Both consumption paths - "set as default" (writes the result) and `ctrl+K`
+ * (never writes it) - call this, so a default kit and a session kit produce
+ * structurally identical configurations. There is no second interpretation.
+ *
+ * `defaultKitId` is only touched when the caller PASSES it (it is
+ * `undefined` for a session kit), which is what keeps `ctrl+K` from moving the
+ * persisted pointer.
+ */
+export declare function kitCandidate(input: {
+    library: ModelProfilesConfig;
+    kit: AgentKit;
+    defaultKitId?: string | null;
+}): KitCandidate;
+/**
+ * Dereference the three slots for every surface that prints them (picker,
+ * management page, `/kit list`).
+ *
+ * A MISSING ENTRY RETURNS `null` INSTEAD OF THROWING (RV-P1-1 / I-8): the UI
+ * renders `Profile missing`, the library stays readable, and only APPLYING the
+ * kit is refused, with a stable code.
+ */
+export declare function kitSlotConnections(library: ModelProfilesConfig | undefined, kit: AgentKit): KitSlotConnections;
+/**
+ * Pre-fill the first kit from what this machine already runs (§4.10 / D-13).
+ *
+ * `mainProfileId` comes from the caller because CREATING a profile is UI work:
+ * `createCustomProfile` lives in `ui/overlays/model-profile-state.ts`, and a
+ * `config/` module importing `ui/` would invert the dependency direction this
+ * package keeps everywhere else. The caller creates (or reuses) the entry and
+ * hands its id in; when it is absent the kit is still built, because a
+ * half-filled editor is a better first form than an empty one.
+ */
+export declare function createKitFromCurrent(input: {
+    config: CliConfig;
+    mainProfileId?: string | null;
+    name?: string;
+}): AgentKit;