@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/commands.js

@@ -0,0 +1,550 @@
+import { isPermissionMode, permissionLabel, workspacePermissionKey } from './permissions.js';
+import { graphStorageDirectory } from './graph-account.js';
+import { configuredGraphSelection, currentGraphSubject, saveGraphSelection } from './graph-selection.js';
+import { loadAccessibleGraph, requireGraphMembership } from './membership.js';
+import { GraphProviderUnavailableError } from './graph-provider-portability.js';
+import { confirmAndApplyModelOverride } from './model-override.js';
+import { changeConfigFile, configDirectory, loadConfig, loadSavedAnalytics } from './config.js';
+import { applyModelContextWindow, providerLabel, recordProviderModel, REASONING_EFFORTS } from './providers.js';
+import { resolveRepositoryId } from './code-intelligence/repository.js';
+import { logoutCodex } from './codex-auth.js';
+import { codexAccountHome } from './codex-rpc.js';
+import { executeAuthCommand } from './auth-commands.js';
+import { analyticsGenerationFor, resolveAnalyticsConfig } from './analytics.js';
+import { telemetryDirectory } from './telemetry/identity.js';
+import { purgeOutbox } from './telemetry/outbox.js';
+import { recordPreference } from './telemetry/state.js';
+import { telemetryGate } from './telemetry/gate.js';
+const MAX_CODEINTEL_REPO_OVERRIDES = 100;
+const REASONING_USAGE = 'Usage: /reasoning default|none|minimal|low|medium|high|xhigh|max';
+export const HELP = `Commands:
+  /browser               Open the browser workspace (CLI stays available)
+  /session               Browse and resume saved sessions (newest first)
+  /login                 Open browser sign-in or create an Andorra account
+  /auth logout           Remove this machine's saved Andorra account session
+  /auth status           Show Andorra account session status
+  /model [model-id]       Open model selection or select a model directly; with a graph that pins node models, asks whether to override them
+  /model list            Discover models from the active provider
+  /providers [id]         Choose providers; Right/e edits; Add provider configures
+  /subagent [id [model]]  Set the provider/model external hosts (Claude/Codex CLI) must use for Andorra subagent runs; off clears it
+  /reasoning <level>      Set default|none|minimal|low|medium|high|xhigh|max
+  /graph [id]             Select a graph or open the web graph builder
+  /codegraph <action>     Code intelligence: status|enable|disable|rebuild; enable|disable --global sets the default for every project
+  /dashboard             Toggle live dashboard and transcript (TTY only)
+  /attach <path>         Attach a file or folder to your next task (large pastes and dropped files attach automatically)
+  /usage                 Open session usage (Escape to return)
+  /permissions [mode]    Choose and remember workspace permissions
+  /jev <on|off|status>    Turn Jev on or off for nodes that enable it, or show its setting
+  /feedback <on|off|status>  Show the anonymous-feedback setting; Paid accounts can turn it off
+  /yolo <on|off>          Turn session-wide Full Access on or off (host files and network)
+  /tools                 List available coding tools
+  /skills                List, install, enable, disable or remove skills
+  /<skillname> [args]     Apply an enabled imported skill; qualify duplicate names by catalog ID
+  /plugins               List, install, enable, disable or remove plugins
+  /mcp                   Add, edit, enable, disable or delete MCP servers
+  /logout                Sign out of your Andorra account (then /login to switch accounts)
+  /logout codex          Sign out of every configured Codex (ChatGPT) account
+  /status                Show workspace and current settings
+  /clear                 Clear the conversation on screen and the retained context (session usage is retained)
+  /compact               Compact retained conversation history to free context
+  /help                  Show commands
+  /exit                  Quit
+Selection screens: Up/Down to browse, Enter or Space to select, Escape to return.
+Ctrl+B toggles dashboard; Ctrl+G pages its graph; Ctrl+N cycles dashboard model statistics (display only).
+Ctrl+T expands/collapses todos; Ctrl+O expands/collapses tool details; Ctrl+Y collapses/expands live thinking.
+Shift+Arrow/Home/End selects prompt text; Ctrl+C copies and Ctrl+X cuts a selection. The wheel scrolls; Up/Down recall prompts. Shift+drag selects transcript text.
+Ctrl+C stops an interactive run; send direction to resume, or press Ctrl+C again to exit (idle Ctrl+C exits too). /yolo on|off applies immediately, including at approvals. /exit quits. Headless Ctrl+C cancels the run; a second press exits.`;
+/**
+ * Collapse retained turns into a single summary entry so the next request sends one
+ * condensed user/assistant pair instead of every full completion.
+ *
+ * Compaction is deterministic and local: each turn keeps its task and outcome summary
+ * (clipped) and loses test lists and structured detail. A continued turn also keeps its
+ * direction as its own clipped part — folding it into the task's clip could cut it away
+ * entirely, and `/compact` erasing what the user sent after a stop is exactly what a
+ * summary must not do. The caller still holds the turns; replacing them is the CLI's
+ * decision, reported through the `compact` result flag.
+ */
+export function compactHistory(turns) {
+    const clip = (text, limit) => { const flat = text.replace(/\s+/g, ' ').trim(); return flat.length > limit ? flat.slice(0, limit - 1) + '…' : flat; };
+    const lines = turns.map((turn, index) => `${index + 1}. ${clip(turn.task, 160)}${turn.direction === undefined ? '' : ` (continued with: ${clip(turn.direction, 160)})`} → ${clip(turn.completion.summary, 240)}`);
+    return [{
+            task: `Compacted conversation of ${turns.length} earlier task${turns.length === 1 ? '' : 's'}; entries list each task and its outcome.`,
+            completion: { summary: lines.join('\n'), tests: [] },
+        }];
+}
+/**
+ * Estimate the context the compacted history will occupy, in tokens, so the footer can
+ * drop the moment `/compact` runs. This is a character-based approximation (the same
+ * seed text measured at ~4 characters per token); the next model request replaces it with
+ * the provider-reported input size.
+ */
+export function compactedContextEstimate(turns) {
+    return Math.ceil(JSON.stringify(turns).length / 4);
+}
+const CODEGRAPH_USAGE = 'Usage: /codegraph status|enable|disable|rebuild. Add --global to enable|disable to set the saved default for every project (this clears per-repository overrides).';
+/**
+ * `/codegraph`. `enable|disable` alone records an override for the current repository; with
+ * `--global` it sets the saved default that every project and every later session starts from.
+ */
+async function codegraphCommand(action, scope, state, signal) {
+    const manager = state.codeIntel;
+    if (!manager)
+        return { text: 'Code intelligence is not available in this session.' };
+    if (scope === 'global' && action !== 'enable' && action !== 'disable')
+        return { text: CODEGRAPH_USAGE };
+    switch (action) {
+        case 'status': {
+            const status = await manager.getStatus();
+            const indexed = status.stats?.lastIndexedAt ? new Date(status.stats.lastIndexedAt).toLocaleString() : 'never';
+            const repositoryId = await resolveRepositoryId(state.workspace).catch(() => undefined);
+            const saved = state.config.codeIntel?.enabled !== false;
+            const override = !repositoryId ? ''
+                : (state.config.codeIntel?.enabledRepos ?? []).includes(repositoryId) ? '; this repository is enabled by override'
+                    : (state.config.codeIntel?.disabledRepos ?? []).includes(repositoryId) ? '; this repository is disabled by override'
+                        : '; this repository has no override';
+            return { text: `CodeGraph: ${status.state}${status.available ? '' : ' (unavailable)'}${status.detail ? ` — ${status.detail}` : ''}\nEnabled: ${status.enabled ? 'yes' : 'no'}\nSaved: ${saved ? 'enabled' : 'disabled'} for every project${override}\nIndexed: ${status.stats ? `${status.stats.files} files, ${status.stats.nodes} nodes, last indexed ${indexed}` : 'nothing yet'}\nCache: .codegraph/ in the workspace root (disposable; add it to your .gitignore)` };
+        }
+        case 'enable':
+        case 'disable': {
+            const enable = action === 'enable';
+            if (scope === 'global') {
+                // The global toggle is the newest statement of intent, so it resets the per-repository
+                // exceptions: after it, every project follows the saved default until a plain
+                // `/codegraph enable|disable` records a new override.
+                const cleared = (state.config.codeIntel?.enabledRepos?.length ?? 0) + (state.config.codeIntel?.disabledRepos?.length ?? 0);
+                state.config.codeIntel = { ...state.config.codeIntel, enabled: enable, enabledRepos: [], disabledRepos: [] };
+                return { text: `Code intelligence ${enable ? 'enabled' : 'disabled'} for every project; new sessions in other projects start with it ${enable ? 'on' : 'off'}.${cleared ? ` ${cleared} per-repository override${cleared === 1 ? ' was' : 's were'} cleared.` : ''} /codegraph ${enable ? 'disable' : 'enable'} without --global overrides this for one repository.`, save: true };
+            }
+            const repositoryId = await resolveRepositoryId(state.workspace).catch(() => undefined);
+            if (repositoryId) {
+                // Per-repository override: never touch the global enabled flag, so a
+                // global disable survives enabling one repository (and vice versa).
+                const disabled = new Set(state.config.codeIntel?.disabledRepos ?? []);
+                const enabledRepos = new Set(state.config.codeIntel?.enabledRepos ?? []);
+                const target = enable ? enabledRepos : disabled;
+                if (!target.has(repositoryId) && target.size >= MAX_CODEINTEL_REPO_OVERRIDES) {
+                    return { text: `Code intelligence was not changed: the ${enable ? 'enabled' : 'disabled'} repository override list already contains ${MAX_CODEINTEL_REPO_OVERRIDES} entries. Remove an obsolete override before adding another.` };
+                }
+                if (enable) {
+                    disabled.delete(repositoryId);
+                    enabledRepos.add(repositoryId);
+                }
+                else {
+                    disabled.add(repositoryId);
+                    enabledRepos.delete(repositoryId);
+                }
+                state.config.codeIntel = { ...state.config.codeIntel, disabledRepos: [...disabled], enabledRepos: [...enabledRepos] };
+            }
+            else {
+                state.config.codeIntel = { ...state.config.codeIntel, enabled: enable };
+            }
+            // The live manager is updated by executeCommand only after persistence succeeds.
+            return { text: `Code intelligence ${enable ? 'enabled' : 'disabled'}${repositoryId ? ' for this repository' : ''}.`, save: true };
+        }
+        case 'rebuild':
+            try {
+                signal?.throwIfAborted();
+                await manager.rebuild(signal);
+                signal?.throwIfAborted();
+                return { text: 'Code graph rebuilt and re-indexed.' };
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return { text: 'Code graph rebuild cancelled.' };
+                return { text: `Rebuild failed: ${error instanceof Error ? error.message : 'unknown error'}` };
+            }
+        default:
+            return { text: CODEGRAPH_USAGE };
+    }
+}
+/**
+ * Copy a configuration over the live one, deletions included.
+ *
+ * `Object.assign` only adds and replaces, so a setting another writer deleted would stay in the
+ * live configuration and be resurrected by the next command that saves the whole snapshot.
+ */
+function syncConfig(target, source) {
+    for (const key of Object.keys(target)) {
+        if (!(key in source))
+            delete target[key];
+    }
+    Object.assign(target, source);
+}
+/** What the command says after it changed the preference. */
+function feedbackChangedText(enabled) {
+    return `Anonymous feedback ${enabled ? 'on' : 'off'}. Setting saved for this machine.${enabled ? ' It never includes your code, prompts, or API keys.' : ' No anonymous product data will be reported from this installation.'}`;
+}
+/** The line shown for a plan that collects as a condition of the plan. */
+function includedWithPlanText(plan) {
+    if (plan === 'legacy')
+        return 'on (included with the Legacy plan)';
+    if (plan === 'free')
+        return 'on (included with the Free plan)';
+    return 'on (included with your plan until this account\'s plan is confirmed)';
+}
+/** Why a plan that cannot opt out refuses `/feedback off`. */
+function optOutRefusedText(plan) {
+    const named = plan === 'free' ? 'Free' : plan === 'legacy' ? 'Legacy' : 'current';
+    return `Anonymous feedback stays on: collection is included with the ${named} plan. Upgrade to Paid to turn it off.`;
+}
+/**
+ * Whether a `/subagent off` invocation clears the saved pair.
+ *
+ * A provider may legally be named "off", and a selection of a real provider must not delete the
+ * configuration: the clear applies only when nothing is configured under that name.
+ */
+export function subagentClearRequested(line, providers) {
+    return /^\/subagent\s+off\s*$/.test(line.trim()) && !providers.some(provider => provider.id === 'off');
+}
+/** Commit selection changes only after persistence succeeds; callers render the returned result afterward. */
+export async function executeCommand(line, state, persist, signal, graphAccess = { load: loadAccessibleGraph, requirePaid: requireGraphMembership }, graphSubject = currentGraphSubject, logout = logoutCodex) {
+    // `/logout` is the Andorra account's sign-out, the counterpart of `/login`; a provider's managed
+    // sign-in is named explicitly, so signing out of the account never touches provider sessions.
+    if (/^\/logout\s+\S/.test(line.trim())) {
+        if (!/^\/logout\s+codex$/.test(line.trim()))
+            return { text: 'Usage: /logout | /logout codex' };
+        const codex = state.config.providers.filter(candidate => candidate.type === 'codex');
+        if (!codex.length)
+            return { text: 'No Codex provider is configured, so there is no Codex sign-in to log out of. Use /logout to sign out of your Andorra account.' };
+        // Each configured account has its own home, so all of them leave together: signing out one
+        // alone would leave the others' sessions live under entries the person believes are gone.
+        // Slot-less providers share the default home, which is signed out once.
+        const homes = [];
+        for (const item of codex) {
+            const home = codexAccountHome(item.codexAccount);
+            if (!homes.includes(home))
+                homes.push(home);
+        }
+        const failures = [];
+        for (const home of homes) {
+            try {
+                await logout({ signal, ...(home === undefined ? {} : { home }) });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return { text: 'Sign-out cancelled. Sign-in state may have changed; use /providers to check.' };
+                failures.push(error instanceof Error ? error.message : 'unknown error');
+            }
+        }
+        if (failures.length)
+            return { text: `Sign-out failed for ${failures.length} Codex account${failures.length === 1 ? '' : 's'}: ${failures.join('; ')}` };
+        return { text: 'Signed out of every configured Codex account. Provider settings are retained; use /providers to sign in again.', exit: true, clear: true };
+    }
+    const draft = { ...state, config: structuredClone(state.config) };
+    // The feedback preference belongs to the installation rather than to this process: the desktop
+    // app and another CLI write the same file, so the answer this command reports and the value it
+    // changes are the ones saved now, not the snapshot this process loaded when it started. The bare
+    // form only reports, like `status`.
+    const feedbackWrite = /^\/feedback(?:\s+(?:on|off|status))?$/.test(line.trim());
+    if (feedbackWrite)
+        draft.config.analytics = await loadSavedAnalytics();
+    // The plan gate is resolved before the command runs, so `/feedback off` refuses rather than
+    // writes a value that only looks stored.
+    if (feedbackWrite) {
+        // Read the preference from the file, not this process's snapshot: another writer may have
+        // changed it since the run started.
+        const gate = await telemetryGate({ home: configDirectory(), config: await loadConfig(configDirectory()), subject: await graphSubject().catch(() => undefined) });
+        draft.analytics = { plan: gate.plan, canOptOut: gate.canOptOut };
+    }
+    const graphCommand = /^\/graph\s+(\S+)\s*$/.exec(line.trim());
+    // A second word is only ever `--global`; a bare `/codegraph --global` or a misspelt flag reaches the usage text.
+    const codegraph = /^\/codegraph(?:\s+(\S+))?(?:\s+(\S+))?\s*$/.exec(line.trim());
+    const codegraphScope = codegraph?.[2] === undefined ? 'repository' : codegraph[2] === '--global' ? 'global' : undefined;
+    let result;
+    if (/^\/(login|logout|auth)(?:\s|$)/.test(line.trim())) {
+        const command = /^\/(login|logout)\s*$|^\/auth\s+(status|logout)\s*$/.exec(line.trim());
+        const action = command?.[1] ?? command?.[2];
+        result = { text: command ? await executeAuthCommand(action, { signal, print: state.notify }) : 'Usage: /login | /logout | /auth logout | /auth status' };
+        if (action === 'logout' || action === 'login') {
+            delete draft.graph;
+            result.clear = true;
+        }
+    }
+    else if (codegraph) {
+        result = codegraphScope ? await codegraphCommand(codegraph[1] ?? 'status', codegraphScope, draft, signal) : { text: CODEGRAPH_USAGE };
+    }
+    else if (graphCommand) {
+        const id = graphCommand[1];
+        try {
+            signal?.throwIfAborted();
+            const subject = await graphSubject();
+            // A graph that cannot bind to this machine's providers stays selectable: the choice names
+            // what a task will run, and it is the run that refuses those references. The graph is read
+            // once more without binding so the answer can still name it; membership and storage errors
+            // keep refusing the selection outright.
+            let graph;
+            let unavailable;
+            try {
+                graph = await graphAccess.load(id, signal);
+            }
+            catch (error) {
+                if (!(error instanceof GraphProviderUnavailableError) || signal?.aborted)
+                    throw error;
+                unavailable = error.message;
+                graph = await graphAccess.load(id, signal, undefined, { bindProviders: false });
+            }
+            if (await graphSubject() !== subject)
+                throw new Error('Account changed. Retry /graph for the current account');
+            signal?.throwIfAborted();
+            const changed = (state.graph ?? 'default') !== id;
+            const save = configuredGraphSelection(draft.config, subject) !== id || draft.config.graph !== undefined;
+            if (save)
+                saveGraphSelection(draft.config, id, subject);
+            if (id === 'default')
+                delete draft.graph;
+            else
+                draft.graph = id;
+            // This form has no UI to confirm on, so the warning that the switch starts fresh travels
+            // in the returned text; an unchanged graph clears nothing and carries no warning.
+            result = { text: `Graph: ${id === 'default' ? 'Default' : graph.name} (${id === 'default' ? 'Software Engineer only' : `${graph.id}@${graph.revision}`})${changed ? ". This session's context is cleared and the new graph starts fresh." : ''}${unavailable ? ` ${unavailable} The graph is selected anyway; a task on it starts only once it can run on this machine, or after /model overrides every node with one provider you have.` : ''}`, clear: changed, save };
+        }
+        catch (error) {
+            return { text: `Graph unavailable: ${error instanceof Error ? error.message : id}. Use /graph to browse saved graphs.` };
+        }
+    }
+    else {
+        if (/^\/graph\s*$/.test(line.trim()))
+            await graphAccess.requirePaid(signal);
+        const modelDirect = /^\/model\s+(\S+)$/.exec(line.trim());
+        const activeProvider = draft.config.providers.find(p => p.id === draft.config.provider);
+        if (modelDirect && modelDirect[1] !== 'list' && draft.graph && activeProvider && state.confirmModelOverride) {
+            // The graph is saved before the config: a declined or failed override leaves both untouched.
+            const outcome = await confirmAndApplyModelOverride({
+                graphId: draft.graph,
+                target: { provider: activeProvider.id, model: modelDirect[1] },
+                configProviders: draft.config.providers.map(p => ({ id: p.id, type: p.type, model: p.model })),
+                // Same rule as the /model screen: the override rewrites every provider reference, so the
+                // graph is read without binding — binding is what refuses a graph whose providers are gone.
+                loadGraph: (id, graphSignal) => graphAccess.load(id, graphSignal, undefined, { bindProviders: false }),
+                resolveDirectory: async () => graphStorageDirectory(undefined, await graphSubject()),
+                confirm: state.confirmModelOverride,
+                signal,
+            });
+            if (outcome.status === 'declined')
+                return { text: 'Model unchanged. The graph keeps its own model selections.' };
+            if (outcome.status === 'failed')
+                return { text: outcome.text };
+            result = handleCommand(line, draft);
+            if (outcome.status === 'applied')
+                result.text = `${result.text}\n${outcome.text}`;
+        }
+        else
+            result = handleCommand(line, draft);
+    }
+    const permissionsChanged = draft.permissions !== state.permissions;
+    // Cache writes must stop before Read Only is persisted or exposed to the run.
+    if (permissionsChanged && draft.permissions === 'read-only')
+        await state.codeIntel?.setPermissions(draft.permissions);
+    if (result.save && feedbackWrite) {
+        // The preference belongs to the installation, so its change is written to the file's current
+        // content under the configuration's lock: saving this process's snapshot would revert a
+        // provider, a limit or a permission that another writer changed while it was running.
+        // Every event already queued under the old preference is discarded only when reporting actually
+        // turns off. Repeating `/feedback off` on an installation that is already off keeps the
+        // generation, so purging again would delete events another process legitimately queued since —
+        // on a shared home, a plan that cannot opt out still reports. The purge is decided inside the
+        // locked update so it sees the state the write replaced.
+        let preferenceTurnedOff = false;
+        const saved = await changeConfigFile(configDirectory(), current => {
+            const enabled = draft.config.analytics?.enabled !== false;
+            preferenceTurnedOff = resolveAnalyticsConfig(current).enabled && !enabled;
+            return { ...current, analytics: { ...draft.config.analytics, generation: analyticsGenerationFor(current.analytics, enabled) } };
+        });
+        // The generation bump closes the race against a task engine that appends just after this purge.
+        if (preferenceTurnedOff)
+            await purgeOutbox(telemetryDirectory());
+        if (saved.analytics !== undefined) {
+            await recordPreference({ subject: await graphSubject().catch(() => undefined), preference: saved.analytics.enabled === false ? 'off' : 'on' }).catch(() => { });
+        }
+        // The live configuration follows the file, not the snapshot this process started with.
+        draft.config = saved;
+    }
+    else if (result.save)
+        await persist(draft.config);
+    // Preserve the config object shared by the CLI's run callback, and the deletions another writer
+    // made in it: a setting that is gone from the file must be gone from the live configuration too.
+    syncConfig(state.config, draft.config);
+    if (graphCommand && result.save)
+        delete state.config.graph;
+    // A cleared subagent pair is a delete on the draft, which Object.assign cannot carry back. A
+    // provider named "off" is a selection, not a clear, so it leaves the setting alone.
+    if (subagentClearRequested(line, state.config.providers) && result.save)
+        delete state.config.externalSubagent;
+    state.yolo = draft.yolo;
+    state.permissions = draft.permissions;
+    if (permissionsChanged && draft.permissions !== 'read-only')
+        await state.codeIntel?.setPermissions(draft.permissions);
+    if (draft.graph === undefined)
+        delete state.graph;
+    else
+        state.graph = draft.graph;
+    // Live manager changes follow persistence, never precede it.
+    if (codegraph && result.save && (codegraph[1] === 'enable' || codegraph[1] === 'disable')) {
+        await state.codeIntel?.setEnabled(codegraph[1] === 'enable');
+    }
+    return result;
+}
+export function handleCommand(line, state) {
+    const [command, ...args] = line.trim().split(/\s+/);
+    const arg = args.join(' ');
+    const provider = state.config.providers.find(p => p.id === state.config.provider);
+    if (!provider && ['/model', '/reasoning', '/status'].includes(command))
+        return { text: 'No providers configured. Open /providers and choose Add provider.' };
+    switch (command) {
+        case '/help': return { text: HELP };
+        case '/exit':
+        case '/quit': return { text: 'Goodbye.', exit: true };
+        case '/clear': return { text: 'Conversation cleared. Session usage retained.', clear: true, resetScreen: true };
+        case '/compact': {
+            const turns = state.history ?? [];
+            if (!turns.length)
+                return { text: 'Nothing to compact: no conversation history is retained yet.' };
+            return { text: `Compacted ${turns.length} retained turn${turns.length === 1 ? '' : 's'} into one summary entry. The next request sends the condensed history; session usage totals are unchanged.`, compact: true };
+        }
+        case '/model':
+            if (arg === 'list')
+                return { text: '', discover: true };
+            if (!arg)
+                return { text: `${provider.id}: ${provider.model}` };
+            if (args.length !== 1)
+                return { text: 'Usage: /model <model-id>' };
+            if (provider.model !== arg) {
+                applyModelContextWindow(provider, arg);
+                delete provider.reasoningEffort;
+            }
+            recordProviderModel(provider, arg);
+            provider.model = arg;
+            return { text: `Model: ${provider.id}/${arg}`, save: true, clear: true };
+        case '/providers':
+            if (!arg && !provider)
+                return { text: 'No providers configured. Open /providers and choose Add provider.' };
+            if (!arg)
+                return { text: state.config.providers.map(p => `${p.id === provider.id ? '*' : ' '} ${providerLabel(p, state.config.providers)} (${p.type}) — ${p.model}`).join('\n') };
+            if (!state.config.providers.some(p => p.id === arg))
+                return { text: `Unknown provider: ${arg}. Use /providers to browse configured providers.` };
+            state.config.provider = arg;
+            return { text: `Provider: ${arg}. Conversation cleared for the new provider.`, save: true, clear: true };
+        case '/subagent': {
+            const setting = state.config.externalSubagent;
+            if (!arg)
+                return { text: setting
+                        ? `External subagent: ${setting.provider}/${setting.model}. Claude CLI and Codex CLI subagent runs use this pair.`
+                        : 'External subagent: not set. External hosts cannot start an Andorra subagent run until a provider/model is picked; they receive a PROVIDER_NOT_SET error listing the options. Use /subagent <provider> [model], or /subagent to pick.' };
+            // A provider may legally be named "off", so the clear applies only when nothing is
+            // configured under that name: a selection of a real provider must not delete the setting.
+            if (arg === 'off' && !state.config.providers.some(provider => provider.id === 'off')) {
+                if (!setting)
+                    return { text: 'External subagent: already not set.' };
+                delete state.config.externalSubagent;
+                return { text: 'External subagent setting cleared. External hosts will be asked to pick a provider/model on every run.', save: true };
+            }
+            const [providerId, modelId] = args;
+            const target = state.config.providers.find(p => p.id === providerId);
+            if (!target)
+                return { text: `Unknown provider: ${providerId}. Use /subagent <provider> [model] with a configured provider.` };
+            const model = modelId ?? target.model;
+            if (target.models !== undefined && !target.models.includes(model)) {
+                return { text: `Model ${model} is not configured for ${target.id}. Use one of: ${target.models.join(', ')}` };
+            }
+            state.config.externalSubagent = { provider: target.id, model };
+            return { text: `External subagent: ${target.id}/${model}. Claude CLI and Codex CLI subagent runs use this pair.`, save: true };
+        }
+        case '/reasoning':
+            if (!arg)
+                return { text: `Thinking: ${provider.reasoningEffort ?? 'provider default'}\n${REASONING_USAGE}` };
+            if (args.length !== 1 || (arg !== 'default' && !REASONING_EFFORTS.includes(arg)))
+                return { text: REASONING_USAGE };
+            if (arg === 'default')
+                delete provider.reasoningEffort;
+            else {
+                if (!['openai-compatible', 'opencode-go'].includes(provider.type))
+                    return { text: 'Reasoning effort overrides are currently supported only for OpenAI-compatible or OpenCode Go providers.' };
+                provider.reasoningEffort = arg;
+            }
+            return { text: `Thinking: ${provider.reasoningEffort ?? 'provider default'}. Effort support depends on the selected model and server.`, save: true };
+        case '/graph':
+            if (arg && arg !== 'default')
+                return { text: 'Use /graph to browse saved graphs, or select a saved graph with /graph <id>.' };
+            if (arg === 'default') {
+                const changed = state.graph !== undefined;
+                delete state.graph;
+                if (changed)
+                    return { text: 'Graph: Default (Software Engineer only)', clear: true };
+            }
+            return { text: 'Graph: Default - Software Engineer only. Use the graph selector for the paid Andorra workflow or custom graphs.' };
+        case '/permissions':
+            if (!arg)
+                return { text: `Permissions: ${permissionLabel(state.permissions ?? (state.yolo ? 'full-access' : 'ask-for-approval'))}` };
+            if (!isPermissionMode(arg))
+                return { text: 'Usage: /permissions read-only|ask-for-approval|approve-for-me|full-access' };
+            state.config.workspacePermissions = { ...state.config.workspacePermissions, [workspacePermissionKey(state.workspace)]: arg };
+            state.permissions = arg;
+            state.yolo = arg === 'full-access';
+            return { text: `Permissions: ${permissionLabel(arg)} (remembered for this workspace).`, save: true };
+        case '/yolo':
+            // The bare form reports and changes nothing: a stray Enter must never flip approvals.
+            if (!arg)
+                return { text: `YOLO: ${state.yolo ? 'on' : 'off'}.\nUsage: /yolo on|off` };
+            if (!['on', 'off'].includes(arg))
+                return { text: 'Usage: /yolo on|off' };
+            state.yolo = arg === 'on';
+            state.permissions = state.yolo ? 'full-access' : 'ask-for-approval';
+            return { text: state.yolo
+                    ? 'YOLO on: session-wide Full Access. Host files, shell, Git, QA, MCP and network operations are automatically approved.'
+                    : 'YOLO off: session permissions restored to Ask for approval.' };
+        case '/jev': {
+            if (args.length > 1 || (arg && !['on', 'off', 'status'].includes(arg)))
+                return { text: 'Usage: /jev on|off|status' };
+            const jevStatus = `Jev: ${state.config.jevEnabled === false ? 'disabled' : 'enabled'} (saved preference). Applies to Agent nodes with Jev turned on. Requires sign-in and available quota.`;
+            if (arg === 'status')
+                return { text: jevStatus };
+            if (!arg)
+                return { text: `${jevStatus}\nUsage: /jev on|off|status` };
+            state.config.jevEnabled = arg === 'on';
+            const saved = `Jev ${state.config.jevEnabled ? 'enabled' : 'disabled'}. Setting saved for this machine.`;
+            if (state.running)
+                return { text: `${saved} The current run keeps its setting; the change applies after it ends or you interrupt it.`, save: true };
+            return { text: `${saved}${state.config.jevEnabled ? ' It applies to Agent nodes with Jev turned on and requires sign-in and available quota.' : ''}`, save: true };
+        }
+        case '/feedback': {
+            if (args.length > 1 || (arg && !['on', 'off', 'status'].includes(arg)))
+                return { text: 'Usage: /feedback on|off|status' };
+            // The saved answer is the effective one, not the raw stored field: a configuration that
+            // never mentioned the setting still reports on, and the status line has to say so.
+            // The stored preference, not the effective reporting answer: a never-confirmed installation
+            // collects even with the preference off, and the status line still has to say what was saved.
+            const enabled = resolveAnalyticsConfig(state.config).enabled;
+            const plan = state.analytics?.plan ?? 'unknown';
+            const canOptOut = state.analytics?.canOptOut ?? true;
+            // The bare form reports, like `status`: a stray Enter must never change the preference.
+            if (arg === 'status' || !arg) {
+                const usage = arg ? '' : '\nUsage: /feedback on|off|status';
+                if (!canOptOut)
+                    return { text: `Anonymous feedback: ${includedWithPlanText(plan)}. It never includes your code, prompts, or API keys.${usage}` };
+                return { text: `Anonymous feedback: ${enabled ? 'on' : 'off'} (saved preference). It never includes your code, prompts, or API keys.${usage}` };
+            }
+            const next = arg === 'on';
+            // A switch that silently does nothing is worse than one that is not offered: a plan that
+            // cannot opt out refuses the change and says why.
+            if (!next && !canOptOut)
+                return { text: optOutRefusedText(plan) };
+            state.config.analytics = { ...state.config.analytics, enabled: next };
+            return { text: feedbackChangedText(next), save: true };
+        }
+        case '/usage': {
+            // Cache traffic renders only when reported, mirroring the usage screen: an
+            // unreported read is omitted rather than shown as a measured zero, and the
+            // hit-rate percentage needs a positive input total to mean anything.
+            const read = state.usage.cacheRead ?? 0, write = state.usage.cacheWrite ?? 0;
+            const cache = read > 0 || write > 0
+                ? `, ${[read > 0 ? `${read} cache-read${state.usage.inputTokens > 0 ? ` (${Math.round(read / state.usage.inputTokens * 100)}% of input)` : ''}` : '',
+                    write > 0 ? `${write} cache-write` : ''].filter(Boolean).join(' + ')}`
+                : '';
+            return { text: `Session: ${state.usage.requests} model requests, ${state.usage.inputTokens} input + ${state.usage.outputTokens} output tokens${cache} (provider-reported; missing usage is not estimated).\nCost: unavailable; no pricing assumptions.${state.lastRun ? `\nLast run: ${state.lastRun.id} — ${state.lastRun.status}, ${state.lastRun.toolCalls} tool calls` : ''}` };
+        }
+        case '/status': return { text: `Workspace: ${state.workspace}\nProvider/model: ${provider.id}/${provider.model}\nThinking: ${provider.reasoningEffort ?? 'provider default'}\nContext window: ${provider.contextWindow?.toLocaleString() ?? 'unknown'}\nGraph: ${state.graph ?? 'Default'}\nPermissions: ${permissionLabel(state.permissions ?? (state.yolo ? 'full-access' : 'ask-for-approval'))}\nYOLO: ${state.yolo ? 'on' : 'off'}` };
+        case '/tools': return { text: 'Read, Write, Edit, Glob, Grep, Bash, PowerShell; repo_explore (when CodeGraph is enabled), git_read, qa.*, memory_search and artifact/control tools as permitted.\nEnabled skills add read_skill_resource. Enabled MCP servers and plugins discover namespaced tools at each task start; connection status reports availability. External tools require an agent with shell permission.\nWrites and shell commands obey /permissions; unsupported strict sandboxes fail closed. Host/network escalation and MCP connections/calls require approval unless Full Access is selected. Existing graph configs using retired read_file/search_files/Pi lowercase names are translated internally and are not advertised to models.' };
+        default: return { text: `Unknown command: ${command}. Use /help.` };
+    }
+}

