@aragon-agent/tui 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,103 @@
+import { type AgentKit } from './model-kits.js';
+export type ModelRole = 'main' | 'fast';
+export interface ModelProfile {
+    id: string;
+    name: string;
+    provider: string;
+    model: string;
+    baseUrl: string | null;
+    apiKey: string | null;
+    /** The context window of this model+endpoint; null = AUTO (profile-context-window 5.1). */
+    contextWindow: number | null;
+}
+export interface ModelProfilesConfig {
+    version: 1;
+    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;
+    appliedId: string | null;
+    overriddenFields: Array<'provider' | 'model' | 'baseUrl'>;
+    invalid: boolean;
+}
+export interface ModelProfilesRuntime {
+    main: ProfileBindingState;
+    fast: ProfileBindingState;
+}
+export interface ProfileValidationIssue {
+    path: string;
+    code: 'invalid' | 'duplicate_id' | 'missing_reference' | 'unsupported_version';
+    message: string;
+}
+/** Return a fresh empty library without initiating a disk migration. */
+export declare function emptyModelProfiles(): ModelProfilesConfig;
+/** Return independently mutable role state. */
+export declare function emptyModelProfileState(invalid?: boolean): ModelProfilesRuntime;
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * 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.
+ *
+ * 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).
+ *
+ * THE SAME TRI-STATE DISCIPLINE as store.ts normalizeContextWindow, kept out of
+ * store.ts on purpose: this file already imports schema.js and store's sibling
+ * model-profile-store.ts already imports this one, so placing it here avoids
+ * widening the existing store <-> model-profile-store cycle. A garbage value on
+ * a hand-edited file degrades to AUTO; it NEVER invalidates the whole library
+ * (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.
+ *
+ * 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;
+/** 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;

package/dist/model/config/model-profiles.js

@@ -0,0 +1,188 @@
+import { randomUUID } from 'node:crypto';
+import { ADAPTER_PROVIDERS, clampContextWindow, isAutoToken } from './schema.js';
+import { normalizeKits, validateKits } from './model-kits.js';
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+/** Return a fresh empty library without initiating a disk migration. */
+export function emptyModelProfiles() {
+    return { version: 1, entries: [], mainId: null, fastId: null, kits: [],
+        defaultKitId: null, kitsVersion: 1 };
+}
+/** Return independently mutable role state. */
+export function emptyModelProfileState(invalid = false) {
+    const binding = () => ({ selectedId: null, appliedId: null,
+        overriddenFields: [], invalid });
+    return { main: binding(), fast: binding() };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function validText(value, max, allowEmpty = false) {
+    return typeof value === 'string' && !CONTROL.test(value)
+        && (allowEmpty || value.trim().length > 0) && [...value.trim()].length <= max;
+}
+function validUrl(value) {
+    if (value === null || (typeof value === 'string' && !value.trim()))
+        return true;
+    if (typeof value !== 'string' || CONTROL.test(value))
+        return false;
+    try {
+        const url = new URL(value.trim());
+        return ['http:', 'https:'].includes(url.protocol) && Boolean(url.hostname)
+            && !url.username && !url.password && !value.includes('?') && !value.includes('#');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The endpoint rule published as a predicate (model-profile-connection-test §5 row 10).
+ *
+ * The probe's `invalid_base_url` guard has to use THE SAME ruler as validation, or a
+ * URL the editor accepts can still be refused by the test (and the reverse). A second
+ * copy of these four clauses is one edit away from disagreeing with the config layer.
+ */
+export function isValidEndpointUrl(value) {
+    return validUrl(value);
+}
+function validateEntry(value, index) {
+    const path = `modelProfiles.entries[${index}]`;
+    const invalid = (field, message) => ({
+        path: field ? `${path}.${field}` : path, code: 'invalid', message,
+    });
+    if (!isRecord(value))
+        return [invalid('', 'Profile must be an object.')];
+    const issues = [];
+    if (!validText(value.id, 128))
+        issues.push(invalid('id', 'ID must have 1-128 safe characters.'));
+    if (!validText(value.name, 80, true)) {
+        issues.push(invalid('name', 'Name must have at most 80 safe characters.'));
+    }
+    if (!ADAPTER_PROVIDERS.includes(value.provider)) {
+        issues.push(invalid('provider', 'Select a supported provider.'));
+    }
+    if (!validText(value.model, 256)) {
+        issues.push(invalid('model', 'Model must have 1-256 safe characters.'));
+    }
+    if (!validUrl(value.baseUrl)) {
+        issues.push(invalid('baseUrl', 'Use an HTTP(S) URL without credentials, query or fragment.'));
+    }
+    if (value.apiKey !== null && !validText(value.apiKey, 8192)) {
+        issues.push(invalid('apiKey', 'Enter a nonempty key up to 8192 safe characters.'));
+    }
+    return issues;
+}
+/**
+ * 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 function validateModelProfiles(value) {
+    if (value === undefined)
+        return [];
+    if (!isRecord(value))
+        return [{ path: 'modelProfiles', code: 'invalid',
+                message: 'Model profiles must be an object. Repair with aragon config edit.' }];
+    if (value.version !== 1)
+        return [{ path: 'modelProfiles.version',
+                code: 'unsupported_version', message: 'Unsupported model profiles version.' }];
+    if (!Array.isArray(value.entries) || value.entries.length > 200) {
+        return [{ path: 'modelProfiles.entries', code: 'invalid',
+                message: 'Use an array with at most 200 profiles; remove unused profiles to add more.' }];
+    }
+    const issues = value.entries.flatMap(validateEntry);
+    const ids = new Set();
+    value.entries.forEach((entry, index) => {
+        if (!isRecord(entry) || typeof entry.id !== 'string')
+            return;
+        if (ids.has(entry.id))
+            issues.push({ path: `modelProfiles.entries[${index}].id`,
+                code: 'duplicate_id', message: 'Profile IDs must be unique.' });
+        ids.add(entry.id);
+    });
+    for (const field of ['mainId', 'fastId']) {
+        if (value[field] !== null && (typeof value[field] !== 'string' || !ids.has(value[field]))) {
+            issues.push({ path: `modelProfiles.${field}`, code: 'missing_reference',
+                message: 'Select an existing profile or Current custom.' });
+        }
+    }
+    issues.push(...validateKits(value.kits));
+    return issues;
+}
+/**
+ * Disk-tolerance gate for a profile-level context window (profile-context-window 5.3).
+ *
+ * THE SAME TRI-STATE DISCIPLINE as store.ts normalizeContextWindow, kept out of
+ * store.ts on purpose: this file already imports schema.js and store's sibling
+ * model-profile-store.ts already imports this one, so placing it here avoids
+ * widening the existing store <-> model-profile-store cycle. A garbage value on
+ * a hand-edited file degrades to AUTO; it NEVER invalidates the whole library
+ * (invariant 4 - one bad number must not drop the user's credentials).
+ */
+export function normalizeProfileContextWindow(value) {
+    if (value === undefined || value === null || isAutoToken(value))
+        return null;
+    return clampContextWindow(value, null);
+}
+/**
+ * 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 function normalizeModelProfiles(value) {
+    if (validateModelProfiles(value).length)
+        throw new Error('Invalid model profiles.');
+    if (value === undefined)
+        return emptyModelProfiles();
+    const library = value;
+    const { kits, defaultKitId, kitsVersion } = normalizeKits(library.kits, library.defaultKitId);
+    return { version: 1, mainId: library.mainId, fastId: library.fastId,
+        entries: library.entries.map((entry) => ({ id: entry.id, name: entry.name.trim()
+                || [...entry.model.trim()].slice(0, 80).join(''), provider: entry.provider,
+            model: entry.model.trim(), baseUrl: entry.baseUrl?.trim() || null,
+            apiKey: entry.apiKey?.trim() || null,
+            contextWindow: normalizeProfileContextWindow(entry.contextWindow) })),
+        kits, defaultKitId, kitsVersion };
+}
+/** Create an entry with a stable UUID and a frozen default name. */
+export function createModelProfile(input) {
+    const entry = { ...input, id: randomUUID() };
+    return normalizeModelProfiles({ ...emptyModelProfiles(), entries: [entry] }).entries[0];
+}
+/** Duplicate the current draft entry, including its explicitly edited credential. */
+export function duplicateModelProfile(entry) {
+    return { ...entry, id: randomUUID(), name: `${[...entry.name].slice(0, 73).join('')} (copy)` };
+}
+/** Ids of the kits whose three slots name `id`, for the reference message. */
+export function kitNamesForProfile(library, id) {
+    return (library.kits ?? []).filter((kit) => kit.mainProfileId === id
+        || kit.fastProfileId === id
+        || (kit.subagent.model === 'profile' && kit.subagent.modelProfileId === id))
+        .map((kit) => kit.name);
+}
+/**
+ * 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 function removeModelProfile(library, id) {
+    if (library.mainId === id || library.fastId === id)
+        throw new Error('Profile is still in use.');
+    const kits = kitNamesForProfile(library, id);
+    if (kits.length) {
+        throw new Error(`Profile is used by kit ${kits.map((name) => `"${name}"`).join(', ')}.`);
+    }
+    return { ...library, entries: library.entries.filter((entry) => entry.id !== id) };
+}

package/dist/model/config/model-settings-types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The model-settings TRANSACTION types, split out of `model-profile-store.ts`
+ * (tui-package-split S2).
+ *
+ * ASCII ONLY - `src/config/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * TYPES ONLY, NO RUNTIME CODE. The terminal-UI view models (settings screen, model-kit
+ * resolution, team fan-out and governance settings) need the SHAPE of a settings patch,
+ * a draft and a save result, but the store that owns them also reads and writes the config
+ * file. Keeping the shapes here lets those view models live in a package that has no
+ * filesystem persistence, while `model-profile-store.ts` re-exports every name so existing
+ * importers and tests are untouched. Symbols with I/O semantics (`ConfigReadError`,
+ * `ModelSettingsDisk`, `ModelProfileConfigError`) deliberately stay in the store.
+ *
+ * `SessionKitState` comes from `model-kits`, which in turn imports `ModelSettingsSaveResult`
+ * from here: a pure type cycle, which TypeScript permits because it is erased at compile time.
+ */
+import type { SessionKitState } from './model-kits.js';
+import type { ModelProfilesConfig, ModelRole, ProfileValidationIssue } from './model-profiles.js';
+import type { CliConfig, CompactionConfig, FastConfig, GovernanceConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
+export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team' | 'governance'>> {
+    fast?: Partial<FastConfig>;
+    compaction?: Partial<CompactionConfig>;
+    log?: Partial<LogConfig>;
+    /** The subagent-model picker writes here (subagent-model D-5/I-5): draft-only until Save. */
+    team?: Partial<TeamConfig>;
+    /** Governance writers (`config set`, `/gov budget`) send single keys; the store clamps. */
+    governance?: Partial<GovernanceConfig>;
+}
+export interface ModelSettingsDraft {
+    profiles?: ModelProfilesConfig;
+    patch: ModelSettingsPatch;
+    activateRoles: ModelRole[];
+    diskRevision: string;
+    liveRevision: number;
+    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;
+    persisted: boolean;
+    status: 'applied' | 'restart_required' | 'rejected' | 'saved_apply_failed';
+    code?: 'invalid' | 'busy' | 'conflict' | 'read_failed' | 'write_failed' | 'profile_key_required' | 'legacy_conversion_unsupported' | 'apply_failed';
+    issues?: ProfileValidationIssue[];
+    restartRequired?: boolean;
+}

package/dist/model/config/model-settings-types.js

@@ -0,0 +1,18 @@
+/**
+ * The model-settings TRANSACTION types, split out of `model-profile-store.ts`
+ * (tui-package-split S2).
+ *
+ * ASCII ONLY - `src/config/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * TYPES ONLY, NO RUNTIME CODE. The terminal-UI view models (settings screen, model-kit
+ * resolution, team fan-out and governance settings) need the SHAPE of a settings patch,
+ * a draft and a save result, but the store that owns them also reads and writes the config
+ * file. Keeping the shapes here lets those view models live in a package that has no
+ * filesystem persistence, while `model-profile-store.ts` re-exports every name so existing
+ * importers and tests are untouched. Symbols with I/O semantics (`ConfigReadError`,
+ * `ModelSettingsDisk`, `ModelProfileConfigError`) deliberately stay in the store.
+ *
+ * `SessionKitState` comes from `model-kits`, which in turn imports `ModelSettingsSaveResult`
+ * from here: a pure type cycle, which TypeScript permits because it is erased at compile time.
+ */
+export {};