@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/commands/sys/__tests__/setup-core.test.js

@@ -1,7 +1,164 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { resolveBundledPiCliPath } from '../../../core/runtime/pi-cli.js';
+import { BINDING_CATALOG, resolveKeybindings } from '../../../core/keybindings/index.js';
+import { SetupKeybindingsDraft, buildSetupManifest } from '../setup-core.js';
+import { SetupWizard } from '../setup.js';
+import { applyTheme } from '../../../clients/attach/config-load.js';
+import { stripVTControlCharacters } from 'node:util';
+// The provider panel only touches the TUI on async OAuth transitions (never in
+// these keybindings-tab render/input tests) and reads auth from `agentDir`; a
+// no-op TUI stub and an empty temp agent dir keep the wizard headless.
+const stubTui = { requestRender() { } };
+const agentDir = mkdtempSync(join(tmpdir(), 'setup-wizard-test-'));
+test('setup keybinding draft edits, disables, resets, and discards transactionally', () => {
+    const draft = new SetupKeybindingsDraft({ 'crtr.attach.graph.toggle': ['alt+x'] });
+    assert.equal(draft.expression('crtr.attach.graph.toggle'), 'alt+x');
+    assert.equal(draft.dirty, false);
+    assert.equal(draft.edit('crtr.attach.graph.toggle', 'M-Y, ctrl+g').ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], ['alt+shift+y', 'ctrl+g']);
+    assert.equal(draft.dirty, true);
+    assert.equal(draft.unbind('crtr.attach.graph.toggle').ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], []);
+    draft.resetRow('crtr.attach.graph.toggle');
+    assert.equal(Object.hasOwn(draft.overrides(), 'crtr.attach.graph.toggle'), false);
+    draft.edit('crtr.attach.graph.toggle', 'alt+y');
+    draft.discard();
+    assert.deepEqual(draft.overrides(), { 'crtr.attach.graph.toggle': ['alt+x'] });
+    assert.equal(draft.dirty, false);
+});
+test('setup keybinding draft drops a member when the committed value equals the catalog default (N2 sparseness)', () => {
+    const draft = new SetupKeybindingsDraft(undefined);
+    const definition = BINDING_CATALOG.find((entry) => entry.id === 'crtr.attach.graph.toggle');
+    const defaultExpression = draft.expression(definition.id);
+    // Committing the seeded default verbatim must NOT record an override: the row
+    // stays sparse (no member) and the draft stays clean — no spurious unsaved/dot.
+    const result = draft.edit(definition.id, defaultExpression);
+    assert.equal(result.ok, true);
+    assert.equal(Object.hasOwn(draft.overrides(), definition.id), false);
+    assert.equal(draft.dirty, false);
+    // Editing to a real value records the member; re-committing the default drops it.
+    assert.equal(draft.edit(definition.id, 'ctrl+g').ok, true);
+    assert.deepEqual(draft.overrides()[definition.id], ['ctrl+g']);
+    assert.equal(draft.dirty, true);
+    assert.equal(draft.edit(definition.id, defaultExpression).ok, true);
+    assert.equal(Object.hasOwn(draft.overrides(), definition.id), false);
+    assert.equal(draft.dirty, false);
+});
+test('setup keybinding draft keeps the last valid cell value on syntax, collision, and safety errors', () => {
+    const draft = new SetupKeybindingsDraft(undefined);
+    const syntax = draft.edit('crtr.attach.graph.toggle', 'ctrl+not-a-key');
+    assert.equal(syntax.ok, false);
+    assert.deepEqual(draft.overrides(), {});
+    const collision = draft.edit('crtr.attach.graph.toggle', 'alt+m');
+    assert.equal(collision.ok, false);
+    assert.match(collision.diagnostics[0].message, /crtr\.mode\.cycle/);
+    assert.deepEqual(draft.overrides(), {});
+    const unsafe = draft.unbind('crtr.setup.keybindings.save');
+    assert.equal(unsafe.ok, false);
+    assert.match(unsafe.diagnostics[0].message, /save-keybindings/);
+    assert.deepEqual(draft.overrides(), {});
+});
+test('setup reset-all removes invalid and unknown raw members without cataloging pi bindings', () => {
+    const invalidRoot = new SetupKeybindingsDraft('alt+x');
+    assert.equal(invalidRoot.resolution().diagnostics[0]?.code, 'invalid-keybindings');
+    invalidRoot.resetAll();
+    assert.equal(invalidRoot.dirty, true);
+    assert.equal(invalidRoot.resolution().diagnostics.length, 0);
+    const draft = new SetupKeybindingsDraft({
+        'crtr.unknown': ['x'],
+        'crtr.attach.graph.toggle': 'alt+x',
+    });
+    assert.equal(draft.resolution().diagnostics.length, 2);
+    draft.resetAll();
+    assert.deepEqual(draft.overrides(), {});
+    assert.equal(draft.resolution().diagnostics.length, 0);
+    assert.equal(BINDING_CATALOG.some((entry) => entry.id.includes('app.') || entry.id.includes('tui.')), false);
+});
+test('setup keybinding draft refuses edits while the raw root is invalid until reset-all', () => {
+    const draft = new SetupKeybindingsDraft('alt+x');
+    assert.equal(draft.hasInvalidRoot(), true);
+    // An edit against an invalid root must NOT commit (the prior bug: it returned
+    // ok:true against an empty `current` while the row kept showing the default).
+    const rejected = draft.edit('crtr.attach.graph.toggle', 'ctrl+g');
+    assert.equal(rejected.ok, false);
+    assert.equal(rejected.diagnostics[0].code, 'invalid-keybindings');
+    assert.deepEqual(draft.overrides(), {});
+    // reset-all clears the invalid root; edits then succeed and display.
+    draft.resetAll();
+    assert.equal(draft.hasInvalidRoot(), false);
+    const accepted = draft.edit('crtr.attach.graph.toggle', 'ctrl+g');
+    assert.equal(accepted.ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], ['ctrl+g']);
+});
+test('setup keybindings editor stays visible while paging moves the selection (m3)', () => {
+    applyTheme({ cwd: process.cwd() });
+    const openingBindings = resolveKeybindings(undefined);
+    // A short terminal forces a small scroll window so paging past the edit row
+    // is the reproducible m3 scenario (editor was blind-typing off-screen before).
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, openingBindings, undefined, () => 14);
+    wizard.focused = true;
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    // Drive to the Keybindings tab (tab-next = Tab), open the editor on row 0 (Enter).
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    assert.match(render(), /Keybindings/);
+    wizard.handleInput('\r');
+    // Type a distinctive marker into the live editor buffer.
+    wizard.handleInput('zzz');
+    assert.match(render(), /zzz/, 'editor should echo typed input before paging');
+    // PageDown twice: selection moves off, but the editor row must remain on screen.
+    wizard.handleInput('\x1b[6~');
+    wizard.handleInput('\x1b[6~');
+    assert.match(render(), /zzz/, 'editor must stay visible (and keep capturing) after paging');
+});
+test('setup keybindings q-cancel with a dirty draft routes through discard-confirm, not a silent exit (N3)', () => {
+    applyTheme({ cwd: process.cwd() });
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 40);
+    wizard.focused = true;
+    let cancelled = false;
+    wizard.onCancel = () => { cancelled = true; };
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    // Make the draft dirty: unbind the selected row (delete key) so it has a real
+    // pending override.
+    wizard.handleInput('\x1b[3~');
+    assert.match(render(), /unsaved/, 'draft should be dirty after unbind');
+    // q (crtr.setup.cancel) in list mode must NOT drop the edits: it opens the same
+    // discard-confirm the Escape path uses.
+    wizard.handleInput('q');
+    assert.equal(cancelled, false, 'dirty draft must not silently exit on q');
+    assert.match(render(), /Discard every unsaved keybinding change\?/);
+    // A clean draft still exits on q (cancel elsewhere is unchanged).
+    const clean = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 40);
+    let cleanCancelled = false;
+    clean.onCancel = () => { cleanCancelled = true; };
+    clean.focused = true;
+    for (let i = 0; i < 5; i += 1)
+        clean.handleInput('\t');
+    clean.handleInput('q');
+    assert.equal(cleanCancelled, true, 'clean draft still exits on q');
+});
+test('setup keybindings selection always renders across group boundaries in a short window (m4 residual)', () => {
+    applyTheme({ cwd: process.cwd() });
+    // Small viewport so a window spans several group headings + a diagnostic line —
+    // the fixed-reserve page math used to let the selected row fail to render here.
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 13);
+    wizard.focused = true;
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    // Page/step down through the whole catalog; the selection marker must always render.
+    for (let step = 0; step < BINDING_CATALOG.length + 5; step += 1) {
+        assert.match(render(), /\u25b6/, `selection marker must render at step ${step}`);
+        wizard.handleInput('\x1b[6~'); // PageDown
+        wizard.handleInput('j'); // and a single-row step to hit every boundary alignment
+    }
+});
 test('resolveBundledPiCliPath uses crouter bundled pi instead of a standalone pi on PATH', () => {
     const prevPath = process.env.PATH;
     process.env.PATH = '';

package/dist/commands/sys/config.js

@@ -1,5 +1,5 @@
 import { defineBranch, defineLeaf } from '../../core/command.js';
-import { readConfig, writeConfig, configPath as coreConfigPath } from '../../core/config.js';
+import { readConfig, updateConfig, configPath as coreConfigPath } from '../../core/config.js';
 import { usage, notFound } from '../../core/errors.js';
 import { scopeRoot, listScopes } from '../../core/scope.js';
 import { resolveScope } from './shared.js';
@@ -11,7 +11,6 @@ const TOP_LEVEL_KEYS = new Set([
     'marketplaces',
     'plugins',
     'max_panes_per_window',
-    'canvasNav',
     'modelLadders',
 ]);
 const MODEL_PROVIDERS = new Set(['anthropic', 'openai']);
@@ -44,6 +43,9 @@ function parseConfigValue(raw) {
 function setNestedValue(cfg, key, rawValue, value) {
     const parts = key.split('.');
     const topKey = parts[0];
+    if (topKey === 'keybindings') {
+        throw usage('keybindings are edited only through `crtr sys setup`');
+    }
     if (!TOP_LEVEL_KEYS.has(topKey)) {
         throw usage(`unknown config key: ${topKey} (expected: ${[...TOP_LEVEL_KEYS].join('|')})`);
     }
@@ -69,16 +71,6 @@ function setNestedValue(cfg, key, rawValue, value) {
         cfg.max_panes_per_window = Math.floor(value);
         return;
     }
-    if (topKey === 'canvasNav') {
-        // Only the scalar prefixKey is settable here; the prefixBinds/graphBinds
-        // record tables are edited directly in config.json (run `crtr sys config
-        // path` to locate it).
-        if (key === 'canvasNav.prefixKey') {
-            cfg.canvasNav.prefixKey = rawValue;
-            return;
-        }
-        throw usage(`canvasNav.${parts.slice(1).join('.') || '*'} is a record table — edit config.json directly (run \`crtr sys config path\`). Only canvasNav.prefixKey is settable via this command.`);
-    }
     if (topKey === 'modelLadders') {
         if (parts.length === 2 && parts[1] === 'defaultProvider') {
             if (!isModelProvider(rawValue)) {
@@ -121,12 +113,12 @@ function setNestedValue(cfg, key, rawValue, value) {
 const configGet = defineLeaf({
     name: 'get',
     description: 'read a config value by key',
-    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key, or model ladders — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
+    whenToUse: 'you want to inspect one config value — including the whole user keybindings object — optionally from a specific scope. Use sys setup to edit keybindings and sys config set for supported scalar settings.',
     help: {
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav, modelLadders (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, modelLadders, or the whole keybindings object. Keybindings are edited only through sys setup.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
@@ -140,6 +132,9 @@ const configGet = defineLeaf({
     run: async (input) => {
         const key = input['key'];
         const scope = resolveScope(input['scope']);
+        if (key.startsWith('keybindings.') || (key === 'keybindings' && scope !== 'user')) {
+            throw notFound('keybindings are available only as the whole user-scope object');
+        }
         const cfg = readConfig(scope);
         const value = getNestedValue(cfg, key);
         if (value === undefined) {
@@ -151,12 +146,12 @@ const configGet = defineLeaf({
 const configSet = defineLeaf({
     name: 'set',
     description: 'write a config value by key',
-    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey, or set model ladders — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
+    whenToUse: 'you want to change a supported scalar crtr setting in user or project scope. Use sys setup instead for keybindings, and sys config get to inspect values.',
     help: {
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey, modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys setup.' },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. Stored as-is if quoted; coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user.' },
         ],
@@ -174,9 +169,11 @@ const configSet = defineLeaf({
         const scope = resolveScope(input['scope']);
         // Flags are stringly-typed; coerce to number or boolean when unambiguous
         const parsed = parseConfigValue(rawValue);
-        const cfg = readConfig(scope);
-        setNestedValue(cfg, key, rawValue, parsed);
-        writeConfig(scope, cfg);
+        // Mutate + persist through the central raw-partial path. `updateConfig`
+        // writes only the keys this set actually touched -- a non-ladder set never
+        // freezes a materialized `modelLadders`, and a direct
+        // `modelLadders.<provider>.<strength>` set persists only the touched rung.
+        const cfg = updateConfig(scope, (c) => setNestedValue(c, key, rawValue, parsed));
         // Read back the written value for echo
         const written = getNestedValue(cfg, key);
         return { key, value: written, scope };
@@ -185,7 +182,7 @@ const configSet = defineLeaf({
 const configPath = defineLeaf({
     name: 'path',
     description: 'print path(s) to config.json',
-    whenToUse: 'you need the absolute path to config.json — typically to hand-edit settings sys config set cannot reach, like the canvasNav.prefixBinds and graphBinds record tables.',
+    whenToUse: 'you need the absolute path to a user or project config.json for inspection or backup.',
     help: {
         name: 'sys config path',
         summary: 'print absolute path(s) to config.json',
@@ -225,7 +222,7 @@ const configPath = defineLeaf({
 export const configBranch = defineBranch({
     name: 'config',
     description: 'read and write configuration',
-    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey, model ladders), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
+    whenToUse: 'inspecting crtr settings, changing supported scalar values, or locating config.json. Keybinding changes belong in sys setup.',
     help: {
         name: 'sys config',
         summary: 'read and write crtr configuration, including model ladders',

package/dist/commands/sys/doctor.js

@@ -8,6 +8,8 @@ import { lsRemote } from '../../core/git.js';
 import { listNodes } from '../../core/canvas/index.js';
 import { activeFaultForDisplay } from '../../core/canvas/render.js';
 import { readFault } from '../../core/runtime/fault.js';
+import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -89,6 +91,41 @@ function faultRemediation(fault) {
         logPath: fault.logPath,
     };
 }
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+function runCommandPluginChecks(scopes) {
+    const results = [];
+    const inScope = new Set(scopes);
+    const reserved = new Set(SUBTREE_NAMES);
+    // Validate the whole effective set together so cross-plugin top-level name
+    // collisions surface here — a collided command is NOT mounted, and every
+    // claimant must fail, not pass.
+    for (const v of validateEffectiveCommandPlugins(reserved)) {
+        const plugin = v.plugin;
+        if (!inScope.has(plugin.scope))
+            continue;
+        if (v.issues.length === 0) {
+            const mounts = v.contributions.map((c) => c.node.name).join(', ');
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:commands`, mounts.length > 0 ? `contributes top-level command(s): ${mounts}` : `command manifest valid`));
+            continue;
+        }
+        v.issues.forEach((issue, i) => {
+            const remediation = {
+                kind: 'human_action',
+                description: `${issue.next} If unfixable, disable (pkg plugin disable ${plugin.name}), update (pkg plugin update --name ${plugin.name}), or remove (pkg plugin remove ${plugin.name}) the plugin.`,
+            };
+            const detail = issue.path !== undefined ? ` at ${issue.path}` : '';
+            results.push(failCheck(plugin.scope, `plugin:${plugin.name}:commands[${i}]`, `${issue.code}${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, remediation));
+        });
+    }
+    return results;
+}
 function runFaultChecks() {
     const results = [];
     for (const node of listNodes()) {
@@ -240,7 +277,7 @@ function runChecksForScope(scope, opts) {
 export const sysDoctorLeaf = defineLeaf({
     name: 'doctor',
     description: 'diagnose installation health',
-    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, or a config entry points at a directory that no longer exists. Reports each problem with a structured remediation, and can apply the repairs for you.',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or a command-plugin manifest/executable is malformed. Reports each problem with a structured remediation, and can apply the safe repairs for you.',
     help: {
         name: 'sys doctor',
         summary: 'diagnose missing manifests and broken config entries',
@@ -250,13 +287,13 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. Command-plugin manifest checks appear as plugin:<name>:commands (validated statically, never executed); their remediation is always a human_action (disable/update/remove the plugin). remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
-            'Read-only unless --fix is passed.',
-            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings stay read-only.',
+            'Read-only unless --fix is passed. Command-plugin manifests are validated statically — the plugin executable is never run, at any time.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and command-plugin findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
             'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with logPath) so callers can apply it directly without --fix.',
         ],
     },
@@ -270,6 +307,7 @@ export const sysDoctorLeaf = defineLeaf({
             const results = runChecksForScope(scope, { fix, remote });
             allResults.push(...results);
         }
+        allResults.push(...runCommandPluginChecks(scopes));
         allResults.push(...runFaultChecks());
         // Sort by scope then name (mirrors old printResults grouping)
         const scopeOrder = { user: 0, project: 1, builtin: 2, canvas: 3 };

package/dist/commands/sys/setup-core.d.ts

@@ -1,3 +1,4 @@
+import { type BindingId, type BindingResolution, type KeybindingDiagnostic, type SparseKeybindingOverrides } from '../../core/keybindings/index.js';
 export type SetupPackageId = 'crtr-extensions' | 'mode-switch' | 'oauth-adapter';
 export type SetupTool = 'tmux' | 'nvim';
 export type SetupPackageSourceKind = 'local-path' | 'npm';
@@ -31,6 +32,7 @@ export interface SetupStaticInstructions {
     packageLines: string[];
     systemLines: string[];
     exaLine: string;
+    composioLine: string;
     footer: string;
 }
 export interface SetupSubmission {
@@ -39,18 +41,50 @@ export interface SetupSubmission {
     systemDeps: SetupSystemInstallPlan[];
     exaKey: string;
     exaKeyPath: string;
+    composioKey: string;
+    composioKeyPath: string;
 }
 export interface SetupExecutionSummary {
     installed: string[];
     skipped: string[];
     exaKeyWritten: boolean;
     exaKeyPath: string;
+    composioKeyWritten: boolean;
+    composioKeyPath: string;
 }
 export interface SetupInitialState {
     manifest: SetupPackageManifestEntry[];
     installedPackageIds: Set<SetupPackageId>;
     systemTools: SetupSystemToolState[];
     exaKeyPath: string;
+    composioKeyPath: string;
+}
+export interface KeybindingEditResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly KeybindingDiagnostic[];
+}
+/** Transactional sparse keybinding draft used by the full-screen setup tab. */
+export declare class SetupKeybindingsDraft {
+    private expected;
+    private baseline;
+    private current;
+    private baselineInvalidRoot;
+    private invalidRoot;
+    constructor(rawKeybindings: unknown);
+    get dirty(): boolean;
+    overrides(): Record<string, unknown>;
+    expectedKeybindings(): unknown;
+    resolution(): BindingResolution<BindingId>;
+    /** True while the persisted `keybindings` root is a non-object (e.g. a string):
+     *  edits cannot be layered onto an invalid root, so the tab must reset-all first. */
+    hasInvalidRoot(): boolean;
+    expression(id: BindingId): string;
+    edit(id: BindingId, expression: string): KeybindingEditResult;
+    unbind(id: BindingId): KeybindingEditResult;
+    resetRow(id: BindingId): void;
+    resetAll(): void;
+    discard(): void;
+    markSaved(overrides: SparseKeybindingOverrides<BindingId>): void;
 }
 export declare function buildSetupManifest(resolveBuiltinPackageDir?: (name: string) => string): SetupPackageManifestEntry[];
 export declare function normalizePackageIdentity(source: string, settingsDir: string, homeDir: string): SetupPackageIdentity;
@@ -61,6 +95,16 @@ export declare function buildSystemInstallPlan(tool: SetupTool, packageManager:
 export declare function buildSystemToolState(tool: SetupTool, packageManager: PackageManager, commandExists?: (command: string) => boolean): SetupSystemToolState;
 export declare function resolveSettingsPath(homeDir?: string): string;
 export declare function resolveExaKeyPath(homeDir?: string): string;
+export declare function resolveComposioKeyPath(homeDir?: string): string;
+/** Where an already-present API key is resolved from — env var wins over the
+ *  key file, matching the runtime resolvers (search/exa.ts, connectors). */
+export type ApiKeySource = 'env' | 'file';
+export interface ApiKeyPresence {
+    present: boolean;
+    source?: ApiKeySource;
+}
+export declare function detectExaKey(homeDir?: string): ApiKeyPresence;
+export declare function detectComposioKey(homeDir?: string): ApiKeyPresence;
 export declare function buildSetupInitialState(opts?: {
     manifest?: SetupPackageManifestEntry[];
     settingsPath?: string;
@@ -73,9 +117,11 @@ export declare function buildSetupStaticInstructions(opts: {
     installedPackageIds: Set<SetupPackageId>;
     systemPlans: SetupSystemInstallPlan[];
     exaKeyPath: string;
+    composioKeyPath: string;
 }): SetupStaticInstructions;
-export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemTools' | 'exaKeyPath'>): string;
+export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemTools' | 'exaKeyPath' | 'composioKeyPath'>): string;
 export declare function writeExaKey(exaKeyPath: string, exaKey: string): Promise<void>;
+export declare function writeComposioKey(composioKeyPath: string, composioKey: string): Promise<void>;
 export declare function summarizeSetupExecution(result: {
     installedPackages: string[];
     skippedPackages: string[];
@@ -83,6 +129,8 @@ export declare function summarizeSetupExecution(result: {
     skippedSystemDeps: string[];
     exaKeyWritten: boolean;
     exaKeyPath: string;
+    composioKeyWritten: boolean;
+    composioKeyPath: string;
 }): SetupExecutionSummary;
 export declare function formatSetupExecutionSummary(summary: SetupExecutionSummary): string;
 export declare function executeSetupSubmission(submission: SetupSubmission): Promise<SetupExecutionSummary>;