@dinoxx/dinox-cli 2.9.0 → 2.11.0

package/dist/commands/auth/index.js

@@ -1,4 +1,7 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
+import os from 'node:os';
+import { authApiBaseFromTokenEndpoint, DevicePairCancelled, deviceNameFromHostname, pollDevicePairLogin, prepareCliDevice, renderTerminalQr, revokeDeviceBinding, saveDevicePairResult, } from '../../auth/devicePair.js';
 import { buildPendingAuthConfig, fetchUserInfoWithAuthorization, hydrateResolvedAuthIdentity, mergeAuthIdentityIntoConfig, persistedAuthStateMatches, rotatePersistedAuthStateRevision, } from '../../auth/userInfo.js';
 import { getLegacyPowerSyncDbPath, getPowerSyncDbPath } from '../../config/paths.js';
 import { loadConfig, updateConfig } from '../../config/store.js';
@@ -227,6 +230,45 @@ export async function performAuthLogin(rawToken, syncTimeout, overrides = {}) {
     }
     return outcome.value;
 }
+async function loginWithDeviceQr() {
+    const config = await loadConfig();
+    const resolved = resolveConfig(config);
+    const apiBase = authApiBaseFromTokenEndpoint(resolved.powersync.tokenEndpoint);
+    const store = { load: loadConfig, update: updateConfig };
+    const prepared = await prepareCliDevice({
+        store,
+        apiBase,
+        authorization: normalizeAuthToken(config.auth?.authorization),
+        deviceBindingId: config.auth?.deviceBindingId,
+        randomUUID: crypto.randomUUID,
+    });
+    if (prepared.revokeWarning)
+        printHumanReadableWarning(prepared.revokeWarning);
+    const abort = new AbortController();
+    const onSigint = () => abort.abort();
+    process.once('SIGINT', onSigint);
+    try {
+        const paired = await pollDevicePairLogin({
+            apiBase,
+            deviceId: prepared.deviceId,
+            deviceName: deviceNameFromHostname(os.hostname()),
+            renderQr: renderTerminalQr,
+            writeStderr: (text) => { process.stderr.write(text); },
+            signal: abort.signal,
+        });
+        return { token: paired.token, deviceBindingId: paired.deviceBindingId };
+    }
+    catch (error) {
+        if (error instanceof DevicePairCancelled) {
+            process.exitCode = 130;
+            process.exit(130);
+        }
+        throw error;
+    }
+    finally {
+        process.off('SIGINT', onSigint);
+    }
+}
 async function runAuthLogin(context) {
     const options = context.options;
     if (context.args.token && options.tokenStdin) {
@@ -234,17 +276,35 @@ async function runAuthLogin(context) {
             code: 'USAGE_ERROR',
         });
     }
-    const token = options.tokenStdin ? await readAuthTokenFromStdin() : context.args.token;
-    const rawToken = normalizeAuthToken(token);
-    if (!rawToken) {
-        throw new DinoxError('Token is required');
-    }
+    const explicitToken = options.tokenStdin ? await readAuthTokenFromStdin() : context.args.token;
+    let rawToken = normalizeAuthToken(explicitToken);
+    let pairedDeviceBindingId;
     const envToken = readEnvAuthToken();
