@aragon-agent/cli 0.6.34 → 0.6.35

package/dist/commands/builtins.js

@@ -23,6 +23,7 @@ import { getLogger } from '../logging/logger.js';
 import { resolveFastTier } from '../fast/resolve.js';
 import { subagentModelSummary } from '../ui/overlays/model-profile-state.js';
 import { registerQueueCommand } from './queue-command.js';
+import { registerKitCommand } from './kit-command.js';
 import { perfCommand } from './perf.js';
 import { runCompactCommand } from '../compaction/command.js';
 import { runClearCommand } from './clear-command.js';
@@ -1371,6 +1372,9 @@ export function registerBuiltinCommands(registry) {
     for (const command of COMMANDS)
         registry.register(command);
     registerQueueCommand(registry);
+    // The command BODY lives in its own module (builtins.ts is already 1.5k lines);
+    // this line is the whole registration (agent-model-kits §4.9).
+    registerKitCommand(registry);
 }
 /**
  * Every built-in command name INCLUDING aliases (`quit`), for documentation and

package/dist/commands/kit-command.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `/kit` - the slash surface for agent model kits (agent-model-kits §4.9).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A COMMAND AT ALL, WHEN `ctrl+K` EXISTS: a key that a terminal, tmux, an
+ * input method or a IME can swallow needs an equivalent that cannot be swallowed
+ * (`R-4`), and the same reading is what a user pastes into an issue. The two
+ * surfaces call the SAME controller methods, so they can never diverge in
+ * behaviour - only in how the answer is rendered.
+ *
+ * THERE IS NO `/kit default` (D-7): the session path is forbidden from writing
+ * the file, so a "make this the default" verb here would be the one hole in that
+ * promise. Setting a default is a settings action, with a Save the user sees.
+ */
+import type { CommandRegistry, CommandContext } from './registry.js';
+/** The command body; `registerKitCommand` is the only registration site. */
+export declare function runKitCommand(ctx: CommandContext): void;
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export declare function registerKitCommand(registry: CommandRegistry): void;

package/dist/commands/kit-command.js

@@ -0,0 +1,131 @@
+/**
+ * `/kit` - the slash surface for agent model kits (agent-model-kits §4.9).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A COMMAND AT ALL, WHEN `ctrl+K` EXISTS: a key that a terminal, tmux, an
+ * input method or a IME can swallow needs an equivalent that cannot be swallowed
+ * (`R-4`), and the same reading is what a user pastes into an issue. The two
+ * surfaces call the SAME controller methods, so they can never diverge in
+ * behaviour - only in how the answer is rendered.
+ *
+ * THERE IS NO `/kit default` (D-7): the session path is forbidden from writing
+ * the file, so a "make this the default" verb here would be the one hole in that
+ * promise. Setting a default is a settings action, with a Save the user sees.
+ */
+import { kitMatches, findKit, kitSlotConnections } from '../config/model-kits.js';
+import { kitApplyMessage, kitNoteMessages } from '../agent/kit-apply.js';
+/** `main a:b / sub same as main / fast off`, shared by every branch below. */
+function describeKit(config, kit) {
+    const connections = kitSlotConnections(config.modelProfiles, kit);
+    const main = connections.main
+        ? `${connections.main.provider}:${connections.main.model}` : 'Profile missing';
+    const fast = kit.fastProfileId === null ? 'off'
+        : connections.fast ? `${connections.fast.provider}:${connections.fast.model}`
+            : 'Profile missing';
+    const subagent = kit.subagent.model === 'main' ? 'same as main'
+        : kit.subagent.model === 'fast' ? 'fast tier'
+            : connections.subagent.name ? `profile ${connections.subagent.name}` : 'Profile missing';
+    return `main ${main} / sub ${subagent} / fast ${fast}`;
+}
+function kitNames(config) {
+    return (config.modelProfiles?.kits ?? []).map((kit) => kit.name);
+}
+/** `/kit` with no argument: what is in effect, and what it resolves to. */
+function reportActive(ctx) {
+    const config = ctx.controller.getConfig();
+    const active = ctx.controller.getActiveKit();
+    const kits = config.modelProfiles?.kits ?? [];
+    if (!kits.length) {
+        ctx.notify('info', 'No kits yet. Create one in /settings (Settings > Kit pack).');
+        return;
+    }
+    const session = active.source === 'session'
+        ? `session: ${active.name}${active.held.length < 3
+            ? `, holds ${active.held.join('+')}` : ''}`
+        : active.source === 'default' ? 'default' : 'current setup';
+    const kit = findKit(config.modelProfiles, active.id);
+    const detail = kit ? ` ${describeKit(config, kit)}.` : '';
+    const drift = active.modified && active.driftReasons.length
+        ? ` Drifted: ${active.driftReasons.join('; ')}.` : '';
+    ctx.notify('info', `Kit pack: ${active.name} (${session}).${detail}${drift}`);
+}
+/** `/kit list`: every kit, its markers and its three connections. */
+function listKits(ctx) {
+    const config = ctx.controller.getConfig();
+    const kits = config.modelProfiles?.kits ?? [];
+    const active = ctx.controller.getActiveKit();
+    const fallback = config.modelProfiles?.defaultKitId ?? null;
+    if (!kits.length) {
+        ctx.notify('info', 'No kits yet. Create one in /settings.');
+        return;
+    }
+    const lines = kits.map((kit) => {
+        const markers = [kit.id === fallback ? '[Default]' : '',
+            active.source !== 'none' && active.id === kit.id ? '[In use]' : '',
+            active.source !== 'none' && active.id === kit.id && active.modified ? '~' : '']
+            .filter(Boolean).join(' ');
+        return `${markers ? `${markers} ` : ''}${kit.name}: ${describeKit(config, kit)}`;
+    });
+    ctx.notify('info', `Kits (${kits.length}):\n${lines.join('\n')}`);
+}
+/** `/kit use current` and `/kit use <name|#prefix>`. */
+function useKit(ctx, ref) {
+    const config = ctx.controller.getConfig();
+    if (ref.toLowerCase() === 'current') {
+        const released = ctx.controller.clearSessionKit();
+        ctx.toast(released.ok ? 'success' : 'warn', kitApplyMessage(released));
+        return;
+    }
+    const matches = kitMatches(config.modelProfiles, ref);
+    if (!matches.length) {
+        const names = kitNames(config);
+        ctx.notify('warn', `No kit named "${ref}".`
+            + (names.length ? ` Available: ${names.join(', ')}.` : ' Create one in /settings first.'));
+        return;
+    }
+    if (matches.length > 1) {
+        const ids = matches.map((kit) => `#${kit.id.slice(0, 8)}`).join(', ');
+        ctx.notify('warn', `Two or more kits are named "${ref}": ${ids}. Use one of those ids.`);
+        return;
+    }
+    const kit = matches[0];
+    const result = ctx.controller.applySessionKit(kit.id);
+    if (!result.ok) {
+        // `kit_references_missing_profile` names the SLOT in its issues; without them
+        // the user would have to open three screens to find out which one is dead.
+        const detail = (result.issues ?? []).map((issue) => issue.message).join(' ');
+        ctx.notify('warn', [kitApplyMessage(result), detail].filter(Boolean).join(' '));
+        return;
+    }
+    const notes = kitNoteMessages(result.notes);
+    ctx.toast(notes.length ? 'warn' : 'success', [`Kit ${kit.name} applied for this session.`, ...notes].join(' '));
+}
+/** The command body; `registerKitCommand` is the only registration site. */
+export function runKitCommand(ctx) {
+    const args = ctx.args.trim();
+    if (!args) {
+        reportActive(ctx);
+        return;
+    }
+    const [verb = '', ...rest] = args.split(/\s+/);
+    if (verb.toLowerCase() === 'list') {
+        listKits(ctx);
+        return;
+    }
+    if (verb.toLowerCase() === 'use') {
+        const ref = rest.join(' ').trim();
+        if (!ref) {
+            ctx.notify('warn', 'Which kit? Use /kit use <name|#id prefix>, or /kit use current.');
+            return;
+        }
+        useKit(ctx, ref);
+        return;
+    }
+    ctx.notify('warn', 'Unknown /kit subcommand. Try /kit, /kit list, /kit use <name>.');
+}
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export function registerKitCommand(registry) {
+    registry.register({ name: 'kit', description: 'Agent kits: status, list, use for this session',
+        run: (ctx) => { runKitCommand(ctx); } });
+}

