@dinoxx/dinox-cli 2.2.0 → 2.4.0

package/README.md

@@ -52,7 +52,7 @@ Dinox CLI 适合这几类场景：
 
 安装前请先确认：
 
-- 推荐使用 Node.js 24 LTS；支持 Node.js 20.18.1+、22、23、24、25（不支持 Node.js 21 或 26+）
+- 推荐使用 Node.js 24 LTS；支持 Node.js 22、23、24、25（不支持 Node.js 21 及以下或 26+）
 - 已安装 npm
 - 你的系统可以正常执行全局 npm 命令
 
@@ -937,13 +937,27 @@ daemon 通过用户数据目录下的私有 Unix domain socket 通信，Windows
 
 需要在当前进程打开 PowerSync SQLite 的命令（例如写命令、`sync`、在线 `auth status`、`--offline` 或 `--require-sync` 读取）会先取得跨进程生命周期锁。如果同一用户数据库正由健康 daemon 持有，CLI 会暂时停止该实例；只有在命令结束、数据库关闭且 owner lease 成功释放后，才会按原端口恢复它。使用其他用户数据库的 daemon 不会被停止；如果关闭或释放失败，CLI 会保留 daemon 为停止状态并在 stderr 报告警告，避免两个运行时同时持有同一 SQLite 数据库。
 
-### 6.15 `info`：查看版本与技能仓库地址
+### 6.15 `gateway`：把本机 Agent 挂成远程设备
+
+```bash
+dino gateway detect
+dino gateway detect --add
+dino gateway add Hermes --command hermes --arg acp
+dino gateway list
+dino gateway status
+dino gateway reload
+dino gateway remove Hermes
+```
+
+`detect` 会在 `PATH` 上查找 ACP agent，并用真实握手确认能否启动。`--add` 把已确认的 agent 写入当前账号的 gateway 配置，并由 daemon 托管。`gateway list` 只显示环境变量名，不显示值。`dino gateway mcp` 由这些 agent 拉起，对外提供只读的 Dinox 知识工具。
+
+### 6.16 `info`：查看版本与技能仓库地址
 
 ```bash
 dino info
 ```
 
