@aragon-agent/cli 0.6.34 → 0.6.35

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;

package/dist/config/model-kits.js

@@ -0,0 +1,302 @@
+/**
+ * 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 { randomUUID } from 'node:crypto';
+export 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.
+     */
+    maxKits: 50,
+    nameMaxChars: 48,
+    maxSlots: 3,
+};
+export const SUBAGENT_MODES = ['main', 'fast', 'profile'];
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Non-empty, control-free text of at most `max` code points. */
+function validText(value, max) {
+    if (typeof value !== 'string' || CONTROL.test(value))
+        return false;
+    const points = [...value.trim()].length;
+    return points > 0 && points <= max;
+}
+function invalidKit(path, message) {
+    return { path, code: 'invalid', message };
+}
+function validateKitSubagent(value, path) {
+    if (!isRecord(value))
+        return [invalidKit(`${path}.subagent`, 'Subagent must be an object.')];
+    const issues = [];
+    if (!SUBAGENT_MODES.includes(value.model)) {
+        issues.push(invalidKit(`${path}.subagent.model`, 'Subagent model must be main, fast or profile.'));
+    }
+    const id = value.modelProfileId;
+    if (id !== null && !validText(id, 128)) {
+        issues.push(invalidKit(`${path}.subagent.modelProfileId`, 'Subagent profile must be empty or 1-128 safe characters.'));
+    }
+    return issues;
+}
+function validateKit(value, index) {
+    const path = `modelProfiles.kits[${index}]`;
+    if (!isRecord(value))
+        return [invalidKit(path, 'Kit must be an object.')];
+    const issues = [];
+    if (!validText(value.id, 128)) {
+        issues.push(invalidKit(`${path}.id`, 'Kit ID must have 1-128 safe characters.'));
+    }
+    if (!validText(value.name, KIT_LIMITS.nameMaxChars)) {
+        issues.push(invalidKit(`${path}.name`, `Kit name must have 1-${KIT_LIMITS.nameMaxChars} safe characters.`));
+    }
+    if (!validText(value.mainProfileId, 128)) {
+        issues.push(invalidKit(`${path}.mainProfileId`, 'Choose a main profile for this kit.'));
+    }
+    const fast = value.fastProfileId;
+    if (fast !== null && !validText(fast, 128)) {
+        issues.push(invalidKit(`${path}.fastProfileId`, 'Fast profile must be a profile or off.'));
+    }
+    issues.push(...validateKitSubagent(value.subagent, path));
+    return issues;
+}
+/**
+ * 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 function validateKits(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        return [invalidKit('modelProfiles.kits', 'Kits must be an array.')];
+    }
+    if (value.length > KIT_LIMITS.maxKits) {
+        return [invalidKit('modelProfiles.kits', `Use at most ${KIT_LIMITS.maxKits} kits; delete unused kits to add more.`)];
+    }
+    const issues = value.flatMap(validateKit);
+    const ids = new Set();
+    value.forEach((kit, index) => {
+        if (!isRecord(kit) || typeof kit.id !== 'string')
+            return;
+        if (ids.has(kit.id)) {
+            issues.push({ path: `modelProfiles.kits[${index}].id`, code: 'duplicate_id',
+                message: 'Kit IDs must be unique.' });
+        }
+        ids.add(kit.id);
+    });
+    return issues;
+}
+function normalizeSubagent(value) {
+    const source = isRecord(value) ? value : {};
+    const model = SUBAGENT_MODES.includes(source.model)
+        ? source.model : 'main';
+    // I-2: the id exists exactly when the mode names a profile. A hand-edited
+    // `{model:'fast', modelProfileId:'x'}` therefore heals instead of lingering
+    // as a reference nothing reads.
+    const id = model === 'profile' && validText(source.modelProfileId, 128)
+        ? source.modelProfileId.trim() : null;
+    return { model, modelProfileId: id };
+}
+/** One entry into a safe `AgentKit`, or `null` when it cannot be salvaged. */
+function normalizeKit(value) {
+    if (!isRecord(value))
+        return null;
+    if (!validText(value.id, 128) || !validText(value.name, KIT_LIMITS.nameMaxChars)
+        || !validText(value.mainProfileId, 128))
+        return null;
+    const fast = value.fastProfileId;
+    if (fast !== null && fast !== undefined && !validText(fast, 128))
+        return null;
+    return {
+        id: value.id.trim(),
+        name: value.name.trim(),
+        mainProfileId: value.mainProfileId.trim(),
+        fastProfileId: validText(fast, 128) ? fast.trim() : null,
+        subagent: normalizeSubagent(value.subagent),
+    };
+}
+/**
+ * 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 function normalizeKits(kitsValue, defaultKitRef) {
+    const kits = [];
+    let dropped = 0;
+    if (Array.isArray(kitsValue)) {
+        const seen = new Set();
+        for (const raw of kitsValue.slice(0, KIT_LIMITS.maxKits)) {
+            const kit = normalizeKit(raw);
+            if (!kit || seen.has(kit.id)) {
+                dropped += 1;
+                continue;
+            }
+            seen.add(kit.id);
+            kits.push(kit);
+        }
+        dropped += Math.max(0, kitsValue.length - KIT_LIMITS.maxKits);
+    }
+    else if (kitsValue !== undefined && kitsValue !== null)
+        dropped += 1;
+    const defaultKitId = typeof defaultKitRef === 'string'
+        && kits.some((kit) => kit.id === defaultKitRef) ? defaultKitRef : null;
+    return { kits, defaultKitId, kitsVersion: 1, dropped };
+}
+/** Create a kit with a stable UUID, normalized like `createModelProfile`. */
+export function createAgentKit(input) {
+    const draft = { ...input, id: randomUUID() };
+    return normalizeKit(draft) ?? { ...draft, subagent: normalizeSubagent(draft.subagent) };
+}
+/** Copy a kit under a free ` (copy)` name - the manager's `Duplicate` action. */
+export function duplicateAgentKit(kit, existing) {
+    const taken = new Set(existing.map((other) => other.name));
+    const suffix = [...kit.name].slice(0, KIT_LIMITS.nameMaxChars - 8).join('').trimEnd();
+    let name = `${suffix} (copy)`;
+    for (let copy = 2; taken.has(name); copy += 1)
+        name = `${suffix} (copy ${copy})`;
+    return { ...kit, id: randomUUID(), name: [...name].slice(0, KIT_LIMITS.nameMaxChars).join('') };
+}
+/**
+ * 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 function kitMatches(library, ref) {
+    if (!library || !ref)
+        return [];
+    const kits = library.kits ?? [];
+    const text = ref.trim();
+    if (!text)
+        return [];
+    const exact = kits.find((kit) => kit.id === text);
+    if (exact)
+        return [exact];
+    if (text.startsWith('#')) {
+        const prefix = text.slice(1).trim().toLowerCase();
+        return prefix ? kits.filter((kit) => kit.id.toLowerCase().startsWith(prefix)) : [];
+    }
+    return kits.filter((kit) => kit.name === text);
+}
+/** Resolve one kit, or `undefined` when the reference is missing or ambiguous. */
+export function findKit(library, ref) {
+    const hits = kitMatches(library, ref);
+    return hits.length === 1 ? hits[0] : 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 function kitCandidate(input) {
+    const { library, kit } = input;
+    const profileId = kit.subagent.model === 'profile' ? kit.subagent.modelProfileId : null;
+    return {
+        modelProfiles: {
+            ...library,
+            mainId: kit.mainProfileId,
+            fastId: kit.fastProfileId,
+            ...(input.defaultKitId !== undefined ? { defaultKitId: input.defaultKitId } : {}),
+        },
+        team: { model: kit.subagent.model, modelProfileId: profileId },
+        // D-8: `fastProfileId: null` means OFF, not "leave it alone".
+        fast: { enabled: kit.fastProfileId !== null },
+    };
+}
+function connectionOf(entry) {
+    if (!entry)
+        return null;
+    return { provider: entry.provider, model: entry.model, baseUrl: entry.baseUrl,
+        name: entry.name };
+}
+/**
+ * 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 function kitSlotConnections(library, kit) {
+    const entries = library?.entries ?? [];
+    const find = (id) => id ? entries.find((entry) => entry.id === id) : undefined;
+    const main = find(kit.mainProfileId);
+    const fast = find(kit.fastProfileId);
+    const subProfile = kit.subagent.model === 'profile'
+        ? find(kit.subagent.modelProfileId) : undefined;
+    const target = kit.subagent.model === 'main' ? main
+        : kit.subagent.model === 'fast' ? fast : subProfile;
+    return {
+        main: connectionOf(main),
+        fast: connectionOf(fast),
+        subagent: {
+            mode: kit.subagent.model,
+            provider: target?.provider ?? null,
+            model: target?.model ?? null,
+            baseUrl: target?.baseUrl ?? null,
+            name: target?.name ?? null,
+        },
+    };
+}
+/**
+ * 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 function createKitFromCurrent(input) {
+    const { config } = input;
+    const library = config.modelProfiles;
+    const fastId = config.fast?.enabled === true ? library?.fastId ?? null : null;
+    // THE SUBAGENT PROFILE IS CARRIED, NOT BLANKED (I-2): a machine whose subagent
+    // already runs a specific profile would otherwise be prefilled with mode
+    // `profile` and no id, which `resolveSubagentModel` can only degrade to main -
+    // the prefill would silently change the answer it exists to record.
+    const subagentModel = config.team?.model ?? 'main';
+    const subagentProfileId = subagentModel === 'profile'
+        ? config.team?.modelProfileId ?? null : null;
+    return createAgentKit({
+        name: input.name ?? 'My setup',
+        mainProfileId: input.mainProfileId ?? library?.mainId ?? '',
+        fastProfileId: fastId,
+        subagent: { model: subagentModel, modelProfileId: subagentProfileId },
+    });
+}

package/dist/config/model-profile-store.d.ts

@@ -1,4 +1,5 @@
 import { type ModelProfilesConfig, type ModelRole, type ProfileValidationIssue } from './model-profiles.js';
+import type { SessionKitState } from './model-kits.js';
 import type { CliConfig, CompactionConfig, FastConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
 export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team'>> {
     fast?: Partial<FastConfig>;
@@ -16,6 +17,30 @@ export interface ModelSettingsDraft {
     baseline: PersistedConfig;
     liveBaseline: CliConfig;
     readError?: string;
+    /**
+     * The session kit this transaction carries (agent-model-kits RV-P0-2 / §4.3).
+     *
+     * THREE-STATE, and every state is reachable: `undefined` = "this draft does
+     * not speak about kits" (a legacy caller, `/model`, `config set`);
+     * an object = "the session kit is still in effect and these slots are still
+     * its"; `null` = "this transaction explicitly RELEASES the session kit"
+     * (`Current setup`, `/kit use current`, or a save that decided all three
+     * slots). `createModelSettingsDraft` seeds it from the LIVE config, without
+     * which the object state would be unreachable and any save made from the
+     * settings screen would silently release the kit.
+     */
+    sessionKit?: SessionKitState | null;
+    /**
+     * Set ONLY by `applySessionKit` (agent-model-kits §4.2 exit B).
+     *
+     * IT MEANS "THIS DRAFT IS THE KIT BEING APPLIED". The release rule
+     * (`releasedSlots`) reads `activateRoles` / `patch.team` / binding changes as
+     * "the user decided that slot", and an apply writes all three of those by
+     * definition - so without this marker every apply would immediately release the
+     * slots it just installed. The marker is per-transaction state, never persisted,
+     * and a save from the settings screen never sets it.
+     */
+    sessionKitFresh?: boolean;
 }
 export interface ModelSettingsSaveResult {
     ok: boolean;

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

@@ -1,3 +1,4 @@
+import { type AgentKit } from './model-kits.js';
 export type ModelRole = 'main' | 'fast';
 export interface ModelProfile {
     id: string;
@@ -14,6 +15,16 @@ export interface ModelProfilesConfig {
     entries: ModelProfile[];
     mainId: string | null;
     fastId: string | null;
+    /**
+     * Agent model kits (agent-model-kits D-2). OPTIONAL because a file written by
+     * a pre-KIT build simply has no such key; `emptyModelProfiles` still fills it
+     * in, so every library this build CREATES is explicit.
+     */
+    kits?: AgentKit[];
+    /** The `Set default` pointer (D-13); a dangling value normalizes to null. */
+    defaultKitId?: string | null;
+    /** Forward migration marker (D-3). Always 1; never a functional decision. */
+    kitsVersion?: 1;
 }
 export interface ProfileBindingState {
     selectedId: string | null;
@@ -42,7 +53,16 @@ export declare function emptyModelProfileState(invalid?: boolean): ModelProfiles
  * copy of these four clauses is one edit away from disagreeing with the config layer.
  */
 export declare function isValidEndpointUrl(value: string | null | undefined): boolean;
-/** Validate untrusted input; diagnostics never include supplied values. */
+/**
+ * Validate untrusted input; diagnostics never include supplied values.
+ *
+ * THE KIT SECTION IS STRUCTURAL ONLY (agent-model-kits RV-P1-1). `mainId` /
+ * `fastId` above are `missing_reference` because a dangling ROLE BINDING leaves
+ * the whole library unreadable (there is no "nothing bound" recovery path once
+ * a bound id is gone), while a dangling KIT SLOT degrades at resolution time
+ * into `Profile missing` and a refused apply - the same discipline
+ * `team.modelProfileId` already follows (`schema.ts` clampTeamConfig).
+ */
 export declare function validateModelProfiles(value: unknown): ProfileValidationIssue[];
 /**
  * Disk-tolerance gate for a profile-level context window (profile-context-window 5.3).
@@ -55,11 +75,29 @@ export declare function validateModelProfiles(value: unknown): ProfileValidation
  * (invariant 4 - one bad number must not drop the user's credentials).
  */
 export declare function normalizeProfileContextWindow(value: unknown): number | null;
-/** Normalize a valid library into a safe field whitelist; throws a fixed error if invalid. */
+/**
+ * Normalize a valid library into a safe field whitelist; throws a fixed error if invalid.
+ *
+ * THE THREE KIT KEYS ARE LISTED EXPLICITLY, NEVER `...spread` (R-2): this
+ * literal IS the whitelist (F-3), so a key missing from it disappears at the
+ * next write - a save that only touched `thinking` would silently delete every
+ * kit the user owns. `normalizeKits` is TOTAL, so a hand-edited kit degrades
+ * instead of taking the library (and the credentials in it) with it.
+ */
 export declare function normalizeModelProfiles(value: unknown): ModelProfilesConfig;
 /** Create an entry with a stable UUID and a frozen default name. */
 export declare function createModelProfile(input: Omit<ModelProfile, 'id'>): ModelProfile;
 /** Duplicate the current draft entry, including its explicitly edited credential. */
 export declare function duplicateModelProfile(entry: ModelProfile): ModelProfile;
-/** Remove an unused entry; binding references must be changed explicitly first. */
+/** Ids of the kits whose three slots name `id`, for the reference message. */
+export declare function kitNamesForProfile(library: ModelProfilesConfig, id: string): string[];
+/**
+ * Remove an unused entry; binding references must be changed explicitly first.
+ *
+ * The message NAMES the kits that would be orphaned (D-9): a throw that only
+ * says "still in use" sends the user hunting through three separate screens for
+ * the reference it means, and the kits are the reference nobody thinks of.
+ * (The UI never reaches this throw - it unbinds, and deletes the kits, inside
+ * the draft first - so this is the library-level backstop, F-25.)
+ */
 export declare function removeModelProfile(library: ModelProfilesConfig, id: string): ModelProfilesConfig;