package/dist/config/kit-resolution.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 type { CliConfig, FastConfig, TeamConfig } from './schema.js';
+import type { ModelProfilesConfig } from './model-profiles.js';
+import { type KitSlot, type SessionKitState } from './model-kits.js';
+/** The three slots, in the order every surface prints them. */
+export declare const ALL_SLOTS: readonly KitSlot[];
+/** The name the UI gives "no kit is in effect" (D-13). */
+export declare 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 declare const INACTIVE_KIT: ActiveKit;
+export interface ActiveKit {
+    source: 'session' | 'default' | 'none';
+    id: string | null;
+    /** `Current setup` when `source === 'none'`. */
+    name: string;
+    /** `[]` when `source === 'none'`; all three for a default kit. */
+    held: KitSlot[];
+    /** The kit's definition and the live connections no longer agree (§4.8). */
+    modified: boolean;
+    /** Human-readable ASCII reasons, for `/kit` and the root row. */
+    driftReasons: string[];
+    /** Slots whose referenced profile is gone (RV-P1-1 / I-8). */
+    missingProfiles: KitSlot[];
+}
+/** The session-kit runtime shape, owned by `model-kits.ts` and re-exported here. */
+export type { SessionKitState } from './model-kits.js';
+/**
+ * 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 declare function resolveActiveKit(config: CliConfig): ActiveKit;
+/**
+ * The minimum a candidate has to offer for the held slots to be re-applied.
+ *
+ * STRUCTURAL, NOT `PersistedConfig`: the same routine serves a disk candidate on
+ * its way to `liveCandidate` and a freshly reloaded `CliConfig`, and forcing
+ * either through a cast at the call site would hide the fact that only these
+ * three sections are ever written.
+ */
+export interface HeldTarget {
+    modelProfiles?: ModelProfilesConfig;
+    fast?: Partial<FastConfig>;
+    team?: Partial<TeamConfig>;
+}
+/**
+ * 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 declare function applyHeldToLive<T extends HeldTarget>(candidate: T, sessionKit: SessionKitState | null | undefined): {
+    candidate: T;
+    dropped: KitSlot[];
+};
+/**
+ * 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 declare function carrySessionKit(input: {
+    resolved: CliConfig;
+    previous: CliConfig;
+}): CliConfig;

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;
+}