@dinoxx/dinox-cli 2.2.0 → 2.4.0

package/dist/gateway/assistantProjection.js

@@ -0,0 +1,193 @@
+/**
+ * Folds normalized agent events into the AI SDK `UIMessage` the app renders.
+ * Agent tools become read-only `dynamic-tool` parts (they ran on the agent's
+ * machine); approvals use the same part/metadata shape as desktop so the app's
+ * approval bar and `run.status` recovery work unchanged.
+ */
+const APPROVAL_TTL_MS = 30 * 60 * 1000;
+const MAX_PENDING_APPROVALS = 32;
+const PREVIEW_MAX_CHARS = 1500;
+const SENSITIVE_KEY = /password|token|secret|api[-_ ]?key|authorization|cookie|credential|private[-_ ]?key/i;
+export class AssistantProjection {
+    base;
+    parts = [];
+    toolIndex = new Map();
+    approvals = {};
+    revisionCounter = 0;
+    constructor(base) {
+        this.base = base;
+    }
+    get revision() {
+        return this.revisionCounter;
+    }
+    apply(event) {
+        switch (event.type) {
+            case 'text-delta':
+                this.appendText('text', event.text);
+                break;
+            case 'reasoning-delta':
+                this.appendText('reasoning', event.text);
+                break;
+            case 'tool':
+                this.applyTool(event);
+                break;
+            case 'approval-request': {
+                const requestedAt = new Date().toISOString();
+                this.approvals[event.approvalId] = {
+                    requestedAt,
+                    expiresAt: new Date(Date.parse(requestedAt) + APPROVAL_TTL_MS).toISOString(),
+                    toolName: event.toolName,
+                    toolCallId: event.toolCallId,
+                };
+                const part = this.ensureTool(event.toolCallId, event.toolName);
+                part.state = 'approval-requested';
+                part.approval = { id: event.approvalId };
+                if (event.input !== undefined)
+                    part.input = event.input;
+                break;
+            }
+            case 'approval-resolved': {
+                const part = this.findToolByApproval(event.approvalId);
+                if (part) {
+                    part.approval = { id: event.approvalId, approved: event.approved };
+                    part.state = event.approved ? 'approval-responded' : 'output-denied';
+                }
+                break;
+            }
+            case 'usage':
+                return;
+        }
+        this.revisionCounter += 1;
+    }
+    /** Closes streaming parts; called once when the turn ends. */
+    finish() {
+        for (const part of this.parts) {
+            if ((part.type === 'text' || part.type === 'reasoning') && part.state === 'streaming')
+                part.state = 'done';
+        }
+        this.revisionCounter += 1;
+    }
+    snapshot() {
+        return {
+            ...this.base,
+            role: 'assistant',
+            parts: this.parts.map((part) => ({ ...part })),
+            metadata: {
+                ...(this.base.metadata ?? {}),
+                ...(Object.keys(this.approvals).length ? { toolApprovals: { ...this.approvals } } : {}),
+            },
+        };
+    }
+    appendText(type, text) {
+        if (!text)
+            return;
+        const last = this.parts.at(-1);
+        if (last?.type === type && last.state === 'streaming') {
+            last.text = `${String(last.text ?? '')}${text}`;
+            return;
+        }
+        this.parts.push({ type, text, state: 'streaming' });
+    }
+    ensureTool(toolCallId, toolName) {
+        const index = this.toolIndex.get(toolCallId);
+        if (index !== undefined)
+            return this.parts[index];
+        // A tool call closes the text segment before it.
+        const last = this.parts.at(-1);
+        if (last && (last.type === 'text' || last.type === 'reasoning'))
+            last.state = 'done';
+        const part = { type: 'dynamic-tool', toolCallId, toolName, state: 'input-streaming', input: undefined };
+        this.toolIndex.set(toolCallId, this.parts.push(part) - 1);
+        return part;
+    }
+    findToolByApproval(approvalId) {
+        return this.parts.find((part) => part.type === 'dynamic-tool' && part.approval?.id === approvalId);
+    }
+    applyTool(event) {
+        const part = this.ensureTool(event.toolCallId, event.title || 'tool');
+        if (event.title)
+            part.toolName = event.title;
+        if (event.input !== undefined)
+            part.input = event.input;
+        switch (event.status) {
+            case 'completed':
+                part.state = 'output-available';
+                part.output = event.output ?? part.output ?? null;
+                break;
+            case 'failed':
+                part.state = 'output-error';
+                part.errorText = typeof event.output === 'string' ? event.output : 'Tool failed';
+                break;
+            case 'pending':
+            case 'running':
+                if (part.state !== 'approval-requested')
+                    part.state = 'input-available';
+                if (event.output !== undefined)
+                    part.output = event.output;
+                break;
+            default:
+                if (event.output !== undefined)
+                    part.output = event.output;
+        }
+    }
+}
+function redact(value, depth) {
+    if (depth > 4)
+        return '[…]';
+    if (Array.isArray(value))
+        return value.slice(0, 16).map((item) => redact(item, depth + 1));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .slice(0, 24)
+            .map(([key, item]) => [key, SENSITIVE_KEY.test(key) ? '[redacted]' : redact(item, depth + 1)]));
+    }
+    return value;
+}
+/** Same projection the desktop host sends: open approval requests found in the snapshot. */
+/**
+ * The reply as it is kept in the synced transcript. A computer agent's
+ * reasoning and tool calls are working state: they stream to the client while
+ * the turn runs and stay in the local run snapshot, but only the answer is
+ * stored in `c_chat_message`.
+ */
+export function toTranscriptMessage(message) {
+    const { toolApprovals: _approvals, ...metadata } = (message.metadata ?? {});
+    return {
+        ...message,
+        parts: message.parts.filter((part) => part.type === 'text' || part.type === 'file'),
+        metadata,
+    };
+}
+export function projectPendingApprovals(message, ids) {
+    if (!message)
+        return [];
+    const approvals = (message.metadata?.toolApprovals ?? {});
+    const prompts = [];
+    for (const part of message.parts) {
+        if (prompts.length >= MAX_PENDING_APPROVALS)
+            break;
+        const approvalId = part.approval?.id;
+        if (part.state !== 'approval-requested' || typeof approvalId !== 'string')
+            continue;
+        const meta = approvals[approvalId] ?? {};
+        const requestedAt = meta.requestedAt ?? new Date().toISOString();
+        let inputPreview = '';
+        try {
+            inputPreview = JSON.stringify(redact(part.input, 0)) ?? '';
+        }
+        catch {
+            inputPreview = '';
+        }
+        prompts.push({
+            approvalId,
+            runId: ids.runId,
+            threadId: ids.threadId,
+            toolCallId: String(part.toolCallId ?? meta.toolCallId ?? ''),
+            toolName: String(part.toolName ?? meta.toolName ?? 'tool'),
+            inputPreview: inputPreview.slice(0, PREVIEW_MAX_CHARS),
+            requestedAt,
+            expiresAt: meta.expiresAt ?? new Date(Date.parse(requestedAt) + APPROVAL_TTL_MS).toISOString(),
+        });
+    }
+    return prompts;
+}