package/dist/src/completion.d.ts

@@ -0,0 +1,45 @@
+import type { Completion, RunOptions } from './runtime.js';
+import type { ModelResponse, ToolSchema } from './types.js';
+export declare const COMPLETION_TOOL = "complete_agent";
+export declare const FINAL_RESPONSE_GUIDANCE = "Only when this node is responsible for producing the final user answer, its summary must satisfy the user's response requirements: include complete requested files and exact formatting, including requested code fences, without abbreviation, path substitution, or offers to provide content later. Each fence opens and closes on its own line; a file written to the workspace that the user did not ask to see in the answer is named by path, not reproduced. Intermediate intake, research, and delegation nodes must instead keep a concise handoff and preserve these final-answer acceptance requirements in the downstream task instruction or output; do not implement or reproduce the final deliverable before handing off.";
+/**
+ * How the model lays out text a person reads: the handoff summary and any prose answer. The
+ * transcript renders markdown (headings, lists, fenced code), so the structure it asks for is
+ * what the user actually sees; a single unbroken paragraph is what this guidance exists to prevent.
+ */
+export declare const RESPONSE_STRUCTURE_GUIDANCE = "Write user-facing text, including the final summary, as structured markdown rather than one unbroken paragraph. Lead with the outcome in one or two sentences, then use short headings (## What changed, ## Verified, ## Not done) and bullet lists for parallel items; put every command, file content, and code sample in a fenced code block whose fences sit on their own lines; keep sentences short and omit filler. Inside a JSON string the line breaks are written as \\n escapes, and they are expected: never flatten the summary into one line to keep the JSON valid. In the tests array, write one short line per check: the check that ran, then its outcome.";
+/**
+ * The summary is the user's final answer and the transcript renders it as markdown. Weak models
+ * read "valid JSON" as "no newlines" and return one unbroken line, so the field itself says the
+ * breaks are wanted, next to the value they shape.
+ */
+export declare const SUMMARY_DESCRIPTION = "Markdown shown to the user as the final answer. Write line breaks as \\n escapes: lead with the outcome, then short headings and bullet lists, and open and close each fenced code block on its own line. Never one unbroken paragraph.";
+export declare const COMPLETION_GUIDANCE = "Finish with complete_agent alone or final JSON. Todos/artifacts do not finish a node. Compare deliverables and verification evidence with acceptance criteria. Fulfill assigned requirements: intake/research nodes hand off downstream work; implementation nodes finish implementation and verification, not a progress checkpoint. Continue available work. For a concrete external blocker, report the blocker and unfinished work honestly. Use a blocked outcome if available; otherwise the sole outcome permits a terminal report, not a claim that the task is done. Only when this node is responsible for producing the final user answer, its summary must satisfy the user's response requirements: include complete requested files and exact formatting, including requested code fences, without abbreviation, path substitution, or offers to provide content later. Each fence opens and closes on its own line; a file written to the workspace that the user did not ask to see in the answer is named by path, not reproduced. Intermediate intake, research, and delegation nodes must instead keep a concise handoff and preserve these final-answer acceptance requirements in the downstream task instruction or output; do not implement or reproduce the final deliverable before handing off. Preserve required fields and valid JSON; escape quotes and Windows backslashes or use C:/repo/file.ts, and write each summary line break as \\n rather than dropping it. Never claim unperformed work.";
+/** Control-plane completion remains available when the execution-tool budget is exhausted. */
+export declare function completionTool(options: RunOptions): ToolSchema;
+/** Only a direct, sole model control call can request completion, never a tool observation. */
+export declare function completionResponse(response: ModelResponse): ModelResponse & {
+    completionError?: string;
+    completionSource: 'complete_agent' | 'final_text';
+};
+/**
+ * Undo one extra layer of string escaping in a summary. Some models JSON-escape the summary again
+ * inside already-JSON tool arguments, so the parsed text holds a backslash and an "n" where its
+ * line breaks belong, and the transcript draws its markdown as one literal paragraph. The decode
+ * runs only when the text has no real line break and at least two escaped paragraph breaks, so a
+ * summary that merely mentions an escape sequence, or a Windows path, is left as written.
+ * Sessions saved before this decode ran still hold the escaped text, so their readers apply it too
+ * (`displayHistory` in sessions.ts).
+ */
+export declare function decodeDoubleEscapedSummary(summary: string, notes?: string[]): string;
+/**
+ * Parse one completion, accepting mechanically imperfect envelopes that are semantically correct.
+ *
+ * `notes`, when provided, collects each host-side coercion ("output arrived as a JSON-encoded
+ * string", "dropped artifacts entries the runtime did not issue"). Those repairs are
+ * deterministic transforms the model cannot achieve by retrying: the artifacts channel can never
+ * hold a pull-request URL, and a model that double-encodes `output` once will do it again. A
+ * rejection for either burns a repair on a coin flip and can end a node whose work is already
+ * done, so they are coerced and recorded instead.
+ */
+export declare function parseCompletion(text: string, options: RunOptions, reject: (reason: string) => void, notes?: string[]): Completion | undefined;