@agentdeck/bridge 1.0.4 → 1.0.5

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { writeFileSync, unlinkSync, existsSync, realpathSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
@@ -8,13 +8,42 @@ import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { request } from 'http';
 import { BRIDGE_WS_PORT } from './types.js';
+import { SESSION_WEIGHT_MIN, SESSION_WEIGHT_MAX } from '@agentdeck/shared';
 import { ensureBleRuntime, getBleRuntimeStatus } from './python-ble-runtime.js';
 import { TASK_NAME, installWindowsTask, taskExists, runWindowsTask, endWindowsTask, deleteWindowsTask, } from './windows-service.js';
+import { deriveRemoteAttachOpts } from './session-registry.js';
+import { SERVICE_NAME, hasSystemctl, unitExists, installUnit, startUnit, disableUnit, getUnitPath, getDataDir, } from './linux-service.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
+/**
+ * Pre-PTY warning for a host hint given without the opt-in switch. Must run in
+ * the CLI action handler BEFORE the bridge starts: once the PTY takes the
+ * terminal, `log()` output is swallowed and the user would never see it.
+ */
+function warnIfDaemonHostIgnored(opts) {
+    if (deriveRemoteAttachOpts(opts).ignoredHostHint) {
+        console.error('[agentdeck] --daemon-host / AGENTDECK_DAEMON_HOST is set but ignored: remote attach requires --remote-daemon (or AGENTDECK_REMOTE_DAEMON=1). Session stays local-only.');
+    }
+}
 function log(msg) {
     process.stderr.write(msg + '\n');
 }
+/**
+ * Parse a `--weight <n>` value into an integer sort override. Rejects
+ * non-integers so a typo (`--weight foo`) fails loudly instead of silently
+ * collapsing to 0, and rejects values outside the documented cross-platform
+ * range (shared SESSION_WEIGHT_MIN/MAX) — the wire value must fit every
+ * consumer's integer type (Kotlin `Int` in particular), and comparators on
+ * fixed-width platforms must never see values that could overflow. Lower
+ * sorts first (see shared sortSessions).
+ */
+function parseWeight(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < SESSION_WEIGHT_MIN || n > SESSION_WEIGHT_MAX) {
+        throw new InvalidArgumentError(`weight must be an integer between ${SESSION_WEIGHT_MIN} and ${SESSION_WEIGHT_MAX} (e.g. --weight 1, --weight -5)`);
+    }
+    return n;
+}
 function formatBytes(value) {
     const bytes = typeof value === 'number' && Number.isFinite(value) ? value : 0;
     if (bytes >= 1024 * 1024)
@@ -141,7 +170,7 @@ function projectRootPath() {
 }
 async function runBlePython(python, args, captureStdout = false) {
     return new Promise((resolve, reject) => {
-        const child = spawn(python, args, captureStdout ? { stdio: ['ignore', 'pipe', 'inherit'] } : { stdio: 'inherit' });
+        const child = spawn(python, args, captureStdout ? { stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true } : { stdio: 'inherit', windowsHide: true });
         let stdout = '';
         child.stdout?.on('data', (data) => {
             stdout += data.toString();
@@ -204,6 +233,117 @@ function platformioBin() {
         return '/opt/homebrew/bin/pio';
     return 'pio';
 }
+// ===== Env-var default CLI args =====
+//
+// Two layers of environment-variable defaults, so a shell profile can set
+// repeated flags once:
+//   AGENTDECK_COMMANDER_ARGS   → args for the `agentdeck` (commander) layer,
+//                                spliced into argv after the session subcommand.
+//   AGENTDECK_<AGENT>_ARGS     → args appended to the spawned agent command,
+//                                weaving into an explicit `-c` when present.
+// See docs and cli.test.ts for behavior.
+/** Session subcommands the global env-args var applies to. */
+const SESSION_COMMANDS = ['claude', 'codex', 'opencode', 'monitor'];
+/** Env var holding extra args for the spawned agent command, per agent type. */
+const AGENT_ARGS_ENV = {
+    'claude-code': 'AGENTDECK_CLAUDE_ARGS',
+    'codex-cli': 'AGENTDECK_CODEX_ARGS',
+    opencode: 'AGENTDECK_OPENCODE_ARGS',
+};
+/**
+ * Split an env-provided arg string into tokens, honoring single/double quotes
+ * so values like `--flag "a b"` survive. No shell expansion (no $VAR,
+ * globbing, or escapes beyond quote grouping) — this only groups whitespace.
+ * Cross-platform: pure JS, never invokes a shell.
+ */
+export function tokenizeArgString(s) {
+    if (!s)
+        return [];
+    const tokens = [];
+    // Match: double-quoted run | single-quoted run | bare non-space run.
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let cur = '';
+    let curActive = false;
+    let lastIndex = 0;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+        // A gap of whitespace between matches ends the current token.
+        if (curActive && m.index > lastIndex) {
+            tokens.push(cur);
+            cur = '';
+            curActive = false;
+        }
+        cur += m[1] ?? m[2] ?? m[3] ?? '';
+        curActive = true;
+        lastIndex = re.lastIndex;
+    }
+    if (curActive)
+        tokens.push(cur);
+    return tokens;
+}
+/** Per-invocation escape hatch: disables BOTH env-default layers when typed. */
+const NO_ENV_ARGS_FLAG = '--no-env-args';
+/**
+ * If argv's subcommand is a session command and AGENTDECK_COMMANDER_ARGS is set,
+ * splice its tokens in immediately after the subcommand name. Env tokens land
+ * before any user-typed tokens, giving last-write override for SCALAR options
+ * (retype `--weight`/`--daemon-host` to win); boolean flags have no inverse
+ * spelling, so the per-invocation override is the typed `--no-env-args` hatch,
+ * which skips the splice entirely (and, parsed by commander, turns the
+ * per-agent append off in the session actions too).
+ * Returns a new argv; no-op (returns input) when unset or not a session command.
+ */
+export function applyGlobalEnvArgs(argv, env = process.env) {
+    // The hatch itself is stripped from the env tokens: an env-smuggled
+    // --no-env-args would otherwise splice normally and then parse to
+    // envArgs=false, silently disabling only the per-agent layer — an
+    // undocumented half-state. The env var cannot turn the hatch on or off;
+    // only a typed flag can.
+    const extra = tokenizeArgString(env.AGENTDECK_COMMANDER_ARGS)
+        .filter((tok) => tok !== NO_ENV_ARGS_FLAG);
+    if (extra.length === 0)
+        return argv;
+    // The CLI has a fixed top-level command position: argv[0]=node,
+    // argv[1]=script, argv[2]=subcommand. Keying the decision to argv[2] (not a
+    // token scan) keeps non-session commands a true no-op even when a
+    // positional VALUE equals a session command name (`agentdeck speak b claude`).
+    const sub = argv[2];
+    if (sub === undefined || !SESSION_COMMANDS.includes(sub))
+        return argv;
+    // Typed escape hatch — checked on the RAW argv before splicing, because
+    // post-parse is too late (env tokens would already have parsed into opts).
+    // Exact-token match: a flag VALUE lexically equal to --no-env-args would
+    // false-positive, but producing that requires a deliberately pathological
+    // invocation (`-c --no-env-args`), and the argv[2] gate above bounds the
+    // scan to session commands.
+    if (argv.slice(3).includes(NO_ENV_ARGS_FLAG))
+        return argv;
+    const next = argv.slice();
+    next.splice(3, 0, ...extra);
+    return next;
+}
+/**
+ * Append the per-agent env var to the resolved `-c` command string. Raw append
+ * (single space + trim) — the PTY shell re-parses the whole string at spawn, so
+ * this rides the same platform shell path (cmd.exe / POSIX) that already handles
+ * a user's `-c`. No-op (returns `command`) when the var is unset/empty.
+ */
+export function weaveAgentCommand(agentType, command, env = process.env) {
+    const extra = (env[AGENT_ARGS_ENV[agentType]] ?? '').trim();
+    if (!extra)
+        return command;
+    return `${command} ${extra}`.trim();
+}
+/**
+ * The session actions' one-call selection for the spawned agent command:
+ * weave the per-agent env args unless the user typed `--no-env-args`
+ * (commander parses it as `opts.envArgs === false`; the hatch covers BOTH
+ * env layers, and the commander-layer half is handled pre-parse in
+ * `applyGlobalEnvArgs`).
+ */
+export function resolveAgentCommand(agentType, command, envArgsEnabled, env = process.env) {
+    return envArgsEnabled ? weaveAgentCommand(agentType, command, env) : command;
+}
 // ===== Program =====
 const program = new Command();
 program
@@ -223,16 +363,24 @@ program
     .option('--no-adb', 'Disable ADB reverse setup')
     .option('--no-postit', 'Disable terminal tab title updates')
     .option('--wake-word', 'Enable wake word voice assistant ("오픈클로")')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     await startSession({
         agentType: 'claude-code',
         port: parseInt(opts.port, 10),
-        command: opts.command,
+        command: resolveAgentCommand('claude-code', opts.command, opts.envArgs !== false),
         debug: opts.debug,
         noUpdateCheck: opts.updateCheck === false,
         postit: opts.postit !== false,
         wakeWord: !!opts.wakeWord,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false, // daemon-only — session bridges never advertise mDNS
             adb: opts.adb !== false ? 'auto' : false,
@@ -252,7 +400,12 @@ program
     .option('--no-adb', 'Disable ADB reverse setup')
     .option('--no-postit', 'Disable terminal tab title updates')
     .option('--no-codex-hooks', 'Skip ~/.codex/config.toml hook install')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     // Install Codex lifecycle hooks before starting the session so the
     // first prompt's UserPromptSubmit / Stop events reach the daemon.
     // Idempotent: re-running with the same daemon port is a no-op.
@@ -281,9 +434,12 @@ program
     await startSession({
         agentType: 'codex-cli',
         port: parseInt(opts.port, 10),
-        command: opts.command,
+        command: resolveAgentCommand('codex-cli', opts.command, opts.envArgs !== false),
         debug: opts.debug,
         postit: opts.postit !== false,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false, // daemon-only
             adb: opts.adb !== false ? 'auto' : false,
@@ -303,7 +459,12 @@ program
     .option('--no-adb', 'Disable ADB reverse setup')
     .option('--no-postit', 'Disable terminal tab title updates')
     .option('--no-opencode-hooks', 'Skip OpenCode observer plugin install')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS and AGENTDECK_<AGENT>_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     // Install the OpenCode observer plugin so standalone `opencode` runs
     // (outside this managed session) also reach the daemon timeline. The
     // plugin self-disables inside managed PTYs via AGENTDECK_PORT, so this
@@ -331,9 +492,12 @@ program
     await startSession({
         agentType: 'opencode',
         port: parseInt(opts.port, 10),
-        command: opts.command,
+        command: resolveAgentCommand('opencode', opts.command, opts.envArgs !== false),
         debug: opts.debug,
         postit: opts.postit !== false,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : {
             mdns: false,
             adb: opts.adb !== false ? 'auto' : false,
@@ -349,7 +513,13 @@ program
     .option('-p, --port <port>', 'Bridge server port', String(BRIDGE_WS_PORT))
     .option('-d, --debug', 'Enable debug logging')
     .option('--local', 'Disable all device modules')
+    .option('--remote-daemon', 'Opt in to attaching this session to a daemon on another machine (gates --daemon-host and mDNS discovery)')
+    .option('--daemon-host <host>', 'Explicit remote daemon endpoint (host or host:port); requires --remote-daemon')
+    // Commander-layer half only: monitor spawns no agent command to weave into.
+    .option('--no-env-args', 'Ignore AGENTDECK_COMMANDER_ARGS for this invocation')
+    .option('--weight <n>', 'Deck/tab sort order override (integer, lower first; default 0)', parseWeight)
     .action(async (opts) => {
+    warnIfDaemonHostIgnored(opts);
     const { startSession } = await import('./index.js');
     const port = parseInt(opts.port, 10);
     log(`\nMonitor mode: hook server on port ${port}`);
@@ -358,6 +528,9 @@ program
         agentType: 'monitor',
         port,
         debug: opts.debug,
+        remoteDaemon: !!opts.remoteDaemon,
+        daemonHost: opts.daemonHost,
+        weight: opts.weight,
         modules: opts.local ? { mdns: false, adb: false, serial: false, pixoo: false, timebox: false } : undefined,
     });
 });
@@ -465,6 +638,7 @@ daemon
         const child = spawn(process.execPath, args, {
             detached: true,
             stdio: ['ignore', out, err],
+            windowsHide: true,
         });
         child.unref();
         log(`Daemon started (PID ${child.pid})`);
@@ -502,6 +676,7 @@ daemon
     const child = spawn(process.execPath, args, {
         detached: true,
         stdio: 'ignore',
+        windowsHide: true,
     });
     child.unref();
     log(`Daemon restarted (PID ${child.pid})`);
@@ -534,7 +709,7 @@ daemon
 });
 daemon
     .command('install')
-    .description('Install daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows)')
+    .description('Install daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows, systemd --user unit on Linux)')
     .action(async () => {
     if (process.platform === 'win32') {
         try {
@@ -588,6 +763,62 @@ daemon
         catch { /* hooks package not built yet — task install still succeeds */ }
         process.exit(0);
     }
+    if (process.platform === 'linux') {
+        if (!hasSystemctl()) {
+            log('systemd --user is not available on this host.');
+            log('Run the daemon manually with: agentdeck daemon start');
+            log('(or add your own autostart entry).');
+        }
+        else {
+            try {
+                installUnit();
+                startUnit();
+                log(`systemd user unit '${SERVICE_NAME}' installed and started.`);
+                log(`Unit file: ${getUnitPath()}`);
+                if (process.env.AGENTDECK_DATA_DIR) {
+                    log(`Data dir: ${getDataDir()} (AGENTDECK_DATA_DIR persisted into the unit — re-run 'agentdeck daemon install' to change it)`);
+                }
+                else {
+                    log(`Data dir: ${getDataDir()}`);
+                }
+                log('For boot-without-login on a headless host, run once: loginctl enable-linger $USER');
+            }
+            catch (e) {
+                const detail = e.stderr?.toString().trim() || e.message;
+                log('Failed to install the systemd user unit.');
+                if (detail)
+                    log(detail);
+                log('You can still run the daemon manually with: agentdeck daemon start');
+                process.exit(1);
+            }
+        }
+        // Install Codex + OpenCode hooks for parity with the macOS/Windows paths.
+        try {
+            const { installCodexHooksIfNeeded } = await import('@agentdeck/hooks');
+            const result = installCodexHooksIfNeeded();
+            if (result.installed) {
+                log('Codex lifecycle hooks installed in ~/.codex/config.toml');
+                if (result.warning)
+                    log(`Codex hooks degraded: ${result.warning}`);
+            }
+            else if (result.reason) {
+                log(`Codex hooks skipped: ${result.reason}`);
+            }
+        }
+        catch { /* hooks package not built yet — install still succeeds */ }
+        try {
+            const { installOpenCodeHooksIfNeeded, opencodePluginPath } = await import('@agentdeck/hooks');
+            const result = installOpenCodeHooksIfNeeded();
+            if (result.installed) {
+                log(`OpenCode observer plugin installed at ${opencodePluginPath()}`);
+            }
+            else if (result.reason) {
+                log(`OpenCode observer plugin skipped: ${result.reason}`);
+            }
+        }
+        catch { /* hooks package not built yet — install still succeeds */ }
+        process.exit(0);
+    }
     if (process.platform !== 'darwin') {
         log('LaunchAgent is macOS-only');
         process.exit(1);
@@ -630,7 +861,7 @@ daemon
 });
 daemon
     .command('uninstall')
-    .description('Remove daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows)')
+    .description('Remove daemon auto-start (LaunchAgent on macOS, Scheduled Task on Windows, systemd --user unit on Linux)')
     .action(async () => {
     if (process.platform === 'win32') {
         if (!taskExists()) {
@@ -656,6 +887,17 @@ daemon
         }
         process.exit(0);
     }
+    if (process.platform === 'linux') {
+        if (!unitExists()) {
+            log(`systemd user unit '${SERVICE_NAME}' is not installed.`);
+            process.exit(0);
+        }
+        // Graceful daemon shutdown first, then disable + remove the unit.
+        await stopDaemon(BRIDGE_WS_PORT);
+        disableUnit();
+        log(`systemd user unit '${SERVICE_NAME}' removed.`);
+        process.exit(0);
+    }
     if (!existsSync(PLIST_PATH)) {
         log('LaunchAgent not installed');
         return;
@@ -961,6 +1203,7 @@ program
     .option('-e, --env <env>', 'PlatformIO environment for default firmware path')
     .option('-f, --firmware <path>', 'Firmware .bin path')
     .option('--build', 'Build the PlatformIO environment before upload')
+    .option('--stage', 'Stage for pull OTA: the board installs it on its next feed pull (no live WS needed)')
     .action(async (target, opts) => {
     const { readDaemonInfo, findDaemonPort } = await import('./session-registry.js');
     const info = readDaemonInfo();
@@ -974,12 +1217,25 @@ program
         execFileSync(pio, ['run', '-e', env], {
             cwd: join(projectRootPath(), 'esp32'),
             stdio: 'inherit',
+            windowsHide: true,
         });
     }
     // Send the canonical board string, not the raw alias — the daemon matches
     // `target` against device_info.board, so `ttgo` must become `ttgo_t_display`.
     const daemonTarget = resolveEsp32OtaDaemonTarget(target);
     const firmwarePath = resolveEsp32FirmwarePath(target, opts.env, opts.firmware);
+    if (opts.stage) {
+        // Pull-OTA staging: for wake-sync-sleep boards (XTeink X3/X4) that never
+        // hold a live WS. The daemon adverts the build on the board's feed pulls;
+        // the board downloads + flashes itself on its next wake.
+        const { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath, stage: true }, 30_000);
+        if (statusCode < 200 || statusCode >= 300 || body.ok === false) {
+            throw new Error(String(body.error ?? `HTTP ${statusCode}`));
+        }
+        log(`Staged for ${body.board}: ${formatBytes(body.bytes)} md5=${body.md5}`);
+        log('The board installs it on its next feed pull (battery cadence: typically within 15-60 min).');
+        return;
+    }
     log(`Uploading ${firmwarePath} to ${daemonTarget} via daemon :${port}...`);
     let { statusCode, body } = await postJsonWithTimeout(`http://127.0.0.1:${port}/esp32/ota`, { target: daemonTarget, firmwarePath }, 15 * 60_000);
     if (body.ok === false && String(body.error ?? '').startsWith('firmware_unreadable')) {
@@ -1194,7 +1450,11 @@ idotmatrix
         return;
     log('Scanning for BLE devices (5 seconds)...');
     try {
-        const { code, stdout } = await runBlePython(runtime.python, [runtime.paths.scripts.idotmatrixScan], true);
+        // Panels are identified by advertised service UUID first and known name
+        // families second; settings.json `idotmatrixNamePrefixes` widens the
+        // latter for a rebranded panel that hides its service.
+        const { loadIDotMatrixNamePrefixes } = await import('./idotmatrix/idotmatrix-settings.js');
+        const { code, stdout } = await runBlePython(runtime.python, [runtime.paths.scripts.idotmatrixScan, ...loadIDotMatrixNamePrefixes()], true);
         if (code !== 0) {
             log('Failed to run scan script.');
             process.exitCode = 1;
@@ -2329,7 +2589,7 @@ export async function runCli(argv = process.argv) {
         await showDefaultStatusOrHelp();
         return;
     }
-    program.parse(argv);
+    program.parse(applyGlobalEnvArgs(argv));
 }
 export { program };
 if (isMainModule()) {