package/dist/gateway/config.d.ts

@@ -0,0 +1,50 @@
+import type { GatewayDefinition, GatewayKind } from './types.js';
+/** Gateways belong to an account: each one registers a robot for that user. */
+export declare function getGatewaysFilePath(userId: string): string;
+/**
+ * A random id for this installation, created once. Unlike the hostname it
+ * never changes, so it can scope this machine's robots.
+ */
+export declare function getMachineId(): Promise<string>;
+/**
+ * Deterministic per (account, machine, agent): re-adding an agent after a removal
+ * or a lost config revives the same robot instead of registering a duplicate,
+ * and the app's bindings to it keep working.
+ */
+export declare function deriveGatewayIdentity(input: {
+    userId: string;
+    machineId: string;
+    name: string;
+    agentId?: string;
+}): {
+    id: string;
+    deviceId: string;
+};
+export declare function loadGateways(userId: string): Promise<GatewayDefinition[]>;
+/** Atomic, owner-only write: the file can hold agent commands and environment secrets. */
+export declare function saveGateways(userId: string, gateways: GatewayDefinition[]): Promise<void>;
+export declare function addGateway(userId: string, input: {
+    name: string;
+    kind: GatewayKind;
+    agentId?: string;
+    command?: string;
+    args?: string[];
+    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[];
+}): Promise<{
+    gateway: GatewayDefinition;
+    change: 'added' | 'updated' | 'unchanged';
+}>;
+export declare function findGateway(gateways: GatewayDefinition[], ref: string): GatewayDefinition | undefined;
+export declare function removeGateway(userId: string, ref: string): Promise<GatewayDefinition>;

