@compilr-dev/cli 0.8.10 → 0.9.0

package/dist/repl-helpers.js

@@ -5,7 +5,7 @@
  * and improve maintainability. These functions support the REPL but don't
  * depend on REPL instance state.
  */
-import { detectCollisions, formatCollisionWarnings, resolveSkillPrompt, getAllAvailableSkills, platformSkills } from '@compilr-dev/sdk';
+import { detectCollisions, formatCollisionWarnings, resolveSkillPrompt, getAllAvailableSkills, platformMacros } from '@compilr-dev/sdk';
 import { getSkillsDir } from './utils/skill-paths.js';
 import { getProjectPath } from './utils/project-status.js';
 import { codingSkills } from '@compilr-dev/agents-coding';
@@ -202,7 +202,7 @@ export function hasBacklogItems(backlogPath) {
     }
 }
 /** Get the current project directory (best effort). */
-function getProjectDir() {
+export function getProjectDir() {
     try {
         return getProjectPath(process.cwd());
     }
@@ -211,7 +211,7 @@ function getProjectDir() {
     }
 }
 /** Get CLI skill sources (factory + coding). */
-function getCliSkillSources() {
+export function getCliSkillSources() {
     return { factorySkills, codingSkills };
 }
 /**
@@ -229,16 +229,16 @@ function getCliSkillSources() {
  * of date again, so the rule now reads the skill's own tag. The SDK has a matching guard
  * asserting every canvas skill carries it.
  */
-const DESKTOP_ONLY_SKILLS = new Set(platformSkills.filter((skill) => skill.tags?.includes('canvas')).map((skill) => skill.name));
+const DESKTOP_ONLY_MACROS = new Set(platformMacros.filter((skill) => skill.tags?.includes('canvas')).map((skill) => skill.name));
 /**
  * Get skill prompt by name. Delegates to SDK resolveSkillPrompt, minus any
- * Desktop-only SDK skills (see DESKTOP_ONLY_SKILLS).
+ * Desktop-only SDK skills (see DESKTOP_ONLY_MACROS).
  */
 export function getSkillPrompt(name) {
     const resolution = resolveSkillPrompt(name, getProjectDir(), getCliSkillSources());
     if (!resolution)
         return null;
-    if (resolution.source === 'sdk' && DESKTOP_ONLY_SKILLS.has(resolution.skillName))
+    if (resolution.source === 'sdk' && DESKTOP_ONLY_MACROS.has(resolution.skillName))
         return null;
     return resolution.prompt;
 }
@@ -250,7 +250,7 @@ export function getSkillResolution(name) {
     const resolution = resolveSkillPrompt(name, getProjectDir(), getCliSkillSources());
     if (!resolution)
         return null;
-    if (resolution.source === 'sdk' && DESKTOP_ONLY_SKILLS.has(resolution.skillName))
+    if (resolution.source === 'sdk' && DESKTOP_ONLY_MACROS.has(resolution.skillName))
         return null;
     return {
         prompt: resolution.prompt,
@@ -267,6 +267,13 @@ export function getSkillAutocompleteEntries() {
     const entries = getAllAvailableSkills(getProjectDir(), getCliSkillSources());
     return entries
         .filter((e) => e.source !== 'sdk' && e.source !== 'agents') // SDK/agents skills already in built-in commands
+        /*
+          ⚠️ A DISABLED SKILL MUST NOT BE OFFERED. Pressing Space in `/skill` writes `enabled: false`
+          into the SKILL.md and `resolveSkillPrompt` then refuses it — but autocomplete filtered only
+          on `source`, so the skill kept appearing, and accepting the suggestion answered "Unknown
+          command". Desktop's `getSkillList` has always filtered on this; the CLI did not.
+        */
+        .filter((e) => e.enabled !== false)
         .map((e) => {
         const desc = e.description.length > 60 ? e.description.slice(0, 57) + '...' : e.description;
         return {

package/dist/repl-v2.d.ts

@@ -304,6 +304,16 @@ export declare class ReplV2 {
      * For foreground: sets currentSession and foregroundAgentId
      * For background: only adds to sessions map
      */
+    /**
+     * A warning to prepend when a macro needs tools the active agent does not have.
+     *
+     * ⚠️ WITHOUT IT THE AGENT PROMISES AND THEN FAILS. `/design` tells the agent to use `ask_user`
+     * and `workitem_add`; sent to an agent that cannot reach those it announces a requirements
+     * session and dies partway, which reads as the agent being broken. Addressed to the agent, not
+     * shown as a terminal warning: the user does not know which tools /design needs or which
+     * teammate has them, and the agent can explain and offer the handoff.
+     */
+    private macroPreamble;
     private startSession;
     /**
      * End an agent session.

package/dist/repl-v2.js

@@ -56,6 +56,7 @@ import { isMemoryInput } from './input-handlers/index.js';
 import { addAnchor } from './anchors/index.js';
 import { getActiveProject } from './tools/project-db.js';
 import { getSkillResolution, getSkillAutocompleteEntries, checkSkillCollisions } from './repl-helpers.js';
+import { macroToolGap, macroToolGapPreamble } from '@compilr-dev/sdk';
 import { getProjectSessionManager } from './session/project-session-manager.js';
 import { ResumeOverlayV2 } from './ui/overlay/impl/resume-overlay-v2.js';
 import { updateCacheInfo, updateHistoryEstimate, formatBreakdownCompact, formatCacheInfo, estimateTokens } from './utils/token-tracker.js';
@@ -302,8 +303,36 @@ export class ReplV2 {
      * For foreground: sets currentSession and foregroundAgentId
      * For background: only adds to sessions map
      */
+    /**
+     * A warning to prepend when a macro needs tools the active agent does not have.
+     *
+     * ⚠️ WITHOUT IT THE AGENT PROMISES AND THEN FAILS. `/design` tells the agent to use `ask_user`
+     * and `workitem_add`; sent to an agent that cannot reach those it announces a requirements
+     * session and dies partway, which reads as the agent being broken. Addressed to the agent, not
+     * shown as a terminal warning: the user does not know which tools /design needs or which
+     * teammate has them, and the agent can explain and offer the handoff.
+     */
+    macroPreamble(macroName) {
+        const active = this.team?.getActive();
+        if (!active?.toolFilter)
+            return null;
+        const gap = macroToolGap(macroName, active.toolFilter);
+        return gap ? macroToolGapPreamble(macroName, gap) : null;
+    }
     startSession(session) {
         this.sessions.set(session.agentId, session);
+        /*
+          ⚠️ TELLS THE SDK THE AGENT IS MID-REPLY, so `/team` -> `e` cannot save an edit that
+          rebuilds it. A rebuild snapshots the history and drops the instance, but the in-flight run
+          holds its own reference and finishes anyway — the reply arrives and the rebuilt agent has
+          no memory of having sent it. Nothing errors; the agent just answers the next question from
+          a history the user can see is wrong.
+    
+          Reachable here through BACKGROUND agents (`$agent msg &`): a foreground turn blocks the
+          REPL, so `/team` is out of reach until it finishes, but a background one leaves the prompt
+          free. Bracketing start/end covers both, and they are the one chokepoint every run passes.
+        */
+        this.team?.get(session.agentId)?.beginTurn();
         if (!session.isBackground) {
             this.currentSession = session;
             this.foregroundAgentId = session.agentId;
@@ -316,6 +345,8 @@ export class ReplV2 {
      */
     endSession(agentId) {
         this.sessions.delete(agentId);
+        // Pairs with beginTurn() in startSession, however the turn ended.
+        this.team?.get(agentId)?.endTurn();
         if (this.foregroundAgentId === agentId) {
             this.currentSession = null;
             this.foregroundAgentId = null;
@@ -2047,7 +2078,13 @@ export class ReplV2 {
             },
             // Queue agent message (for commands that invoke the agent)
             queueAgentMessage: (options) => {
-                this.ui.queueAgentMessage(options);
+                /*
+                  A macro assumes tools. Warn the AGENT here — the one place every hardcoded macro
+                  handler funnels through — rather than in each handler, which would be eight copies of
+                  a rule that must not drift.
+                */
+                const preamble = options.macro ? this.macroPreamble(options.macro) : null;
+                this.ui.queueAgentMessage(preamble ? { ...options, message: `${preamble}\n\n---\n\n${options.message}` } : options);
             },
             // Session stats
             startTime: this.startTime,
@@ -2092,7 +2129,11 @@ export class ReplV2 {
                     this.ui.print({ type: 'info', message: `🛠  /${cmd} → ${resolution.skillName}${forkInfo}` });
                 }
                 this.ui.print({ type: 'user-message', text: `/${cmd}${args ? ' ' + args : ''}` });
-                const fullPrompt = args ? `${resolution.prompt}\n\nUser request: ${args}` : resolution.prompt;
+                // Same warning as the hardcoded macros get — this path serves every other macro name,
+                // including a user's own skill invoked as one.
+                const macroPreamble = this.macroPreamble(cmd);
+                const body = args ? `${resolution.prompt}\n\nUser request: ${args}` : resolution.prompt;
+                const fullPrompt = macroPreamble ? `${macroPreamble}\n\n---\n\n${body}` : body;
                 if (this.agent) {
                     await this.runAgentReal(fullPrompt);
                 }

package/dist/ui/overlay/impl/agent-edit-overlay-v2.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Agent Edit Overlay V2
+ *
+ * Standalone overlay for editing an existing team agent's attributes.
+ * Opened from /team (via 'e' key) — see commands-v2/handlers/team.ts.
+ *
+ * Adapted from ProjectEditOverlayV2, which has the same shape: a list of fields,
+ * one selected, Enter to change it. The additions here are choice fields (model
+ * tier, tool profile, mascot) which cycle rather than accept typing.
+ *
+ * ⚠️ THIS OVERLAY DOES NOT SAVE. It returns the edited values and the caller applies
+ * them. `AgentTeam.updateAgent` is async and the REPL's live-agent reference may need
+ * replacing afterwards (see the handler); overlay key handling is synchronous.
+ */
+import { BaseOverlayV2 } from '../../base/index.js';
+import type { RenderContext, OverlayAction, KeyEvent } from '../types.js';
+import { type ToolProfile, type MascotExpression } from '@compilr-dev/sdk';
+import { type ModelTier } from '../../../models/index.js';
+type FieldKey = 'displayName' | 'specialty' | 'personality' | 'instructions' | 'modelTier' | 'toolProfile' | 'mascot';
+interface EditableField {
+    key: FieldKey;
+    label: string;
+    /** 'text' fields are typed into; 'choice' fields cycle through `choices`. */
+    kind: 'text' | 'choice';
+    value: string;
+    placeholder?: string;
+    maxLength?: number;
+    choices?: string[];
+}
+interface AgentEditState {
+    fields: EditableField[];
+    selectedFieldIndex: number;
+    editingField: boolean;
+    inputBuffer: string;
+    error: string | null;
+}
+/** Everything the overlay needs to render, and to hand back unchanged if untouched. */
+export interface AgentEditOptions {
+    agentId: string;
+    displayName: string;
+    mascot: MascotExpression;
+    /** TeamAgent.description — the one-line "what this agent is for". */
+    specialty: string;
+    /** Tone only. Composed at initialize() as "Your manner: …" (SDK 0.23+). */
+    personality: string;
+    /**
+     * The user's OWN instructions — never the composed prompt.
+     * For a custom agent this comes from `CustomAgentDefinition.systemPromptAddition`; for a
+     * role agent, from the live `TeamAgent.systemPromptAddition`, which since SDK 0.23 holds
+     * user-authored text only. A role agent that has never been edited stores nothing here,
+     * so an empty box is the normal state rather than a loading failure.
+     */
+    instructions: string;
+    modelTier: ModelTier;
+    toolProfile: ToolProfile;
+    /** Custom agents regenerate their prompt on save; role agents do not. */
+    isCustom: boolean;
+    /** Mascots already in use by other agents, marked in the picker. */
+    takenMascots?: string[];
+}
+export interface AgentEditValues {
+    displayName: string;
+    specialty: string;
+    personality: string;
+    instructions: string;
+    modelTier: ModelTier;
+    toolProfile: ToolProfile;
+    mascot: MascotExpression;
+}
+export interface AgentEditResult {
+    saved: boolean;
+    agentId: string;
+    /** Present only when saved. The caller diffs these against the originals. */
+    values?: AgentEditValues;
+}
+export declare class AgentEditOverlayV2 extends BaseOverlayV2<AgentEditState, AgentEditResult> {
+    readonly type: "inline";
+    readonly id = "agent-edit-overlay-v2";
+    private readonly opts;
+    constructor(opts: AgentEditOptions);
+    /** Human-readable rendering of a choice field's current value. */
+    private describeChoice;
+    /**
+     * One-line preview of a text value.
+     *
+     * ⚠️ Collapse newlines BEFORE truncating. Instructions are multi-line, and a raw `\n`
+     * reaching the renderer makes one logical line occupy two physical rows, which breaks
+     * the overlay's line accounting.
+     */
+    private previewText;
+    /**
+     * Truncate plain text to fit the frame.
+     *
+     * ⚠️ Applied BEFORE styling. Cutting a styled string can slice through an ANSI escape
+     * and leave the rest of the terminal wearing the colour.
+     */
+    private fit;
+    protected renderContent(context: RenderContext): string[];
+    /** Move a choice field to its next/previous option, wrapping. */
+    private cycleChoice;
+    handleKey(key: KeyEvent): OverlayAction<AgentEditResult>;
+    private valueOf;
+    private saveAndClose;
+}
+export {};

package/dist/ui/overlay/impl/agent-edit-overlay-v2.js

@@ -0,0 +1,364 @@
+/**
+ * Agent Edit Overlay V2
+ *
+ * Standalone overlay for editing an existing team agent's attributes.
+ * Opened from /team (via 'e' key) — see commands-v2/handlers/team.ts.
+ *
+ * Adapted from ProjectEditOverlayV2, which has the same shape: a list of fields,
+ * one selected, Enter to change it. The additions here are choice fields (model
+ * tier, tool profile, mascot) which cycle rather than accept typing.
+ *
+ * ⚠️ THIS OVERLAY DOES NOT SAVE. It returns the edited values and the caller applies
+ * them. `AgentTeam.updateAgent` is async and the REPL's live-agent reference may need
+ * replacing afterwards (see the handler); overlay key handling is synchronous.
+ */
+import { BaseOverlayV2, renderBorder } from '../../base/index.js';
+import { PROFILE_INFO, CUSTOM_MASCOTS, } from '@compilr-dev/sdk';
+import { MODEL_TIERS, TIER_INFO } from '../../../models/index.js';
+const PROFILE_LIST = Object.keys(PROFILE_INFO);
+// =============================================================================
+// Agent Edit Overlay V2
+// =============================================================================
+export class AgentEditOverlayV2 extends BaseOverlayV2 {
+    type = 'inline';
+    id = 'agent-edit-overlay-v2';
+    opts;
+    constructor(opts) {
+        // A custom agent's mascot is user-chosen; keep the current one selectable even
+        // if another agent also holds it, so opening the editor can never silently
+        // move an agent off its own face.
+        const mascotChoices = Array.from(new Set([opts.mascot, ...CUSTOM_MASCOTS]));
+        super({
+            fields: [
+                {
+                    key: 'displayName',
+                    label: 'Display Name',
+                    kind: 'text',
+                    value: opts.displayName,
+                    placeholder: 'e.g. Solution Architect',
+                    maxLength: 60,
+                },
+                {
+                    key: 'specialty',
+                    label: 'Specialty',
+                    kind: 'text',
+                    value: opts.specialty,
+                    placeholder: 'e.g. system design and trade-offs',
+                    maxLength: 120,
+                },
+                {
+                    key: 'personality',
+                    label: 'Personality',
+                    kind: 'text',
+                    value: opts.personality,
+                    placeholder: 'e.g. Pragmatic and thorough (tone only)',
+                    maxLength: 200,
+                },
+                {
+                    key: 'instructions',
+                    label: 'Instructions',
+                    kind: 'text',
+                    value: opts.instructions,
+                    // Empty is the normal state for a role agent: its role scaffold is composed by
+                    // the SDK and was never the user's to edit.
+                    placeholder: opts.isCustom
+                        ? '(none — add your own instructions)'
+                        : '(none — role behaviour is built in)',
+                    maxLength: 2000,
+                },
+                {
+                    key: 'modelTier',
+                    label: 'Model Tier',
+                    kind: 'choice',
+                    value: opts.modelTier,
+                    choices: [...MODEL_TIERS],
+                },
+                {
+                    key: 'toolProfile',
+                    label: 'Tool Profile',
+                    kind: 'choice',
+                    value: opts.toolProfile,
+                    choices: [...PROFILE_LIST],
+                },
+                {
+                    key: 'mascot',
+                    label: 'Mascot',
+                    kind: 'choice',
+                    value: opts.mascot,
+                    choices: mascotChoices,
+                },
+            ],
+            selectedFieldIndex: 0,
+            editingField: false,
+            inputBuffer: '',
+            error: null,
+        });
+        this.opts = opts;
+        this.minHeight = 24;
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /** Human-readable rendering of a choice field's current value. */
+    describeChoice(field, context) {
+        const s = context.styles;
+        if (field.key === 'modelTier') {
+            const info = TIER_INFO[field.value];
+            return `${info.label} ${s.muted(`— ${info.shortDescription}`)}`;
+        }
+        if (field.key === 'toolProfile') {
+            const info = PROFILE_INFO[field.value];
+            const readOnly = info.isReadOnly ? s.muted(' [read-only]') : '';
+            return `${info.label}${readOnly}`;
+        }
+        // mascot
+        const taken = (this.opts.takenMascots ?? []).includes(field.value) && field.value !== this.opts.mascot;
+        return `${field.value}${taken ? s.muted(' (in use by another agent)') : ''}`;
+    }
+    /**
+     * One-line preview of a text value.
+     *
+     * ⚠️ Collapse newlines BEFORE truncating. Instructions are multi-line, and a raw `\n`
+     * reaching the renderer makes one logical line occupy two physical rows, which breaks
+     * the overlay's line accounting.
+     */
+    previewText(value, width) {
+        const collapsed = value.replace(/\n+/g, ' ').replace(/\s+/g, ' ').trim();
+        if (collapsed.length <= width)
+            return collapsed;
+        return collapsed.slice(0, Math.max(0, width - 1)) + '…';
+    }
+    /**
+     * Truncate plain text to fit the frame.
+     *
+     * ⚠️ Applied BEFORE styling. Cutting a styled string can slice through an ANSI escape
+     * and leave the rest of the terminal wearing the colour.
+     */
+    fit(text, cols) {
+        const max = Math.max(0, cols - 2);
+        if (text.length <= max)
+            return text;
+        return text.slice(0, Math.max(0, max - 1)) + '…';
+    }
+    renderContent(context) {
+        const s = context.styles;
+        /*
+          The width we were GIVEN, not the process's. `OverlayManager` builds the context from
+          `getTerminalWidth()`, so these are the same value in production — but rendering to the
+          width passed in is what makes the frame measurable, and leaves the overlay correct if
+          it is ever rendered somewhere narrower than the whole terminal.
+        */
+        const cols = context.width;
+        const border = renderBorder(cols, s);
+        const lines = [];
+        const labelWidth = 14;
+        const valueWidth = Math.max(20, cols - labelWidth - 8);
+        lines.push(border);
+        lines.push(`  ${s.primaryBold('EDIT AGENT')}`);
+        lines.push('');
+        lines.push(s.muted(`  $${this.opts.agentId} · ${this.opts.isCustom ? 'custom agent' : 'role agent'}`));
+        // The id is deliberately not editable — it is written into message history as
+        // literal text, so renaming it would strand every earlier $mention.
+        lines.push(s.muted('  ' +
+            this.fit(cols < 72
+                ? 'Agent ID cannot be changed'
+                : 'Agent ID cannot be changed (earlier $mentions would break)', cols)));
+        lines.push('');
+        lines.push(s.muted('  ' + '─'.repeat(Math.max(0, cols - 6))));
+        lines.push('');
+        for (let i = 0; i < this.state.fields.length; i++) {
+            const field = this.state.fields[i];
+            const isSelected = i === this.state.selectedFieldIndex;
+            const isEditing = isSelected && this.state.editingField;
+            const cursor = isSelected ? s.primary('❯ ') : '  ';
+            const label = field.label.padEnd(labelWidth);
+            if (isEditing) {
+                const shown = this.previewText(this.state.inputBuffer, valueWidth);
+                lines.push(`${cursor}${s.muted(label)} ${s.primary(shown)}█`);
+                continue;
+            }
+            let rendered;
+            if (field.kind === 'choice') {
+                rendered = this.describeChoice(field, context);
+            }
+            else if (field.value) {
+                rendered = this.previewText(field.value, valueWidth);
+            }
+            else {
+                rendered = s.muted(field.placeholder ?? '(not set)');
+            }
+            lines.push(`${cursor}${isSelected ? s.primary(label) : s.muted(label)} ${rendered}`);
+        }
+        lines.push('');
+        if (this.state.error) {
+            lines.push(s.error('  ' + this.fit(this.state.error, cols)));
+        }
+        else if (this.opts.isCustom) {
+            lines.push(s.muted('  ' +
+                this.fit(cols < 72
+                    ? 'Saving regenerates the system prompt.'
+                    : "Saving regenerates this agent's system prompt from its definition.", cols)));
+        }
+        else {
+            lines.push('');
+        }
+        lines.push(border);
+        if (this.state.editingField) {
+            lines.push(s.muted('  ' + this.fit('Enter Accept field · Esc Cancel edit', cols)));
+        }
+        else {
+            const selected = this.state.fields[this.state.selectedFieldIndex];
+            const verb = selected.kind === 'choice' ? 'Enter/←→ Change' : 'Enter Edit';
+            const hint = cols < 72
+                ? `↑↓ Move · ${verb} · s Save · Esc Cancel`
+                : `↑↓/jk Navigate · ${verb} field · s Save & close · Esc Cancel`;
+            lines.push(s.muted('  ' + this.fit(hint, cols)));
+        }
+        lines.push(border);
+        return lines;
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    /** Move a choice field to its next/previous option, wrapping. */
+    cycleChoice(field, delta) {
+        const choices = field.choices ?? [];
+        if (choices.length === 0)
+            return;
+        const current = choices.indexOf(field.value);
+        // An unknown current value starts the cycle at the first option rather than
+        // throwing the index negative.
+        const base = current === -1 ? 0 : current;
+        const next = (base + delta + choices.length) % choices.length;
+        field.value = choices[next];
+    }
+    handleKey(key) {
+        // Ctrl+C always closes
+        if (this.isInterruptKey(key)) {
+            return this.close({ saved: false, agentId: this.opts.agentId });
+        }
+        // Handle field editing mode
+        if (this.state.editingField) {
+            if (key.name === 'escape') {
+                // Cancel field edit — the field keeps the value it had
+                this.state.editingField = false;
+                this.state.inputBuffer = '';
+                return this.rerender();
+            }
+            if (this.isEnterKey(key)) {
+                const field = this.state.fields[this.state.selectedFieldIndex];
+                field.value = this.state.inputBuffer;
+                this.state.editingField = false;
+                this.state.inputBuffer = '';
+                this.state.error = null;
+                return this.rerender();
+            }
+            if (key.name === 'backspace') {
+                this.state.inputBuffer = this.state.inputBuffer.slice(0, -1);
+                if (this.state.inputBuffer.length < (this.state.fields[this.state.selectedFieldIndex].maxLength ?? 200)) {
+                    this.state.error = null;
+                }
+                return this.rerender();
+            }
+            // Regular character input
+            if (key.char && key.char.length === 1 && key.char >= ' ' && key.char <= '~') {
+                const field = this.state.fields[this.state.selectedFieldIndex];
+                const max = field.maxLength ?? 200;
+                /*
+                  ⚠️ THE LIMIT BLOCKS GROWTH, NOT EDITING. It used to be `length < max`, which meant a
+                  value ALREADY over the limit swallowed every keystroke in silence — the field looked
+                  frozen and gave no reason. Real case: a pre-0.23 role agent carried 6,208 characters of
+                  generated prompt in a 2,000-character field, so Instructions could not be edited at all.
+                  The SDK no longer stores prose there, but an over-length value can still arrive from
+                  disk, and a control that ignores input without saying why is the worse half of that bug.
+                */
+                if (this.state.inputBuffer.length < max) {
+                    this.state.inputBuffer += key.char;
+                }
+                else {
+                    this.state.error = `${field.label} is at its ${String(max)}-character limit — delete some text first.`;
+                }
+                return this.rerender();
+            }
+            return this.noAction();
+        }
+        // Handle navigation mode
+        if (key.name === 'escape') {
+            return this.close({ saved: false, agentId: this.opts.agentId });
+        }
+        // Navigate up
+        if (this.isUpKey(key) || key.char === 'k') {
+            if (this.state.selectedFieldIndex > 0) {
+                this.state.selectedFieldIndex--;
+                return this.rerender();
+            }
+            return this.noAction();
+        }
+        // Navigate down
+        if (this.isDownKey(key) || key.char === 'j') {
+            if (this.state.selectedFieldIndex < this.state.fields.length - 1) {
+                this.state.selectedFieldIndex++;
+                return this.rerender();
+            }
+            return this.noAction();
+        }
+        const field = this.state.fields[this.state.selectedFieldIndex];
+        // Left/right cycle a choice field
+        if (field.kind === 'choice' && (this.isLeftKey(key) || key.char === 'h')) {
+            this.cycleChoice(field, -1);
+            return this.rerender();
+        }
+        if (field.kind === 'choice' && (this.isRightKey(key) || key.char === 'l')) {
+            this.cycleChoice(field, 1);
+            return this.rerender();
+        }
+        // Enter edits a text field, or advances a choice field
+        if (this.isEnterKey(key)) {
+            if (field.kind === 'choice') {
+                this.cycleChoice(field, 1);
+                return this.rerender();
+            }
+            this.state.inputBuffer = field.value;
+            this.state.editingField = true;
+            return this.rerender();
+        }
+        // 's' to save and close
+        if (key.char === 's' || key.char === 'S') {
+            return this.saveAndClose();
+        }
+        return this.noAction();
+    }
+    valueOf(key) {
+        const field = this.state.fields.find((f) => f.key === key);
+        return field ? field.value : '';
+    }
+    saveAndClose() {
+        const displayName = this.valueOf('displayName').trim();
+        // The roster renders this everywhere an agent is named; an empty one leaves a
+        // blank where the agent should be, so refuse rather than write it.
+        if (!displayName) {
+            this.state.error = 'Display Name cannot be empty.';
+            this.state.selectedFieldIndex = 0;
+            return this.rerender();
+        }
+        return this.close({
+            saved: true,
+            agentId: this.opts.agentId,
+            values: {
+                displayName,
+                specialty: this.valueOf('specialty').trim(),
+                personality: this.valueOf('personality').trim(),
+                instructions: this.valueOf('instructions'),
+                modelTier: this.valueOf('modelTier'),
+                toolProfile: this.valueOf('toolProfile'),
+                /*
+                  Every option came from `CUSTOM_MASCOTS` or from the agent's own current mascot,
+                  so the value is always a real expression. `CUSTOM_MASCOTS` is declared `string[]`
+                  in the SDK, which is why the narrowing has to be stated here — the same cast
+                  `TeamAgent.fromCustomDefinition` makes on the way in.
+                */
+                mascot: this.valueOf('mascot'),
+            },
+        });
+    }
+}