-### 6.16 `update`：升级 CLI
+### 6.17 `update`：升级 CLI
 
 ```bash
 dino update

package/dist/cli.js

@@ -3,6 +3,7 @@ import { registerAuthCommands } from './commands/auth/index.js';
 import { registerBoxesCommand } from './commands/boxes/index.js';
 import { registerConfigCommands } from './commands/config/index.js';
 import { registerDaemonCommands } from './daemon/index.js';
+import { registerGatewayCommands } from './commands/gateway/index.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerGraphCommands } from './commands/graph/index.js';
 import { registerInfoCommand } from './commands/info/index.js';
@@ -10,12 +11,14 @@ import { registerMetaCommands } from './commands/meta/index.js';
 import { registerNoteCommands } from './commands/notes/index.js';
 import { registerPromptCommands } from './commands/prompt/index.js';
 import { registerSchemaCommands } from './commands/schema/index.js';
+import { registerPropertyCommands } from './commands/properties/index.js';
 import { registerSavedViewCommands } from './commands/savedViews/index.js';
 import { registerSkillsCommands } from './commands/skills/index.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerStorageCommands } from './commands/storage/index.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerTagsCommand } from './commands/tags/index.js';
+import { registerTemplateCommands } from './commands/templates/index.js';
 import { registerTodoCommands } from './commands/todo/index.js';
 import { getPackageVersion } from './utils/version.js';
 import { buildStructuredErrorPayload, DinoxError } from './utils/errors.js';
@@ -77,6 +80,7 @@ export function createCli() {
     registerBoxesCommand(program);
     registerConfigCommands(program);
     registerDaemonCommands(program);
+    registerGatewayCommands(program);
     registerDoctorCommand(program);
     registerGraphCommands(program);
     registerInfoCommand(program);
@@ -85,6 +89,8 @@ export function createCli() {
     registerUpdateCommand(program);
     registerPromptCommands(program);
     registerSavedViewCommands(program);
+    registerPropertyCommands(program);
+    registerTemplateCommands(program);
     registerSchemaCommands(program);
     registerSkillsCommands(program);
     registerStorageCommands(program);

package/dist/commands/domain/options.d.ts

@@ -0,0 +1,10 @@
+export declare function parseIntegerOption(value: string): number;
+export declare function parsePositiveIntegerOption(value: string): number;
+export declare function parseNonNegativeIntegerOption(value: string): number;
+/** Commander collector for repeatable options. */
+export declare function collectOption(value: string, previous: unknown): string[];
+export declare function parseTimeZoneOption(value: string): string;
+/** Reads an inline JSON value or `@file` and parses it. */
+export declare function readJsonOption(value: unknown, label: string, schemaPath: string): Promise<unknown>;
+export declare function requiredArgument(value: string | undefined, label: string): string;
+export declare function assertExclusive(conflicts: Array<[boolean, string]>): void;

package/dist/commands/domain/options.js

@@ -0,0 +1,75 @@
+// Option parsers shared by the commands backed by the vendored desktop domain
+// (view, prop, template).
+import { readStringOrFile } from '../../utils/argValue.js';
+import { DinoxError } from '../../utils/errors.js';
+export function parseIntegerOption(value) {
+    const normalized = value.trim();
+    if (!/^-?\d+$/.test(normalized)) {
+        throw new DinoxError('Expected an integer', { code: 'USAGE_ERROR' });
+    }
+    const parsed = Number(normalized);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new DinoxError('Expected a safe integer', { code: 'USAGE_ERROR' });
+    }
+    return parsed;
+}
+export function parsePositiveIntegerOption(value) {
+    const parsed = parseIntegerOption(value);
+    if (parsed <= 0)
+        throw new DinoxError('Expected a positive integer', { code: 'USAGE_ERROR' });
+    return parsed;
+}
+export function parseNonNegativeIntegerOption(value) {
+    const parsed = parseIntegerOption(value);
+    if (parsed < 0)
+        throw new DinoxError('Expected a non-negative integer', { code: 'USAGE_ERROR' });
+    return parsed;
+}
+/** Commander collector for repeatable options. */
+export function collectOption(value, previous) {
+    return [...(Array.isArray(previous) ? previous : []), value];
+}
+export function parseTimeZoneOption(value) {
+    const normalized = value.trim();
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: normalized });
+    }
+    catch {
+        throw new DinoxError(`Invalid IANA time zone: ${value}`, { code: 'SAVED_VIEW_INVALID_TIME_ZONE' });
+    }
+    return normalized;
+}
+/** Reads an inline JSON value or `@file` and parses it. */
+export async function readJsonOption(value, label, schemaPath) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new DinoxError(`${label} requires inline JSON or @file`, { code: 'USAGE_ERROR' });
+    }
+    let raw;
+    try {
+        raw = await readStringOrFile(value);
+    }
+    catch (error) {
+        throw new DinoxError(`Failed to read ${label}`, { code: 'USAGE_ERROR', cause: error });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new DinoxError(`${label} must be valid JSON`, {
+            code: 'USAGE_ERROR',
+            cause: error,
+            suggestion: `Pass inline JSON or use @file. See \`dino schema ${schemaPath} --format json\`.`,
+        });
+    }
+}
+export function requiredArgument(value, label) {
+    const normalized = value?.trim();
+    if (!normalized)
+        throw new DinoxError(`${label} is required`, { code: 'USAGE_ERROR' });
+    return normalized;
+}
+export function assertExclusive(conflicts) {
+    const conflict = conflicts.find(([active]) => active);
+    if (conflict)
+        throw new DinoxError(conflict[1], { code: 'USAGE_ERROR' });
+}

package/dist/commands/domain/run.d.ts

@@ -0,0 +1,24 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import { type z } from 'zod';
+import { DinoxError } from '../../utils/errors.js';
+export type DomainCommandResult<T> = {
+    result: T;
+    affectedTables: string[];
+};
+/** Converts a desktop domain failure into a DinoxError; DinoxErrors pass through unchanged. */
+export declare function toDinoxError(error: unknown, label?: string): DinoxError;
+export declare function parseDomainInput<T>(definition: {
+    inputSchema: z.ZodType<T>;
+}, input: unknown, label: string): T;
+export declare function runDomainCommand<T>(db: AbstractPowerSyncDatabase, name: string, input: unknown): Promise<DomainCommandResult<T>>;
+export declare function fetchDomainReadModel<T>(db: AbstractPowerSyncDatabase, name: string, input: unknown): Promise<T[]>;
+/** Runs `run` in one read transaction (a consistent snapshot) when the database offers it. */
+export declare function withReadTransaction<T>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<T>): Promise<T>;
+/** Runs `run` in one write transaction; vendored commands called inside reuse it. */
+export declare function withNestedWriteTransaction<T>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<T>): Promise<T>;
+/**
+ * Executes `run` and then `inspect` inside one write transaction that is always rolled
+ * back, so a preview reflects exactly what the real write would do (including desktop
+ * validation and derived values) without persisting or queueing an upload.
+ */
+export declare function previewInRolledBackTransaction<TResult, TPreview>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<TResult>, inspect: (tx: AbstractPowerSyncDatabase, result: TResult) => Promise<TPreview>): Promise<TPreview>;