+    if (options.tokenStdin || context.args.token) {
+        if (!rawToken) {
+            throw new DinoxError('Token is required');
+        }
+    }
+    else {
+        // A scanned login can never equal DINOX_TOKEN, so refuse before the phone binds this computer.
+        if (envToken) {
+            throw new DinoxError('DINOX_TOKEN is set, so a QR login would be overridden by it. Unset DINOX_TOKEN before running `dino auth login`, or log in with that token via `--token-stdin`.', { code: 'USAGE_ERROR' });
+        }
+        const paired = await loginWithDeviceQr();
+        rawToken = paired.token;
+        pairedDeviceBindingId = paired.deviceBindingId;
+    }
     if (envToken && envToken !== rawToken) {
         throw new DinoxError('DINOX_TOKEN is set and differs from the login token. Unset DINOX_TOKEN before running `dino auth login`, or use the same token.');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
     const result = await performAuthLogin(rawToken, context.globals.syncTimeout);
+    if (pairedDeviceBindingId) {
+        await saveDevicePairResult({
+            store: { load: loadConfig, update: updateConfig },
+            deviceBindingId: pairedDeviceBindingId,
+        });
+    }
     // After the login lock is released: the service starts the daemon under the new login.
     const daemonService = await autoInstallDaemonService();
     if (structuredOutput) {
@@ -269,6 +329,22 @@ async function runAuthLogoutLocked(options) {
     const config = await loadConfig();
     const resolved = resolveConfig(config);
     const envTokenActive = Boolean(readEnvAuthToken());
+    const savedToken = normalizeAuthToken(config.auth?.authorization);
+    const deviceBindingId = config.auth?.deviceBindingId?.trim();
+    if (deviceBindingId) {
+        if (!savedToken) {
+            printHumanReadableWarning(`warning: could not revoke paired device ${deviceBindingId} (no saved token). Continuing.`);
+        }
+        else {
+            const revoked = await revokeDeviceBinding({
+                apiBase: authApiBaseFromTokenEndpoint(resolved.powersync.tokenEndpoint),
+                deviceBindingId,
+                authorization: savedToken,
+            });
+            if (revoked.warning)
+                printHumanReadableWarning(revoked.warning);
+        }
+    }
     const daemonInfo = await getDaemonInfo();
     let initiallyResolvedUserId = resolved.auth.userId;
     if (!initiallyResolvedUserId
@@ -340,6 +416,8 @@ async function runAuthLogoutLocked(options) {
                     username: undefined,
                     email: undefined,
                     userInfoSyncedAt: undefined,
+                    deviceBindingId: undefined,
+                    deviceId: undefined,
                 },
             });
         }, { timeoutMs: resolved.sync.timeoutMs });