package/dist/gateway/config.js

@@ -0,0 +1,253 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getConfigDir, normalizeUserPathSegment } from '../config/paths.js';
+import { DinoxError } from '../utils/errors.js';
+import { generateId } from '../utils/id.js';
+const GATEWAYS_FILE = 'gateways.json';
+const MACHINE_ID_FILE = 'machine-id';
+const GATEWAYS_FILE_VERSION = 1;
+const DEVICE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const NAME_MAX_LENGTH = 64;
+/** Gateways belong to an account: each one registers a robot for that user. */
+export function getGatewaysFilePath(userId) {
+    return path.join(getConfigDir(), 'users', normalizeUserPathSegment(requireUserId(userId)), GATEWAYS_FILE);
+}
+/** Pre-account location; adopted by the first account that loads its gateways. */
+function getLegacyGatewaysFilePath() {
+    return path.join(getConfigDir(), GATEWAYS_FILE);
+}
+function requireUserId(userId) {
+    const normalized = userId?.trim();
+    if (!normalized) {
+        throw new DinoxError('Log in first: gateways belong to a Dinox account (`dino auth login`)', {
+            code: 'UNAUTHENTICATED',
+        });
+    }
+    return normalized;
+}
+/**
+ * A random id for this installation, created once. Unlike the hostname it
+ * never changes, so it can scope this machine's robots.
+ */
+export async function getMachineId() {
+    const filePath = path.join(getConfigDir(), MACHINE_ID_FILE);
+    try {
+        const existing = (await fs.readFile(filePath, 'utf8')).trim();
+        if (existing)
+            return existing;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const machineId = generateId();
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    try {
+        await fs.writeFile(filePath, `${machineId}\n`, { mode: 0o600, flag: 'wx' });
+        return machineId;
+    }
+    catch (error) {
+        // Another process created it first; use theirs.
+        if (error.code !== 'EEXIST')
+            throw error;
+        return (await fs.readFile(filePath, 'utf8')).trim();
+    }
+}
+function digest(...parts) {
+    return crypto.createHash('sha256').update(parts.join('\u0000')).digest('hex');
+}
+/** UUID-shaped (version 8, name-based) so it fits c_robot.id like other ids. */
+function uuidFromHash(hex) {
+    const variant = ((parseInt(hex[16], 16) & 0x3) | 0x8).toString(16);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-${variant}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+/** What makes a gateway "the same" across re-adds: its agent type, else its name. */
+function identityKey(input) {
+    return input.agentId ? `agent:${input.agentId}` : `name:${input.name.toLowerCase()}`;
+}
+/**
+ * Deterministic per (account, machine, agent): re-adding an agent after a removal
+ * or a lost config revives the same robot instead of registering a duplicate,
+ * and the app's bindings to it keep working.
+ */
+export function deriveGatewayIdentity(input) {
+    const key = identityKey(input);
+    const id = uuidFromHash(digest('dinox-gateway-id', input.userId, input.machineId, key));
+    const deviceId = `gw-${slugify(input.agentId ?? input.name)}-${digest('dinox-gateway-device', input.userId, input.machineId, key).slice(0, 8)}`;
+    if (!DEVICE_ID_PATTERN.test(deviceId)) {
+        throw new DinoxError(`Invalid gateway device id: ${deviceId}`, { code: 'INVALID_ARGUMENT' });
+    }
+    return { id, deviceId };
+}
+function normalizeName(value) {
+    const name = value.replace(/[\u0000-\u001f\u007f]/g, '').trim();
+    if (!name) {
+        throw new DinoxError('Gateway name is required', { code: 'INVALID_ARGUMENT' });
+    }
+    return name.slice(0, NAME_MAX_LENGTH);
+}
+function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 24);
+    return slug || 'agent';
+}
+function parseGateway(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const kind = raw.kind === 'acp' || raw.kind === 'echo' ? raw.kind : null;
+    if (typeof raw.id !== 'string' ||
+        typeof raw.name !== 'string' ||
+        typeof raw.deviceId !== 'string' ||
+        !DEVICE_ID_PATTERN.test(raw.deviceId) ||
+        !kind) {
+        return null;
+    }
+    const env = raw.env && typeof raw.env === 'object' && !Array.isArray(raw.env)
+        ? Object.fromEntries(Object.entries(raw.env).filter((entry) => typeof entry[1] === 'string'))
+        : undefined;
+    return {
+        id: raw.id,
+        name: raw.name,
+        kind,
+        deviceId: raw.deviceId,
+        ...(typeof raw.agentId === 'string' && raw.agentId ? { agentId: raw.agentId } : {}),
+        ...(typeof raw.command === 'string' ? { command: raw.command } : {}),
+        ...(Array.isArray(raw.args) ? { args: raw.args.filter((arg) => typeof arg === 'string') } : {}),
+        ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}),
+        ...(env ? { env } : {}),
+        enabled: raw.enabled !== false,
+        ...(raw.dinoxTools === false ? { dinoxTools: false } : {}),
+        createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : new Date(0).toISOString(),
+    };
+}
+async function readGatewaysFile(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function loadGateways(userId) {
+    const filePath = getGatewaysFilePath(userId);
+    let text = await readGatewaysFile(filePath);
+    if (text === null) {
+        const legacyPath = getLegacyGatewaysFilePath();
+        text = await readGatewaysFile(legacyPath);
+        if (text === null)
+            return [];
+        await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        await fs.rename(legacyPath, filePath);
+    }
+    const parsed = JSON.parse(text);
+    return (Array.isArray(parsed.gateways) ? parsed.gateways : [])
+        .map(parseGateway)
+        .filter((gateway) => gateway !== null);
+}
+/** Atomic, owner-only write: the file can hold agent commands and environment secrets. */
+export async function saveGateways(userId, gateways) {
+    const filePath = getGatewaysFilePath(userId);
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    const payload = { version: GATEWAYS_FILE_VERSION, gateways };
+    const handle = await fs.open(tmpPath, 'wx', 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(tmpPath, filePath);
+}
+export async function addGateway(userId, input) {
+    const name = normalizeName(input.name);
+    if (input.kind === 'acp' && !input.command?.trim()) {
+        throw new DinoxError('ACP gateways need --command (the agent executable)', { code: 'INVALID_ARGUMENT' });
+    }
+    const gateways = await loadGateways(userId);
+    if (gateways.some((gateway) => gateway.name === name)) {
+        throw new DinoxError(`A gateway named "${name}" already exists`, { code: 'ALREADY_EXISTS' });
+    }
+    if (input.agentId && gateways.some((gateway) => gateway.agentId === input.agentId)) {
+        throw new DinoxError(`This agent is already hosted (${input.agentId})`, { code: 'ALREADY_EXISTS' });
+    }
+    const identity = deriveGatewayIdentity({
+        userId: requireUserId(userId),
+        machineId: await getMachineId(),
+        name,
+        agentId: input.agentId,
+    });
+    if (gateways.some((gateway) => gateway.id === identity.id)) {
+        throw new DinoxError(`A gateway named "${name}" already exists`, { code: 'ALREADY_EXISTS' });
+    }
+    const gateway = {
+        ...identity,
+        name,
+        kind: input.kind,
+        ...(input.agentId ? { agentId: input.agentId } : {}),
+        ...(input.command ? { command: input.command.trim() } : {}),
+        ...(input.args?.length ? { args: input.args } : {}),
+        ...(input.cwd ? { cwd: path.resolve(input.cwd) } : {}),
+        ...(input.env && Object.keys(input.env).length ? { env: input.env } : {}),
+        enabled: true,
+        createdAt: new Date().toISOString(),
+    };
+    await saveGateways(userId, [...gateways, gateway]);
+    return gateway;
+}
+function sameLaunch(a, b) {
+    return a.command === b.command && JSON.stringify(a.args ?? []) === JSON.stringify(b.args);
+}
+/**
+ * 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 async function adoptDetectedAgent(userId, agent) {
+    const gateways = await loadGateways(userId);
+    const existing = gateways.find((gateway) => gateway.agentId === agent.id) ??
+        gateways.find((gateway) => !gateway.agentId &&
+            gateway.kind === 'acp' &&
+            gateway.command !== undefined &&
+            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)) {
+            return { gateway: existing, change: 'unchanged' };
+        }
+        const updated = { ...existing, agentId: agent.id, command: agent.command, args: agent.args };
+        await saveGateways(userId, gateways.map((gateway) => (gateway.id === existing.id ? updated : gateway)));
+        return { gateway: updated, change: 'updated' };
+    }
+    const names = new Set(gateways.map((gateway) => gateway.name));
+    let name = agent.name;
+    for (let index = 2; names.has(name); index += 1)
+        name = `${agent.name} ${index}`;
+    const gateway = await addGateway(userId, {
+        name,
+        kind: 'acp',
+        agentId: agent.id,
+        command: agent.command,
+        args: agent.args,
+    });
+    return { gateway, change: 'added' };
+}
+export function findGateway(gateways, ref) {
+    return gateways.find((gateway) => gateway.id === ref || gateway.name === ref || gateway.deviceId === ref);
+}
+export async function removeGateway(userId, ref) {
+    const gateways = await loadGateways(userId);
+    const gateway = findGateway(gateways, ref);
+    if (!gateway) {
+        throw new DinoxError(`Gateway not found: ${ref}`, { code: 'NOT_FOUND' });
+    }
+    await saveGateways(userId, gateways.filter((item) => item.id !== gateway.id));
+    return gateway;
+}

package/dist/gateway/detect.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Known agents that speak ACP over stdio. Each lists launch variants in order;
+ * detection keeps the first one whose process completes an ACP handshake, so
+ * a stale guess here never produces a broken gateway.
+ */
+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. */
+    adapter?: {
+        baseBinary: string;
+        install: 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;
+export type DetectedAgent = {
+    id: string;
+    name: string;
+    /** Absolute executable path, so the daemon does not depend on the caller's PATH. */
+    command: string;
+    args: string[];
+    verified: boolean;
+    agentName: string | null;
+    agentVersion: string | null;
+    error?: string;
+    /** Set when the agent's CLI is installed but its ACP adapter is not. */
+    installHint?: 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<{
+    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;
+}): Promise<DetectedAgent[]>;

package/dist/gateway/detect.js

@@ -0,0 +1,145 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable, Writable } from 'node:stream';
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION } from '@agentclientprotocol/sdk';
+import { getPackageVersion } from '../utils/version.js';
+/**
+ * Known agents that speak ACP over stdio. Each lists launch variants in order;
+ * detection keeps the first one whose process completes an ACP handshake, so
+ * a stale guess here never produces a broken gateway.
+ */
+export const KNOWN_ACP_AGENTS = [
+    { id: 'hermes', name: 'Hermes', candidates: [['hermes', 'acp']] },
+    { id: 'openclaw', name: 'OpenClaw', candidates: [['openclaw', 'acp']] },
+    {
+        id: 'claude',
+        name: 'Claude Code',
+        candidates: [['claude-agent-acp'], ['claude-code-acp']],
+        adapter: { baseBinary: 'claude', install: 'npm install -g @agentclientprotocol/claude-agent-acp' },
+    },
+    {
+        id: 'codex',
+        name: 'Codex',
+        candidates: [['codex-acp']],
+        adapter: { baseBinary: 'codex', install: 'npm install -g @agentclientprotocol/codex-acp' },
+    },
+    { id: 'gemini', name: 'Gemini CLI', candidates: [['gemini', '--acp'], ['gemini', '--experimental-acp']] },
+    { id: 'copilot', name: 'GitHub Copilot', candidates: [['copilot', '--acp']] },
+    { id: 'cursor', name: 'Cursor Agent', candidates: [['cursor-agent', 'acp']] },
+    { id: 'opencode', name: 'OpenCode', candidates: [['opencode', 'acp']] },
+    { id: 'pi', name: 'pi', candidates: [['pi-acp']] },
+    { id: 'goose', name: 'Goose', candidates: [['goose', 'acp']] },
+    { id: 'qwen', name: 'Qwen Code', candidates: [['qwen', '--acp'], ['qwen', '--experimental-acp']] },
+    { id: 'kimi', name: 'Kimi CLI', candidates: [['kimi', 'acp'], ['kimi', '--acp']] },
+    // DeepSeek Harness: ACP is a dsh profile; the model key comes from DEEPSEEK_API_KEY.
+    { id: 'deepseek', name: 'DeepSeek Harness', candidates: [['dsh', '--profile', 'acp']] },
+    { id: 'qoder', name: 'Qoder CLI', candidates: [['qodercli', '--acp'], ['qoderclicn', '--acp']] },
+    {
+        id: 'zcode',
+        name: 'ZCode',
+        candidates: [['zcode-acp']],
+        adapter: { baseBinary: 'zcode', install: 'npm install -g zcode-acp' },
+    },
+];
+/** The known agent a manual launch command starts, by executable name and arguments. */
+export function inferAgentId(command, args = []) {
+    if (!command)
+        return undefined;
+    const binary = path.basename(command).replace(/\.(exe|cmd|bat)$/i, '');
+    return KNOWN_ACP_AGENTS.find((agent) => agent.candidates.some(([candidate, ...candidateArgs]) => candidate === binary && JSON.stringify(candidateArgs) === JSON.stringify(args)))?.id;
+}
+// Some agents cold-start slowly (OpenCode boots a local server: ~40s on first run).
+const PROBE_TIMEOUT_MS = 45_000;
+export async function findExecutable(name, envPath = process.env.PATH ?? '') {
+    const extensions = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const dir of envPath.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(dir, `${name}${extension}`);
+            try {
+                await fs.access(candidate, fs.constants.X_OK);
+                if ((await fs.stat(candidate)).isFile())
+                    return candidate;
+            }
+            catch {
+                // not here
+            }
+        }
+    }
+    return null;
+}
+/** Starts the agent, runs `initialize`, and stops it. Never leaves the process running. */
+export async function probeAcpAgent(command, args, timeoutMs = PROBE_TIMEOUT_MS) {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'ignore'], env: process.env });
+    let timer;
+    try {
+        const exited = new Promise((_, reject) => {
+            child.once('error', reject);
+            child.once('exit', (code) => reject(new Error(`exited before handshake (code ${code})`)));
+        });
+        const timedOut = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error('no ACP handshake within timeout')), timeoutMs);
+        });
+        const connection = new ClientSideConnection(() => ({
+            sessionUpdate: async () => { },
+            requestPermission: async () => ({ outcome: { outcome: 'cancelled' } }),
+        }), ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout)));
+        const init = await Promise.race([
+            connection.initialize({
+                protocolVersion: PROTOCOL_VERSION,
+                clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+                clientInfo: { name: 'dinox-gateway-detect', version: getPackageVersion() },
+            }),
+            exited,
+            timedOut,
+        ]);
+        return { agentName: init.agentInfo?.name ?? null, agentVersion: init.agentInfo?.version ?? null };
+    }
+    finally {
+        clearTimeout(timer);
+        child.stdin.destroy();
+        child.kill('SIGTERM');
+    }
+}
+/** Finds installed ACP agents; with `probe`, keeps only launch variants that handshake. */
+export async function detectAcpAgents(options = {}) {
+    const probe = options.probe ?? true;
+    const results = await Promise.all(KNOWN_ACP_AGENTS.map(async (agent) => {
+        let lastError;
+        for (const [binary, ...args] of agent.candidates) {
+            const command = await findExecutable(binary);
+            if (!command)
+                continue;
+            if (!probe) {
+                return { id: agent.id, name: agent.name, command, args, verified: false, agentName: null, agentVersion: null };
+            }
+            try {
+                const info = await probeAcpAgent(command, args);
+                return { id: agent.id, name: agent.name, command, args, verified: true, ...info };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        if (!lastError) {
+            if (agent.adapter && (await findExecutable(agent.adapter.baseBinary))) {
+                const [binary, ...args] = agent.candidates[0];
+                return {
+                    id: agent.id,
+                    name: agent.name,
+                    command: binary,
+                    args,
+                    verified: false,
+                    agentName: null,
+                    agentVersion: null,
+                    installHint: agent.adapter.install,
+                };
+            }
+            return null;
+        }
+        const [binary, ...args] = agent.candidates[0];
+        const command = (await findExecutable(binary)) ?? binary;
+        return { id: agent.id, name: agent.name, command, args, verified: false, agentName: null, agentVersion: null, error: lastError };
+    }));
+    return results.filter((agent) => agent !== null);
+}