@dinoxx/dinox-cli 2.3.0 → 2.4.0

package/dist/gateway/adapters/acp.js

@@ -0,0 +1,285 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import { Readable, Writable } from 'node:stream';
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from '@agentclientprotocol/sdk';
+import { generateId } from '../../utils/id.js';
+import { getPackageVersion } from '../../utils/version.js';
+const TOOL_STATUS = {
+    pending: 'pending',
+    in_progress: 'running',
+    completed: 'completed',
+    failed: 'failed',
+};
+const STOP_REASON = {
+    end_turn: 'end_turn',
+    max_tokens: 'max_tokens',
+    max_turn_requests: 'max_tokens',
+    refusal: 'refusal',
+    cancelled: 'cancelled',
+};
+function toolContentText(content) {
+    const text = (content ?? [])
+        .map((item) => (item.type === 'content' && item.content.type === 'text' ? item.content.text : ''))
+        .filter(Boolean)
+        .join('\n');
+    return text || undefined;
+}
+/** Select options only; boolean toggles have no use in the app yet. */
+export function normalizeConfigOptions(options) {
+    const normalized = [];
+    for (const option of options ?? []) {
+        if (option.type !== 'select')
+            continue;
+        const values = [];
+        for (const entry of option.options) {
+            if ('group' in entry) {
+                for (const value of entry.options) {
+                    values.push({ value: value.value, name: value.name, description: value.description ?? null, group: entry.name });
+                }
+            }
+            else {
+                values.push({ value: entry.value, name: entry.name, description: entry.description ?? null, group: null });
+            }
+        }
+        normalized.push({
+            id: option.id,
+            name: option.name,
+            category: option.category ?? null,
+            description: option.description ?? null,
+            currentValue: option.currentValue,
+            values,
+        });
+    }
+    return normalized;
+}
+function pickOption(options, approved) {
+    const preferred = approved ? ['allow_once', 'allow_always'] : ['reject_once', 'reject_always'];
+    for (const kind of preferred) {
+        const option = options.find((item) => item.kind === kind);
+        if (option)
+            return option;
+    }
+    return undefined;
+}
+/**
+ * Drives any Agent Client Protocol agent over stdio (`hermes acp`, `openclaw acp`,
+ * `claude-code-acp`, `codex-acp`, `pi-acp`, ...). One long-lived process per
+ * gateway hosts every thread's session; the agent keeps the conversation, so
+ * each turn sends only the new prompt.
+ */
+export class AcpGatewayAdapter {
+    gateway;
+    log;
+    mcpServers;
+    kind = 'acp';
+    process = null;
+    starting = null;
+    turns = new Map();
+    /** The latest settings any session reported: the agent-wide choices the app lists. */
+    catalog = null;
+    constructor(gateway, log = () => { }, 
+    /** MCP servers offered to every session, e.g. the Dinox knowledge tools. */
+    mcpServers = []) {
+        this.gateway = gateway;
+        this.log = log;
+        this.mcpServers = mcpServers;
+    }
+    info() {
+        const agentInfo = this.process?.init.agentInfo;
+        return { kind: this.kind, agentName: agentInfo?.name ?? null, agentVersion: agentInfo?.version ?? null };
+    }
+    async runTurn(input) {
+        const agent = await this.ensureProcess();
+        const sessionId = await this.resolveSession(agent, input.sessionId);
+        await this.applyConfig(agent, sessionId, input.config);
+        this.turns.set(sessionId, { onEvent: input.onEvent, awaitApproval: input.awaitApproval });
+        const onAbort = () => {
+            void agent.connection.cancel({ sessionId }).catch(() => undefined);
+        };
+        input.signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            const prompt = [{ type: 'text', text: input.prompt }];
+            for (const resource of input.resources) {
+                prompt.push({ type: 'resource_link', uri: resource.uri, name: resource.name, mimeType: resource.mediaType ?? null });
+            }
+            const response = await agent.connection.prompt({ sessionId, prompt });
+            return { sessionId, stopReason: STOP_REASON[response.stopReason] ?? 'end_turn' };
+        }
+        catch (error) {
+            if (input.signal.aborted)
+                return { sessionId, stopReason: 'cancelled' };
+            return { sessionId, stopReason: 'error', error: error instanceof Error ? error.message : String(error) };
+        }
+        finally {
+            input.signal.removeEventListener('abort', onAbort);
+            this.turns.delete(sessionId);
+        }
+    }
+    async describeConfig() {
+        if (this.catalog)
+            return this.catalog;
+        const agent = await this.ensureProcess();
+        if (this.catalog)
+            return this.catalog;
+        // No session yet: open one only to read the agent's choices. It never runs a turn.
+        const created = await agent.connection.newSession({ cwd: this.gateway.cwd ?? os.homedir(), mcpServers: [] });
+        this.rememberConfig(agent, created.sessionId, created.configOptions);
+        return this.catalog ?? [];
+    }
+    async dispose() {
+        const agent = this.process;
+        this.process = null;
+        this.starting = null;
+        if (!agent)
+            return;
+        agent.child.stdin.end();
+        agent.child.kill('SIGTERM');
+    }
+    async resolveSession(agent, sessionId) {
+        const cwd = this.gateway.cwd ?? os.homedir();
+        if (sessionId && agent.liveSessions.has(sessionId))
+            return sessionId;
+        if (sessionId && agent.init.agentCapabilities?.loadSession) {
+            try {
+                // No turn is registered yet, so the history the agent replays is ignored.
+                const loaded = await agent.connection.loadSession({ sessionId, cwd, mcpServers: this.mcpServers });
+                agent.liveSessions.add(sessionId);
+                this.rememberConfig(agent, sessionId, loaded.configOptions);
+                return sessionId;
+            }
+            catch (error) {
+                this.log('session/load failed; starting a new session', { sessionId, error: String(error) });
+            }
+        }
+        const created = await agent.connection.newSession({ cwd, mcpServers: this.mcpServers });
+        agent.liveSessions.add(created.sessionId);
+        this.rememberConfig(agent, created.sessionId, created.configOptions);
+        return created.sessionId;
+    }
+    /**
+     * Brings the session to the requested settings before its turn. Entries the
+     * agent does not offer are skipped, so a stale choice never fails the run.
+     */
+    async applyConfig(agent, sessionId, config) {
+        for (const [configId, value] of Object.entries(config ?? {})) {
+            const option = agent.sessionConfig.get(sessionId)?.find((item) => item.id === configId);
+            if (!option || option.currentValue === value)
+                continue;
+            if (!option.values.some((item) => item.value === value)) {
+                this.log('agent setting not offered; skipped', { configId, value });
+                continue;
+            }
+            try {
+                const response = await agent.connection.setSessionConfigOption({ sessionId, configId, value });
+                this.rememberConfig(agent, sessionId, response.configOptions);
+            }
+            catch (error) {
+                this.log('agent setting failed; continuing with the current one', { configId, error: String(error) });
+            }
+        }
+    }
+    rememberConfig(agent, sessionId, options) {
+        if (!options)
+            return;
+        const normalized = normalizeConfigOptions(options);
+        agent.sessionConfig.set(sessionId, normalized);
+        this.catalog = normalized;
+    }
+    ensureProcess() {
+        if (this.process)
+            return Promise.resolve(this.process);
+        this.starting ??= this.startProcess().finally(() => {
+            this.starting = null;
+        });
+        return this.starting;
+    }
+    async startProcess() {
+        const command = this.gateway.command;
+        if (!command)
+            throw new Error(`Gateway ${this.gateway.name} has no ACP command`);
+        const child = spawn(command, this.gateway.args ?? [], {
+            cwd: this.gateway.cwd ?? os.homedir(),
+            env: { ...process.env, ...(this.gateway.env ?? {}) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        child.stderr.on('data', (chunk) => this.log('agent stderr', { text: chunk.toString('utf8').slice(0, 2000) }));
+        const exited = new Promise((_, reject) => {
+            child.once('error', reject);
+            child.once('exit', (code, signal) => reject(new Error(`agent exited (code ${code}, signal ${signal})`)));
+        });
+        child.once('exit', () => {
+            if (this.process?.child === child)
+                this.process = null;
+        });
+        const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        const connection = new ClientSideConnection(() => ({
+            sessionUpdate: (params) => this.handleSessionUpdate(params),
+            requestPermission: (params) => this.handlePermission(params),
+        }), stream);
+        const init = await Promise.race([
+            connection.initialize({
+                protocolVersion: PROTOCOL_VERSION,
+                clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+                clientInfo: { name: 'dinox-gateway', version: getPackageVersion() },
+            }),
+            exited,
+        ]);
+        exited.catch(() => undefined);
+        const agent = { child, connection, init, liveSessions: new Set(), sessionConfig: new Map() };
+        this.process = agent;
+        this.log('agent connected', { agent: init.agentInfo?.name ?? command, protocol: init.protocolVersion });
+        return agent;
+    }
+    handleSessionUpdate(params) {
+        const update = params.update;
+        if (update.sessionUpdate === 'config_option_update' && this.process) {
+            this.rememberConfig(this.process, params.sessionId, update.configOptions);
+            return;
+        }
+        const turn = this.turns.get(params.sessionId);
+        if (!turn)
+            return;
+        switch (update.sessionUpdate) {
+            case 'agent_message_chunk':
+                if (update.content.type === 'text')
+                    turn.onEvent({ type: 'text-delta', text: update.content.text });
+                break;
+            case 'agent_thought_chunk':
+                if (update.content.type === 'text')
+                    turn.onEvent({ type: 'reasoning-delta', text: update.content.text });
+                break;
+            case 'tool_call':
+            case 'tool_call_update':
+                turn.onEvent({
+                    type: 'tool',
+                    toolCallId: update.toolCallId,
+                    ...(update.title ? { title: update.title } : {}),
+                    ...(update.status ? { status: TOOL_STATUS[update.status] } : {}),
+                    ...(update.rawInput !== undefined ? { input: update.rawInput } : {}),
+                    ...(update.rawOutput !== undefined || update.content
+                        ? { output: update.rawOutput ?? toolContentText(update.content) }
+                        : {}),
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    async handlePermission(params) {
+        const turn = this.turns.get(params.sessionId);
+        if (!turn)
+            return { outcome: { outcome: 'cancelled' } };
+        const approvalId = `acp-${generateId()}`;
+        turn.onEvent({
+            type: 'approval-request',
+            approvalId,
+            toolCallId: params.toolCall.toolCallId,
+            toolName: params.toolCall.title || params.toolCall.name || 'tool',
+            input: params.toolCall.rawInput,
+        });
+        const approved = await turn.awaitApproval(approvalId);
+        turn.onEvent({ type: 'approval-resolved', approvalId, approved });
+        const option = pickOption(params.options, approved);
+        return option ? { outcome: { outcome: 'selected', optionId: option.optionId } } : { outcome: { outcome: 'cancelled' } };
+    }
+}

package/dist/gateway/adapters/echo.d.ts

@@ -0,0 +1,12 @@
+import type { GatewayAdapter, GatewayAdapterInfo, GatewayTurnInput, GatewayTurnResult } from '../types.js';
+/**
+ * Loopback agent for end-to-end checks of the gateway path (app ⇄ NATS ⇄ CLI ⇄
+ * PowerSync) without a real runtime. Echoes the prompt; a prompt containing
+ * `/approve` exercises the tool-approval round trip first.
+ */
+export declare class EchoGatewayAdapter implements GatewayAdapter {
+    readonly kind: "echo";
+    info(): GatewayAdapterInfo;
+    runTurn(input: GatewayTurnInput): Promise<GatewayTurnResult>;
+    dispose(): Promise<void>;
+}

package/dist/gateway/adapters/echo.js

@@ -0,0 +1,51 @@
+import { generateId } from '../../utils/id.js';
+const CHUNK_DELAY_MS = 40;
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}
+/**
+ * Loopback agent for end-to-end checks of the gateway path (app ⇄ NATS ⇄ CLI ⇄
+ * PowerSync) without a real runtime. Echoes the prompt; a prompt containing
+ * `/approve` exercises the tool-approval round trip first.
+ */
+export class EchoGatewayAdapter {
+    kind = 'echo';
+    info() {
+        return { kind: this.kind, agentName: 'echo', agentVersion: null };
+    }
+    async runTurn(input) {
+        const sessionId = input.sessionId ?? `echo-${generateId()}`;
+        try {
+            if (input.prompt.includes('/approve')) {
+                const toolCallId = `tool-${generateId()}`;
+                const approvalId = `approval-${generateId()}`;
+                input.onEvent({ type: 'tool', toolCallId, title: 'echo.write', status: 'pending', input: { text: input.prompt } });
+                input.onEvent({ type: 'approval-request', approvalId, toolCallId, toolName: 'echo.write', input: { text: input.prompt } });
+                const approved = await input.awaitApproval(approvalId);
+                input.onEvent({ type: 'approval-resolved', approvalId, approved });
+                input.onEvent(approved
+                    ? { type: 'tool', toolCallId, status: 'completed', output: 'approved' }
+                    : { type: 'tool', toolCallId, status: 'failed', output: 'denied by user' });
+            }
+            for (const word of `Echo: ${input.prompt}`.split(/(\s+)/)) {
+                await delay(CHUNK_DELAY_MS, input.signal);
+                input.onEvent({ type: 'text-delta', text: word });
+            }
+            return { sessionId, stopReason: 'end_turn' };
+        }
+        catch (error) {
+            if (input.signal.aborted)
+                return { sessionId, stopReason: 'cancelled' };
+            throw error;
+        }
+    }
+    async dispose() { }
+}

package/dist/gateway/adapters/index.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@agentclientprotocol/sdk';
+import type { GatewayAdapter, GatewayDefinition } from '../types.js';
+/**
+ * The Dinox knowledge tools as a stdio MCP server: this same CLI, run as
+ * `dino gateway mcp`, reading through the daemon. DINOX_* variables are passed
+ * on so the child finds the same config, data dir and daemon socket.
+ */
+export declare function dinoxMcpServerConfig(): McpServer | null;
+export declare function createGatewayAdapter(gateway: GatewayDefinition, log: (message: string, details?: Record<string, unknown>) => void): GatewayAdapter;

package/dist/gateway/adapters/index.js

@@ -0,0 +1,30 @@
+import { AcpGatewayAdapter } from './acp.js';
+import { EchoGatewayAdapter } from './echo.js';
+/**
+ * The Dinox knowledge tools as a stdio MCP server: this same CLI, run as
+ * `dino gateway mcp`, reading through the daemon. DINOX_* variables are passed
+ * on so the child finds the same config, data dir and daemon socket.
+ */
+export function dinoxMcpServerConfig() {
+    const entrypoint = process.argv[1];
+    if (!entrypoint)
+        return null;
+    return {
+        name: 'dinox',
+        command: process.execPath,
+        args: [...process.execArgv, entrypoint, 'gateway', 'mcp'],
+        env: Object.entries(process.env)
+            .filter((entry) => entry[0].startsWith('DINOX_') && typeof entry[1] === 'string')
+            .map(([name, value]) => ({ name, value })),
+    };
+}
+export function createGatewayAdapter(gateway, log) {
+    switch (gateway.kind) {
+        case 'acp': {
+            const dinoxTools = gateway.dinoxTools === false ? null : dinoxMcpServerConfig();
+            return new AcpGatewayAdapter(gateway, log, dinoxTools ? [dinoxTools] : []);
+        }
+        case 'echo':
+            return new EchoGatewayAdapter();
+    }
+}

package/dist/gateway/assistantProjection.d.ts

@@ -0,0 +1,32 @@
+import type { ChatUIMessage } from '../vendor/electron/shared/external-types.js';
+import type { RemoteToolApprovalPrompt } from '../vendor/electron/shared/remote-device-agent.js';
+import type { GatewayEvent } from './types.js';
+export declare class AssistantProjection {
+    private readonly base;
+    private readonly parts;
+    private readonly toolIndex;
+    private readonly approvals;
+    private revisionCounter;
+    constructor(base: ChatUIMessage);
+    get revision(): number;
+    apply(event: GatewayEvent): void;
+    /** Closes streaming parts; called once when the turn ends. */
+    finish(): void;
+    snapshot(): ChatUIMessage;
+    private appendText;
+    private ensureTool;
+    private findToolByApproval;
+    private applyTool;
+}
+/** 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 declare function toTranscriptMessage(message: ChatUIMessage): ChatUIMessage;
+export declare function projectPendingApprovals(message: ChatUIMessage | null | undefined, ids: {
+    runId: string;
+    threadId: string;
+}): RemoteToolApprovalPrompt[];

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>;