@@ -489,8 +567,8 @@ export const authCommandGroup = {
     commands: [
         {
             name: 'login',
-            description: 'Save login token and verify PowerSync connectivity',
-            arguments: [{ syntax: '[token]', description: 'Login token (omit when using --token-stdin)' }],
+            description: 'Log in by scanning a QR code, or save a token and verify PowerSync connectivity',
+            arguments: [{ syntax: '[token]', description: 'Login token (omit to scan a QR code, or when using --token-stdin)' }],
             options: [{ flags: '--token-stdin', description: 'Read the login token from piped stdin instead of argv', type: 'boolean' }],
             schema: {
                 path: 'auth.login',
@@ -502,7 +580,11 @@ export const authCommandGroup = {
                     summary: 'Login verification result',
                     fields: ['verified', 'endpoint', 'dbPath', 'stale', 'lastSyncedAt', 'userId', 'daemonService'],
                 },
-                examples: ['dino auth login --token-stdin --format json'],
+                examples: [
+                    'dino auth login',
+                    'dino auth login --format json',
+                    'dino auth login --token-stdin --format json',
+                ],
             },
             action: runAuthLogin,
         },

package/dist/commands/gateway/index.js

@@ -116,8 +116,23 @@ async function runAdd(context) {
     printHumanReadableLine(`Added gateway "${gateway.name}" as device ${gateway.deviceId}.`);
     printStatuses(statuses);
 }
+function formatDetectedAgent(agent) {
+    const launch = [agent.command, ...agent.args].join(' ');
+    const label = agent.verified
+        ? `ready${agent.agentVersion ? ` (${agent.agentName ?? agent.name} ${agent.agentVersion})` : ''}`
+        : agent.installHint
+            ? `installed, needs its ACP adapter: ${agent.installHint}`
+            : `not responding: ${agent.error ?? 'unknown'}`;
+    return `${agent.name}: ${label} · ${launch}`;
+}
 async function runDetect(context) {
-    const detected = await detectAcpAgents({ probe: true });
+    const structured = Boolean(getRequestedStructuredOutputFormat());
+    if (!structured)
+        printHumanReadableLine('Checking installed ACP agents...');
+    const detected = await detectAcpAgents({
+        probe: true,
+        onDetected: structured ? undefined : (agent) => printHumanReadableLine(formatDetectedAgent(agent)),
+    });
     const added = [];
     const updated = [];
     if (context.options.add) {
@@ -146,15 +161,6 @@ async function runDetect(context) {
         printHumanReadableLine('No ACP agents found on PATH.');
         return;
     }
-    for (const agent of detected) {
-        const launch = [agent.command, ...agent.args].join(' ');
-        const label = agent.verified
-            ? `ready${agent.agentVersion ? ` (${agent.agentName ?? agent.name} ${agent.agentVersion})` : ''}`
-            : agent.installHint
-                ? `installed, needs its ACP adapter: ${agent.installHint}`
-                : `not responding: ${agent.error ?? 'unknown'}`;
-        printHumanReadableLine(`${agent.name}: ${label} · ${launch}`);
-    }
     for (const gateway of added)
         printHumanReadableLine(`Added gateway "${gateway.name}" (${gateway.deviceId}).`);
     for (const gateway of updated) {

package/dist/commands/graph/index.js

@@ -48,6 +48,8 @@ async function runGraphCommand(context, onlineAction, offlineAction) {
         });
     }
     catch (error) {
+        if (error instanceof DinoxError && error.code === 'AUTH_REQUIRED')
+            throw error;
         const message = error instanceof Error ? error.message : String(error);
         throw new DinoxError(`Daemon execution failed: ${message}`, {
             code: 'DAEMON_UNAVAILABLE',

package/dist/commands/schema/renderSkills.js

@@ -242,7 +242,7 @@ export function renderBundledSkillReference() {
         lines.push('```');
         lines.push('');
         if (section.title === 'Auth') {
-            lines.push('Agent safety: the positional login-token form is legacy compatibility and is intentionally omitted from this agent-facing signature. Agent workflows must never place a Dinox authentication token in argv; use `--token-stdin` from the user\'s own shell or secret store.');
+            lines.push('Agent safety: the positional login-token form is legacy compatibility and is intentionally omitted from this agent-facing signature. Agent workflows must never place a Dinox authentication token in argv. Prefer `dino auth login` in the user\'s terminal (QR code; it blocks for up to 10 minutes; in Claude Code the user can type `! dino auth login`). Use `--token-stdin` only from the user\'s own shell or secret store.');
             lines.push('');
         }
     }
@@ -287,7 +287,7 @@ export function renderPortableRuntimeContract() {
         '- On a nonzero exit, parse structured stderr. Use top-level `code`, `recoverable`, `exit_code`, and `suggested_action`; inspect `error` for details. `dino schema errors --format json` lists every code and its exit status.',
         '- A direct user request for an exact write authorizes that write when the dry-run matches. Ask again before delete, overwrite, merge, bulk mutation, local-cache removal, repair, global CLI update, or whenever targets or impact are ambiguous.',
         '- A dry-run does not apply the planned mutation, but an online PowerSync runtime may flush older queued writes. Use `--offline` only when the user accepts stale local-cache semantics.',
-        '- Do not ask for Dinox authentication credentials in chat or place a Dinox authentication token in argv. The `dino` child process must inherit `DINOX_TOKEN` or receive it from the host secret store at execution time; if the host cannot inject it safely, have the user perform persistent `--token-stdin` login in their own terminal.',
+        '- Do not ask for Dinox authentication credentials in chat or place a Dinox authentication token in argv. For persistent login, have the user run `dino auth login` in their own terminal and scan the QR code with the Dinox app. In Claude Code they can type `! dino auth login`. That command blocks for up to 10 minutes; say so before an agent runs it. Inherited `DINOX_TOKEN` and `dino auth login --token-stdin` remain for CI and secret stores.',
         '- Execute `dino` in an environment that can access the intended CLI binary, Dinox config/cache, and injected secret. Host-turn secret injection does not automatically cross into a sandbox or remote execution backend; never copy a secret through prompts to bridge that boundary.',
         '- If the host times out before receiving a structured envelope, treat the outcome as unknown. Verify freshness or the write postcondition before retrying.',
         '- Before claiming complete, current, all, none, latest, or an exact count, verify the command\'s freshness field is false (usually `data.stale`; note search uses `data.meta.stale`), inspect `_notice`, and check pagination or truncation fields returned by the command.',

package/dist/commands/update.d.ts

@@ -1,12 +1,23 @@
 import { Command } from 'commander';
 import type { CommandDescriptor } from './descriptor/types.js';
+import { type MissingAcpAdapter } from '../gateway/detect.js';
 type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
 type LogFn = (...parts: unknown[]) => void;
+export type AcpAdapterInstallResult = {
+    id: string;
+    name: string;
+    package: string;
+    status: 'installed' | 'failed';
+    error: string | null;
+};
 type UpdateCommandDeps = {
     detectPackageManager: () => PackageManager;
     runUpdate: (pm: PackageManager, options: {
         structuredOutput: boolean;
     }) => Promise<void>;
+    installAcpAdapters: (pm: PackageManager, options: {
+        structuredOutput: boolean;
+    }) => Promise<AcpAdapterInstallResult[]>;
     getVersion: () => string;
     getLatestVersion: () => Promise<string | null>;
     log: LogFn;
@@ -20,7 +31,12 @@ type UpdateSpawnSpec = {
     args: string[];
     shell: boolean;
 };
+export declare function resolvePackageManagerSpawn(pm: PackageManager, args: string[], platform?: NodeJS.Platform): UpdateSpawnSpec;
 export declare function resolveUpdateSpawnSpec(pm: PackageManager, platform?: NodeJS.Platform): UpdateSpawnSpec;
+/** Installs ACP adapters for local agent CLIs that do not already have one. */
+export declare function installMissingAcpAdapters(pm: PackageManager, options: {
+    structuredOutput: boolean;
+}, missing?: MissingAcpAdapter[]): Promise<AcpAdapterInstallResult[]>;
 export declare function createUpdateCommandDescriptor(overrides?: Partial<UpdateCommandDeps>): CommandDescriptor;
 export declare const updateCommandDescriptor: CommandDescriptor;
 export declare function registerUpdateCommand(program: Command, overrides?: Partial<UpdateCommandDeps>): void;

package/dist/commands/update.js

@@ -6,6 +6,7 @@ import { getSkillsReleaseMetadata } from '../constants/links.js';
 import { RETIRED_SKILLS, RETIRED_SKILLS_CLEANUP, formatRetiredSkillsSummary, } from '../skills/retired.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../utils/output.js';
 import { DinoxError } from '../utils/errors.js';
+import { findMissingAcpAdapters } from '../gateway/detect.js';
 import { fetchLatestPublishedVersion } from '../utils/updateNotice.js';
 import { getPackageVersion } from '../utils/version.js';
 const PACKAGE_NAME = '@dinoxx/dinox-cli';
@@ -51,21 +52,31 @@ const PM_COMMANDS = {
     yarn: { bin: 'yarn', args: ['global', 'add', `${PACKAGE_NAME}@latest`] },
     bun: { bin: 'bun', args: ['add', '--global', `${PACKAGE_NAME}@latest`] },
 };
-export function resolveUpdateSpawnSpec(pm, platform = process.platform) {
-    const { bin, args } = PM_COMMANDS[pm];
-    const usesWindowsCommandShim = platform === 'win32' && bin !== 'bun';
+export function resolvePackageManagerSpawn(pm, args, platform = process.platform) {
+    const usesWindowsCommandShim = platform === 'win32' && pm !== 'bun';
     if (usesWindowsCommandShim) {
         return {
-            command: [`${bin}.cmd`, ...args].join(' '),
+            command: [`${pm}.cmd`, ...args].join(' '),
             args: [],
             shell: true,
         };
     }
-    return {
-        command: bin,
-        args: [...args],
-        shell: false,
-    };
+    return { command: pm, args: [...args], shell: false };
+}
+export function resolveUpdateSpawnSpec(pm, platform = process.platform) {
+    return resolvePackageManagerSpawn(pm, PM_COMMANDS[pm].args, platform);
+}
+function globalInstallArgs(pm, packageName) {
+    switch (pm) {
+        case 'npm':
+            return ['install', '--global', packageName];
+        case 'pnpm':
+            return ['add', '--global', packageName];
+        case 'yarn':
+            return ['global', 'add', packageName];
+        case 'bun':
+            return ['add', '--global', packageName];
+    }
 }
 function appendBoundedOutput(current, chunk) {
     if (Buffer.byteLength(current, 'utf8') >= MAX_CAPTURED_UPDATE_OUTPUT_BYTES) {
@@ -74,8 +85,8 @@ function appendBoundedOutput(current, chunk) {
     const remaining = MAX_CAPTURED_UPDATE_OUTPUT_BYTES - Buffer.byteLength(current, 'utf8');
     return current + chunk.subarray(0, remaining).toString('utf8');
 }
-function runUpdate(pm, options) {
-    const { command, args, shell } = resolveUpdateSpawnSpec(pm);
+function runPackageManager(pm, packageArgs, options) {
+    const { command, args, shell } = resolvePackageManagerSpawn(pm, packageArgs);
     const invocation = [command, ...args].join(' ');
     return new Promise((resolve, reject) => {
         let stdout = '';
@@ -120,10 +131,38 @@ function runUpdate(pm, options) {
         });
     });
 }
+function runUpdate(pm, options) {
+    return runPackageManager(pm, PM_COMMANDS[pm].args, options);
+}
+function adapterErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Installs ACP adapters for local agent CLIs that do not already have one. */
+export async function installMissingAcpAdapters(pm, options, missing) {
+    const adapters = missing ?? await findMissingAcpAdapters();
+    const results = [];
+    for (const adapter of adapters) {
+        try {
+            await runPackageManager(pm, globalInstallArgs(pm, adapter.packageName), options);
+            results.push({ id: adapter.id, name: adapter.name, package: adapter.packageName, status: 'installed', error: null });
+        }
+        catch (error) {
+            results.push({
+                id: adapter.id,
+                name: adapter.name,
+                package: adapter.packageName,
+                status: 'failed',
+                error: adapterErrorMessage(error),
+            });
+        }
+    }
+    return results;
+}
 function resolveDeps(overrides) {
     return {
         detectPackageManager,
         runUpdate,
+        installAcpAdapters: (pm, options) => installMissingAcpAdapters(pm, options),
         getVersion: getPackageVersion,
         getLatestVersion: fetchLatestPublishedVersion,
         log: logHumanReadable,
@@ -185,6 +224,7 @@ export function createUpdateCommandDescriptor(overrides = {}) {
                     'skillsInstallCommand',
                     'retiredSkills',
                     'retiredSkillsCleanup',
+                    'acpAdapters',
                 ],
             },
             examples: ['dino update', 'dino update --package-manager pnpm --format json'],
@@ -199,6 +239,7 @@ export function createUpdateCommandDescriptor(overrides = {}) {
                 deps.log(`updating ${PACKAGE_NAME} via ${pm}...`);
             }
             await deps.runUpdate(pm, { structuredOutput });
+            const acpAdapters = await deps.installAcpAdapters(pm, { structuredOutput });
             const observedVersion = deps.getVersion();
             const version = observedVersion !== previousVersion
                 ? observedVersion
@@ -219,10 +260,19 @@ export function createUpdateCommandDescriptor(overrides = {}) {
                     skillsInstallCommand: skills.installCommand,
                     retiredSkills: RETIRED_SKILLS,
                     retiredSkillsCleanup: RETIRED_SKILLS_CLEANUP,
+                    acpAdapters,
                 });
                 return;
             }
             deps.log(`done: ${version}`);
+            for (const adapter of acpAdapters) {
+                if (adapter.status === 'installed') {
+                    deps.log(`installed ACP adapter ${adapter.package} for ${adapter.name}`);
+                }
+                else {
+                    deps.log(`warning: could not install ACP adapter ${adapter.package} for ${adapter.name} (${adapter.error})`);
+                }
+            }
             printSkillsReminder(deps.log, version);
         },
     };

package/dist/config/types.d.ts

@@ -13,6 +13,10 @@ export type DinoxConfig = {
         userInfoSyncedAt?: string;
         /** Internal CAS token changed by every persisted login/logout transition. */
         stateRevision?: string;
+        /** Stable id for QR login (`cli-` + uuid). Reused for the same account on this machine. */
+        deviceId?: string;
+        /** `c_user_device.id` from the last successful QR login. */
+        deviceBindingId?: string;
     };
     powersync?: {
         /** PowerSync sync service endpoint (downloads/subscriptions). */

package/dist/daemon/ensure.js

@@ -31,6 +31,13 @@ function matchesRuntimeTokenBinding(info, version, config) {
 async function ensureDaemonRunningUnlocked() {
     const expectedVersion = getPackageVersion();
     const baseConfig = resolveConfig(await loadConfig());
+    // A daemon cannot serve anything without a login; say so now instead of
+    // waiting for a launch that cannot become ready.
+    if (!baseConfig.auth.authorization) {
+        throw new DinoxError('Not logged in. Set DINOX_TOKEN or pipe a token to `dino auth login --token-stdin`.', {
+            code: 'AUTH_REQUIRED',
+        });
+    }
     const info = await getDaemonInfo();
     if (info && matchesRuntimeTokenBinding(info, expectedVersion, baseConfig)) {
         return;

package/dist/daemon/route.js

@@ -25,6 +25,8 @@ export async function routeRead(globals, daemonMethod, daemonParams, localRun) {
         return (await sendDaemonRequest(daemonMethod, daemonParams));
     }
     catch (error) {
+        if (error instanceof DinoxError && error.code === 'AUTH_REQUIRED')
+            throw error;
         const message = error instanceof Error ? error.message : String(error);
         throw new DinoxError(`Daemon execution failed: ${message}`, {
             code: 'DAEMON_UNAVAILABLE',

package/dist/gateway/config.d.ts

@@ -32,16 +32,12 @@ export declare function addGateway(userId: string, input: {
     cwd?: string;
     env?: Record<string, string>;
 }): Promise<GatewayDefinition>;
-/**
- * Hosts a detected agent once. An agent already hosted, matched by type (or, for
- * gateways from before types were recorded, by executable name and arguments),
- * is updated in place when its executable moved, e.g. after a Node upgrade.
- */
 export declare function adoptDetectedAgent(userId: string, agent: {
     id: string;
     name: string;
     command: string;
     args: string[];
+    env?: Record<string, string>;
 }): Promise<{
     gateway: GatewayDefinition;
     change: 'added' | 'updated' | 'unchanged';

package/dist/gateway/config.js

@@ -214,6 +214,19 @@ function sameLaunch(a, b) {
  * gateways from before types were recorded, by executable name and arguments),
  * is updated in place when its executable moved, e.g. after a Node upgrade.
  */
+function mergeRequiredEnv(existing, required) {
+    if (!required)
+        return { env: existing, changed: false };
+    const env = { ...(existing ?? {}) };
+    let changed = false;
+    for (const [key, value] of Object.entries(required)) {
+        if (env[key] === undefined) {
+            env[key] = value;
+            changed = true;
+        }
+    }
+    return { env, changed };
+}
 export async function adoptDetectedAgent(userId, agent) {
     const gateways = await loadGateways(userId);
     const existing = gateways.find((gateway) => gateway.agentId === agent.id) ??
@@ -223,10 +236,17 @@ export async function adoptDetectedAgent(userId, agent) {
             path.basename(gateway.command) === path.basename(agent.command) &&
             JSON.stringify(gateway.args ?? []) === JSON.stringify(agent.args));
     if (existing) {
-        if (existing.agentId === agent.id && sameLaunch(existing, agent)) {
+        const requiredEnv = mergeRequiredEnv(existing.env, agent.env);
+        if (existing.agentId === agent.id && sameLaunch(existing, agent) && !requiredEnv.changed) {
             return { gateway: existing, change: 'unchanged' };
         }
-        const updated = { ...existing, agentId: agent.id, command: agent.command, args: agent.args };
+        const updated = {
+            ...existing,
+            agentId: agent.id,
+            command: agent.command,
+            args: agent.args,
+            ...(requiredEnv.env ? { env: requiredEnv.env } : {}),
+        };
         await saveGateways(userId, gateways.map((gateway) => (gateway.id === existing.id ? updated : gateway)));
         return { gateway: updated, change: 'updated' };
     }
@@ -240,6 +260,7 @@ export async function adoptDetectedAgent(userId, agent) {
         agentId: agent.id,
         command: agent.command,
         args: agent.args,
+        ...(agent.env ? { env: agent.env } : {}),
     });
     return { gateway, change: 'added' };
 }

package/dist/gateway/detect.d.ts

@@ -7,14 +7,22 @@ export declare const KNOWN_ACP_AGENTS: ReadonlyArray<{
     id: string;
     name: string;
     candidates: string[][];
-    /** The agent's own CLI and the ACP adapter to install when only the CLI is present. */
+    /** Passed to the agent process. Saved on the gateway when this launch is adopted. */
+    env?: Record<string, string>;
+    /** The agent's own CLI, and the global package that provides ACP when that CLI has none. */
     adapter?: {
         baseBinary: string;
-        install: string;
+        packageName: string;
     };
 }>;
 /** The known agent a manual launch command starts, by executable name and arguments. */
 export declare function inferAgentId(command: string | undefined, args?: string[]): string | undefined;
+/** A launch stayed up but never completed the ACP handshake. Further flags of that agent are not tried. */
+export declare class AcpProbeTimeoutError extends Error {
+    constructor();
+}
+/** A quick failure can be a wrong flag. A timeout means that agent is not going to answer. */
+export declare function shouldTryNextAcpCandidate(error: unknown): boolean;
 export type DetectedAgent = {
     id: string;
     name: string;
@@ -27,14 +35,29 @@ export type DetectedAgent = {
     error?: string;
     /** Set when the agent's CLI is installed but its ACP adapter is not. */
     installHint?: string;
+    /** Environment the handshake needed. Stored on the gateway when adopted. */
+    env?: Record<string, string>;
 };
 export declare function findExecutable(name: string, envPath?: string): Promise<string | null>;
 /** Starts the agent, runs `initialize`, and stops it. Never leaves the process running. */
-export declare function probeAcpAgent(command: string, args: string[], timeoutMs?: number): Promise<{
+export declare function probeAcpAgent(command: string, args: string[], timeoutMs?: number, env?: Record<string, string>): Promise<{
     agentName: string | null;
     agentVersion: string | null;
 }>;
 /** Finds installed ACP agents; with `probe`, keeps only launch variants that handshake. */
 export declare function detectAcpAgents(options?: {
     probe?: boolean;
+    timeoutMs?: number;
+    /** Called as soon as one agent finishes, so a slow handshake does not hide the ones already done. */
+    onDetected?: (agent: DetectedAgent) => void;
 }): Promise<DetectedAgent[]>;
+export type MissingAcpAdapter = {
+    id: string;
+    name: string;
+    packageName: string;
+};
+/**
+ * Agents whose own CLI is on PATH but none of the ACP launch commands are.
+ * Those need a global adapter package before a gateway can start them.
+ */
+export declare function findMissingAcpAdapters(envPath?: string): Promise<MissingAcpAdapter[]>;