package/dist/commands/domain/run.js

@@ -0,0 +1,137 @@
+// Runs the vendored desktop domain (src/vendor/electron) against the CLI's PowerSync
+// database: validates inputs with the desktop zod schemas, maps desktop error strings onto
+// registered DinoxError codes, and previews writes by executing them inside a transaction
+// that is always rolled back.
+import { ZodError } from 'zod';
+import { withPowerSyncWriteTransaction } from '../../powersync/runtime.js';
+import { DinoxError } from '../../utils/errors.js';
+import { isRegisteredErrorCode } from '../../utils/errorCodes.js';
+import { createNoteTemplateCommands, createNoteTemplateReadModels } from '../../vendor/electron/domain/note-templates.js';
+import { createPropertyCommands, createPropertyReadModels } from '../../vendor/electron/domain/properties.js';
+import { createSavedViewCommands, createSavedViewReadModels } from '../../vendor/electron/domain/saved-views.js';
+const COMMANDS = new Map([...createPropertyCommands(), ...createSavedViewCommands(), ...createNoteTemplateCommands()]
+    .map((definition) => [definition.name, definition]));
+const READ_MODELS = new Map([...createPropertyReadModels(), ...createSavedViewReadModels(), ...createNoteTemplateReadModels()]
+    .map((definition) => [definition.name, definition]));
+const DOMAIN_CODE_PATTERN = /^[A-Z][A-Z0-9_]+$/;
+function zodIssues(error) {
+    return error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message }));
+}
+/** Converts a desktop domain failure into a DinoxError; DinoxErrors pass through unchanged. */
+export function toDinoxError(error, label = 'Dinox domain operation') {
+    if (error instanceof DinoxError)
+        return error;
+    if (error instanceof ZodError) {
+        return new DinoxError(`${label} input is invalid`, {
+            code: 'INVALID_ARGUMENT',
+            details: { issues: zodIssues(error) },
+            recoverable: false,
+        });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (DOMAIN_CODE_PATTERN.test(message) && isRegisteredErrorCode(message)) {
+        return new DinoxError(message, { code: message, cause: error, recoverable: false });
+    }
+    if (/^Note not found: /.test(message)) {
+        return new DinoxError(message, { code: 'NOTE_NOT_FOUND', cause: error });
+    }
+    if (/^Invalid note template .* input$/.test(message)) {
+        return new DinoxError(message, { code: 'INVALID_ARGUMENT', cause: error, recoverable: false });
+    }
+    return new DinoxError(message || `${label} failed`, { code: 'COMMAND_FAILED', cause: error });
+}
+function requireCommand(name) {
+    const definition = COMMANDS.get(name);
+    if (!definition)
+        throw new DinoxError(`Unknown domain command: ${name}`, { code: 'INTERNAL_ERROR' });
+    return definition;
+}
+function requireReadModel(name) {
+    const definition = READ_MODELS.get(name);
+    if (!definition)
+        throw new DinoxError(`Unknown domain read model: ${name}`, { code: 'INTERNAL_ERROR' });
+    return definition;
+}
+export function parseDomainInput(definition, input, label) {
+    const parsed = definition.inputSchema.safeParse(input);
+    if (!parsed.success)
+        throw toDinoxError(parsed.error, label);
+    return parsed.data;
+}
+export async function runDomainCommand(db, name, input) {
+    const definition = requireCommand(name);
+    const parsed = parseDomainInput(definition, input, name);
+    try {
+        return await definition.run(db, parsed);
+    }
+    catch (error) {
+        throw toDinoxError(error, name);
+    }
+}
+export async function fetchDomainReadModel(db, name, input) {
+    const definition = requireReadModel(name);
+    const parsed = parseDomainInput(definition, input, name);
+    try {
+        return await definition.fetch(db, parsed);
+    }
+    catch (error) {
+        throw toDinoxError(error, name);
+    }
+}
+/**
+ * Exposes an open transaction as a database whose nested write/read transactions reuse it,
+ * so vendored commands that open their own transaction run inside the caller's.
+ */
+function nestedDatabase(tx) {
+    const proxy = new Proxy(tx, {
+        get(target, property, receiver) {
+            if (property === 'writeTransaction' || property === 'readTransaction') {
+                return async (run) => run(proxy);
+            }
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+    return proxy;
+}
+/** Runs `run` in one read transaction (a consistent snapshot) when the database offers it. */
+export async function withReadTransaction(db, run) {
+    const candidate = db;
+    if (typeof candidate.readTransaction !== 'function')
+        return run(db);
+    return candidate.readTransaction.call(db, (tx) => run(nestedDatabase(tx)));
+}
+/** Runs `run` in one write transaction; vendored commands called inside reuse it. */
+export async function withNestedWriteTransaction(db, run) {
+    try {
+        return await withPowerSyncWriteTransaction(db, (tx) => run(nestedDatabase(tx)));
+    }
+    catch (error) {
+        throw toDinoxError(error);
+    }
+}
+class DryRunRollback extends Error {
+}
+/**
+ * Executes `run` and then `inspect` inside one write transaction that is always rolled
+ * back, so a preview reflects exactly what the real write would do (including desktop
+ * validation and derived values) without persisting or queueing an upload.
+ */
+export async function previewInRolledBackTransaction(db, run, inspect) {
+    let preview = null;
+    try {
+        await withPowerSyncWriteTransaction(db, async (tx) => {
+            const nested = nestedDatabase(tx);
+            const result = await run(nested);
+            preview = { value: await inspect(nested, result) };
+            throw new DryRunRollback('dry-run rollback');
+        });
+    }
+    catch (error) {
+        if (!(error instanceof DryRunRollback))
+            throw toDinoxError(error);
+    }
+    if (!preview)
+        throw new DinoxError('Dry-run preview did not complete', { code: 'INTERNAL_ERROR' });
+    return preview.value;
+}

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

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+import type { CommandGroupDescriptor } from '../descriptor/types.js';
+export declare const gatewayCommandGroup: CommandGroupDescriptor;
+export declare function registerGatewayCommands(program: Command): void;

package/dist/commands/gateway/index.js

@@ -0,0 +1,300 @@
+import { isDaemonRunning, sendDaemonRequest } from '../../daemon/client.js';
+import { ensureDaemonRunning } from '../../daemon/ensure.js';
+import { loadConfig } from '../../config/store.js';
+import { addGateway, adoptDetectedAgent, getGatewaysFilePath, loadGateways, removeGateway, } from '../../gateway/config.js';
+import { detectAcpAgents, inferAgentId } from '../../gateway/detect.js';
+import { serveDinoxMcpOverStdio } from '../../gateway/mcpServer.js';
+import { DinoxError } from '../../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess } from '../../utils/output.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS } from '../schema/globalOptions.js';
+const GATEWAY_KINDS = ['acp', 'echo'];
+function collect(value, previous) {
+    return [...(Array.isArray(previous) ? previous : []), value];
+}
+function parseEnv(entries) {
+    const env = {};
+    for (const entry of Array.isArray(entries) ? entries : []) {
+        const separator = entry.indexOf('=');
+        if (separator <= 0) {
+            throw new DinoxError(`--env expects KEY=VALUE, got "${entry}"`, { code: 'INVALID_ARGUMENT' });
+        }
+        env[entry.slice(0, separator)] = entry.slice(separator + 1);
+    }
+    return env;
+}
+/** Gateways belong to the logged-in account. */
+async function currentUserId() {
+    return (await loadConfig()).auth?.userId ?? '';
+}
+/** Public view: never echoes env values (they may hold API keys). */
+function describeGateway(gateway) {
+    return {
+        id: gateway.id,
+        name: gateway.name,
+        kind: gateway.kind,
+        agentId: gateway.agentId ?? null,
+        deviceId: gateway.deviceId,
+        command: gateway.command ?? null,
+        args: gateway.args ?? [],
+        cwd: gateway.cwd ?? null,
+        envKeys: Object.keys(gateway.env ?? {}),
+        enabled: gateway.enabled,
+    };
+}
+/** Applies the account's gateways to the running daemon, starting it when needed. */
+async function applyToDaemon() {
+    if (!(await isDaemonRunning())) {
+        await ensureDaemonRunning();
+        return (await sendDaemonRequest('gateway.status')).gateways;
+    }
+    return (await sendDaemonRequest('gateway.reload', undefined, { timeoutMs: 30_000 })).gateways;
+}
+function printStatuses(statuses) {
+    if (statuses.length === 0) {
+        printHumanReadableLine('No gateways are running.');
+        return;
+    }
+    for (const status of statuses) {
+        const busy = status.busyThreadIds.length ? ` · ${status.busyThreadIds.length} running` : '';
+        const error = status.lastError ? ` · ${status.lastError}` : '';
+        printHumanReadableLine(`${status.name} (${status.kind}, ${status.deviceId}): ${status.state}${busy}${error}`);
+    }
+}
+async function runAdd(context) {
+    const kind = context.options.kind ?? 'acp';
+    if (!GATEWAY_KINDS.includes(kind)) {
+        throw new DinoxError(`--kind must be one of ${GATEWAY_KINDS.join(', ')}`, { code: 'INVALID_ARGUMENT' });
+    }
+    const command = context.options.command;
+    const args = context.options.arg;
+    const gateway = await addGateway(await currentUserId(), {
+        name: context.args.name ?? '',
+        kind,
+        // A manual launch of a known agent counts as that agent, so detect never hosts it twice.
+        agentId: kind === 'acp' ? inferAgentId(command, args) : undefined,
+        command,
+        args,
+        cwd: context.options.cwd,
+        env: parseEnv(context.options.env),
+    });
+    const statuses = await applyToDaemon();
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ gateway: describeGateway(gateway), status: statuses.find((item) => item.gatewayId === gateway.id) ?? null });
+        return;
+    }
+    printHumanReadableLine(`Added gateway "${gateway.name}" as device ${gateway.deviceId}.`);
+    printStatuses(statuses);
+}
+async function runDetect(context) {
+    const detected = await detectAcpAgents({ probe: true });
+    const added = [];
+    const updated = [];
+    if (context.options.add) {
+        const userId = await currentUserId();
+        for (const agent of detected) {
+            if (!agent.verified)
+                continue;
+            const result = await adoptDetectedAgent(userId, agent);
+            if (result.change === 'added')
+                added.push(result.gateway);
+            if (result.change === 'updated')
+                updated.push(result.gateway);
+        }
+    }
+    const statuses = added.length || updated.length ? await applyToDaemon() : [];
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({
+            agents: detected,
+            added: added.map(describeGateway),
+            updated: updated.map(describeGateway),
+            gateways: statuses,
+        });
+        return;
+    }
+    if (detected.length === 0) {
+        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) {
+        printHumanReadableLine(`Updated gateway "${gateway.name}": ${[gateway.command, ...(gateway.args ?? [])].join(' ')}`);
+    }
+    if (!context.options.add && detected.some((agent) => agent.verified)) {
+        printHumanReadableLine('Run `dino gateway detect --add` to host the ready agents.');
+    }
+}
+async function runList() {
+    const userId = await currentUserId();
+    const gateways = (await loadGateways(userId)).map(describeGateway);
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ gateways, file: getGatewaysFilePath(userId) });
+        return;
+    }
+    if (gateways.length === 0) {
+        printHumanReadableLine('No gateways configured. Add one with `dino gateway add <name> --command <agent>`.');
+        return;
+    }
+    for (const gateway of gateways) {
+        const command = gateway.command ? ` · ${[gateway.command, ...gateway.args].join(' ')}` : '';
+        printHumanReadableLine(`${gateway.name} (${gateway.kind}, ${gateway.deviceId})${command}`);
+    }
+}
+async function runRemove(context) {
+    const gateway = await removeGateway(await currentUserId(), context.args.gateway ?? '');
+    const statuses = (await isDaemonRunning()) ? await applyToDaemon() : [];
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ removed: describeGateway(gateway), gateways: statuses });
+        return;
+    }
+    printHumanReadableLine(`Removed gateway "${gateway.name}".`);
+}
+async function runStatus() {
+    await ensureDaemonRunning();
+    const { gateways } = (await sendDaemonRequest('gateway.status'));
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ gateways });
+        return;
+    }
+    printStatuses(gateways);
+}
+async function runReload() {
+    const gateways = await applyToDaemon();
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ gateways });
+        return;
+    }
+    printStatuses(gateways);
+}
+const STATUS_FIELDS = ['gatewayId', 'name', 'deviceId', 'kind', 'state', 'connectedAt', 'lastError', 'busyThreadIds', 'agentName'];
+export const gatewayCommandGroup = {
+    name: 'gateway',
+    description: 'Host external agents (Hermes, OpenClaw, pi, Claude Code, ...) as Dinox remote devices',
+    commands: [
+        {
+            name: 'add',
+            description: 'Add an agent gateway and start hosting it in the daemon',
+            arguments: [{ syntax: '<name>', description: 'Display name shown in the Dinox app' }],
+            options: [
+                { flags: '--kind <kind>', description: 'Agent runtime protocol', type: 'string', enum: GATEWAY_KINDS, defaultValue: 'acp' },
+                { flags: '--command <command>', description: 'ACP agent executable (e.g. hermes, openclaw, claude-code-acp)', type: 'string' },
+                { flags: '--arg <value>', description: 'Argument passed to the agent (repeatable, e.g. --arg acp)', type: 'string[]', parser: collect },
+                { flags: '--cwd <dir>', description: 'Working directory for the agent sessions', type: 'string' },
+                { flags: '--env <KEY=VALUE>', description: 'Environment for the agent process, stored locally (repeatable)', type: 'string[]', parser: collect },
+            ],
+            schema: {
+                path: 'gateway.add',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'The added gateway and its live device status',
+                    fields: ['gateway', 'status'],
+                },
+                examples: [
+                    'dino gateway add Hermes --command hermes --arg acp --format json',
+                    'dino gateway add Echo --kind echo --format json',
+                ],
+            },
+            action: runAdd,
+        },
+        {
+            name: 'detect',
+            description: 'Find ACP agents installed on this machine (verified with a real handshake)',
+            options: [{ flags: '--add', description: 'Add every verified agent that is not configured yet', type: 'boolean' }],
+            schema: {
+                path: 'gateway.detect',
+                risk: 'write',
+                auth: 'none',
+                globalOptions: FORMAT_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Detected agents, gateways added, and their live statuses',
+                    fields: ['agents', 'added', 'gateways'],
+                },
+                examples: ['dino gateway detect --format json', 'dino gateway detect --add --format json'],
+            },
+            action: runDetect,
+        },
+        {
+            name: 'list',
+            description: 'List configured agent gateways (environment values are never shown)',
+            schema: {
+                path: 'gateway.list',
+                risk: 'read',
+                auth: 'none',
+                globalOptions: FORMAT_OPTIONS,
+                output: { type: 'structured', summary: 'Configured gateways', fields: ['gateways', 'file'] },
+                examples: ['dino gateway list --format json'],
+            },
+            action: runList,
+        },
+        {
+            name: 'remove',
+            description: 'Remove an agent gateway and stop hosting it',
+            arguments: [{ syntax: '<gateway>', description: 'Gateway name, id, or device id' }],
+            schema: {
+                path: 'gateway.remove',
+                risk: 'write',
+                auth: 'none',
+                globalOptions: FORMAT_OPTIONS,
+                output: { type: 'structured', summary: 'The removed gateway and remaining statuses', fields: ['removed', 'gateways'] },
+                examples: ['dino gateway remove Hermes --format json'],
+            },
+            action: runRemove,
+        },
+        {
+            name: 'status',
+            description: 'Show live connection status of each hosted gateway',
+            schema: {
+                path: 'gateway.status',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: FORMAT_OPTIONS,
+                output: { type: 'structured', summary: 'Live gateway device statuses', fields: STATUS_FIELDS },
+                examples: ['dino gateway status --format json'],
+            },
+            action: runStatus,
+        },
+        {
+            name: 'mcp',
+            description: 'Serve read-only Dinox knowledge tools over stdio MCP (started by gateway agents)',
+            schema: {
+                path: 'gateway.mcp',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: [],
+                output: { type: 'structured', summary: 'MCP JSON-RPC over stdio until stdin closes', fields: [] },
+                examples: ['dino gateway mcp'],
+            },
+            action: serveDinoxMcpOverStdio,
+        },
+        {
+            name: 'reload',
+            description: 'Re-read gateway configuration in the running daemon',
+            schema: {
+                path: 'gateway.reload',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: FORMAT_OPTIONS,
+                output: { type: 'structured', summary: 'Live gateway device statuses after reload', fields: STATUS_FIELDS },
+                examples: ['dino gateway reload --format json'],
+            },
+            action: runReload,
+        },
+    ],
+};
+export function registerGatewayCommands(program) {
+    registerCommandGroup(program, gatewayCommandGroup);
+}