@commonlyai/cli 0.1.73 → 0.1.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.73",
+  "version": "0.1.74",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/daemon.js

@@ -9,7 +9,7 @@
 import { hostname, homedir } from 'os';
 import { spawn } from 'child_process';
 import {
-  chmodSync, closeSync, existsSync, mkdirSync, openSync, rmSync, watch, writeFileSync,
+  chmodSync, closeSync, existsSync, mkdirSync, openSync, rmSync, watch,
 } from 'fs';
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
@@ -21,7 +21,7 @@ import {
 } from '../lib/daemon-supervisor.js';
 import { loadAgentToken, saveAgentToken } from './agent.js';
 import { getLastTurn } from '../lib/session-store.js';
-import { getAdapter } from '../lib/adapters/index.js';
+import { getAdapter, providerKeyEnvNames } from '../lib/adapters/index.js';
 import {
   installDaemonService,
   uninstallDaemonService,
@@ -29,6 +29,7 @@ import {
   stopDaemonService,
   restartDaemonService,
   daemonLogPath,
+  missingProviderKeys,
   servicePaths,
 } from '../lib/daemon-service.js';
 import { daemonLogsDir, daemonSeatLogPath, readLogTail } from '../lib/daemon-logs.js';
@@ -237,7 +238,10 @@ Examples:
 
   // ── install / uninstall (ADR-026 D1) ──────────────────────────────────────
   const serviceDeps = () => ({
-    writeFile: (file, content) => writeFileSync(file, content, 'utf8'),
+    // writeFile is deliberately NOT injected here: daemon-service.js's default
+    // writer sets the 0600 mode at CREATION, and a bare `writeFileSync(file,
+    // content, 'utf8')` dropped that — leaving the service file, which can hold
+    // a provider key, readable at umask until the chmod a moment later.
     mkdirp: (dir) => { if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); },
     chmod: (path, mode) => chmodSync(path, mode),
     ensureFile: (path) => { const fd = openSync(path, 'a', 0o600); closeSync(fd); },
@@ -270,7 +274,12 @@ Examples:
       try {
         // A service without a credential just crash-loops at boot.
         requireDaemonRecord();
-        await installDaemonService(serviceDeps());
+        // Same class one layer over (TASK-049): a service without the SEATS'
+        // provider key comes up clean, and every pi seat then dies inside its
+        // adapter. The keys are captured here because this is the only moment
+        // the operator's shell is in reach; the ones that are missing are named
+        // by installDaemonService rather than left to be discovered per seat.
+        await installDaemonService({ ...serviceDeps(), providerKeyEnvNames: providerKeyEnvNames() });
         console.log('The daemon now starts at login and is kept alive. Uninstall with: commonly daemon uninstall');
       } catch (error) {
         console.error(`Daemon install failed: ${error.message}`);
@@ -342,6 +351,20 @@ Examples:
         chmodSync(logsDir, 0o700);
         const stampLog = (line) => console.log(`${new Date().toISOString()} ${line}`);
 
+        // TASK-049: fail loudly at BIND, once, naming the variable.
+        //
+        // A service-started daemon inherits a clean environment, so a provider
+        // key that lives only in the operator's shell is absent here; every pi
+        // seat then dies at adapter start with `COMMONLY_LITELLM_KEY is not set`
+        // and the operator sees crash loops with no cause at daemon level. One
+        // line at startup answers the question the log would otherwise take a
+        // seat autopsy to answer. Not fatal: the daemon's other seats are
+        // unaffected, and refusing to start would turn one missing key into a
+        // whole-machine outage.
+        for (const name of missingProviderKeys({ names: providerKeyEnvNames() })) {
+          stampLog(`WARNING: ${name} is not set in this environment — a seat whose adapter needs it will fail to start. Export it and re-run: commonly daemon install (docs/agents/daemon-service-environment.md)`);
+        }
+
         const supervisor = createDaemonSupervisor({
           record,
           client,

package/src/lib/adapters/index.js

@@ -22,3 +22,18 @@ const ADAPTERS = {
 export const listAdapterNames = () => Object.keys(ADAPTERS);
 
 export const getAdapter = (name) => ADAPTERS[name] || null;
+
+/**
+ * TASK-049: the environment a seat's ADAPTER needs from the operator's shell.
+ *
+ * The adapter owns the provider, so the adapter declares the variable (see
+ * `pi.js`); the daemon reads the list to carry those keys into its login
+ * service, because launchd and systemd start the daemon with a clean
+ * environment — a key that exists only in an interactive shell is absent at
+ * boot, and the seat then dies inside its own adapter. An adapter that
+ * authenticates through its own CLI (claude, codex) declares nothing here and
+ * contributes nothing.
+ */
+export const providerKeyEnvNames = (adapters = ADAPTERS) => [...new Set(
+  Object.values(adapters).map((adapter) => adapter.providerKeyEnv).filter(Boolean),
+)];

package/src/lib/adapters/pi.js

@@ -386,6 +386,14 @@ const runPi = ({ args, cwd, env, payload, timeoutMs, credentials = [], spawnImpl
 export default {
   name: 'pi',
 
+  // TASK-049: the variable this adapter needs from the environment of whatever
+  // process spawns it. Declared HERE because the adapter owns the provider; the
+  // registry collects it (adapters/index.js) so the daemon can carry the key
+  // into its login service and fail loudly at bind when it is absent, instead
+  // of the seat dying at line ~406 with nothing naming the missing variable at
+  // daemon level.
+  providerKeyEnv: DEFAULT_PROVIDER.apiKeyEnv,
+
   async detect() {
     const res = spawnSync('pi', ['--version'], { encoding: 'utf8' });
     if (res.error || res.status !== 0) return null;

package/src/lib/daemon-service.js

@@ -11,6 +11,8 @@
  * supervisor: the unit CONTENT is unit-testable without touching launchctl.
  */
 
+import { randomBytes } from 'crypto';
+import { renameSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname, resolve } from 'path';
 
@@ -28,6 +30,29 @@ export const servicePaths = (platform = process.platform, home = homedir()) => (
 const xmlEscape = (value) => String(value)
   .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
+// The systemd sink is NOT the plist sink, so escaping one is not escaping both.
+// Inside `Environment="…"` a raw `"` closes the quote, and a raw newline ends
+// the assignment so the remainder of the key lands in the unit as a directive.
+// The adversary here is the operator's own environment, so severity is low —
+// but correctness does not need an adversary: a provider key containing a `"`
+// writes a unit that will not start, with nothing on screen to say why.
+// systemd quoted values carry C-style escapes (systemd.syntax(7)), so both
+// values are escaped and neither sink is trusted to be the harmless one. The
+// last replacement is the least obvious: `Environment=` does NOT expand `$VAR`
+// but DOES perform specifier expansion (systemd.exec(5), "Specifier expansion is
+// performed"), and `systemd.unit(5)` gives the escape — `%%` in place of `%`.
+// A key containing `%h` would otherwise be rewritten to the home directory: the
+// unit parses, the daemon starts, the seat gets a key nobody exported, and it
+// fails at the provider with nothing at daemon level naming the cause — the same
+// failure class this code exists to remove, arriving through the escaping.
+const systemdEscape = (value) => String(value)
+  .replace(/%/g, '%%')
+  .replace(/\\/g, '\\\\')
+  .replace(/"/g, '\\"')
+  .replace(/\n/g, '\\n')
+  .replace(/\r/g, '\\r')
+  .replace(/\t/g, '\\t');
+
 // PATH matters for the CHILDREN: the daemon spawns `commonly agent run`,
 // which spawns the user's claude/codex CLI by name. launchd's default PATH
 // has no /opt/homebrew/bin, so without this the daemon comes up and every
@@ -36,7 +61,87 @@ const childPath = (nodePath) => [
   dirname(nodePath), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin',
 ].filter((entry, index, all) => all.indexOf(entry) === index).join(':');
 
-export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml version="1.0" encoding="UTF-8"?>
+// TASK-049: PATH is not the only thing the children need.
+//
+// launchd and systemd both start the daemon from a CLEAN environment, so a
+// seat's provider key that exists only in the operator's interactive shell is
+// absent at boot — and the seat then dies inside its own adapter (`pi.js`
+// throws `COMMONLY_LITELLM_KEY is not set`). That is the same defect the PATH
+// line above fixes, one layer over, and it is fixed the same way: carry what
+// the install could see. Installation is the ONLY moment the operator's shell is
+// in reach, so the keys are captured there, and the ones that were missing are
+// named at install time rather than discovered one crash-looping seat at a time.
+//
+// The values are secrets. The daemon's own credential is a 0600 file, so the
+// service file is written 0600 too instead of being left at the umask default a
+// PATH-only unit could safely keep.
+//
+// The mode is guaranteed BY CONSTRUCTION rather than by the order of two calls:
+// the content is written to a sibling temp file CREATED 0600 and then renamed
+// over the target. `writeFileSync`'s mode applies only at creation, so the
+// obvious alternatives each leave a path open — a write straight to the target
+// cannot narrow a file an EARLIER install left at 0644 (its mode survives the
+// write, and a pre-existing 0644 service file is what every upgrade meets),
+// and a chmod after the write closes the door the key already walked through.
+// The rename also removes a second hazard, narrower than it first looks: systemd
+// does NOT re-read a changed unit by itself — it reports the file as changed on
+// disk and keeps the loaded copy until a `systemctl --user daemon-reload`. What
+// is exposed is a reader CONCURRENT with the write, and that is not exotic here:
+// an install ends by running `daemon-reload`, every other install on the machine
+// can run one at the same moment, and `systemctl --user show` reads the file.
+// After a rename each of them sees the old file or the new one, never a
+// truncated unit.
+//
+// POSIX rename replaces the destination atomically, so this needs no
+// chmod-if-exists dance and no cleanup of the old file.
+//
+// The temp NAME and the temp WRITE are each half of the same defence, and
+// neither is sufficient on its own. A predictable name (`<file>.tmp-<pid>`) lets
+// a process running as this user — which is every seat this repo spawns —
+// pre-plant a symlink at that path and capture the key when the write follows
+// it; `O_EXCL` is what actually refuses that, because it fails on a symlink at
+// the final component instead of writing through it. The random suffix only
+// removes the easy target, and the cleanup only deletes a temp this call made.
+export const SERVICE_FILE_MODE = 0o600;
+
+// Exported so the O_EXCL refusal is witnessed against a real symlink at a known
+// path rather than assumed from the absence of a race.
+export const serviceTempPath = (file, suffix = randomBytes(6).toString('hex')) => `${file}.tmp-${suffix}`;
+
+export const writeServiceFile = (file, content, { suffix } = {}) => {
+  const tmp = serviceTempPath(file, suffix);
+  let created = false;
+  try {
+    // `wx` = O_CREAT|O_EXCL: the write either creates the temp itself or does not
+    // happen at all, so a planted path is refused rather than followed.
+    writeFileSync(tmp, content, { encoding: 'utf8', mode: SERVICE_FILE_MODE, flag: 'wx' });
+    created = true;
+    renameSync(tmp, file);
+  } catch (error) {
+    // Only the temp this call created is ours to remove. After a refused write
+    // the path belongs to whoever planted it.
+    if (created) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        // Nothing to clean up; the original error is the one that matters.
+      }
+    }
+    throw error;
+  }
+};
+export const providerEnvPairs = ({ names = [], env = process.env } = {}) => names
+  .filter((name) => env[name])
+  .map((name) => [name, String(env[name])]);
+
+export const missingProviderKeys = ({ names = [], env = process.env } = {}) => names
+  .filter((name) => !env[name]);
+
+const plistEnvPairs = (pairs) => pairs
+  .map(([name, value]) => `\t\t<key>${xmlEscape(name)}</key>\n\t\t<string>${xmlEscape(value)}</string>\n`)
+  .join('');
+
+export const launchdPlist = ({ nodePath, cliPath, home = homedir(), providerEnv = [] }) => `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
@@ -48,7 +153,7 @@ export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml
 \t\t<string>${xmlEscape(childPath(nodePath))}</string>
 \t\t<key>HOME</key>
 \t\t<string>${xmlEscape(home)}</string>
-\t</dict>
+${plistEnvPairs(providerEnv)}\t</dict>
 \t<key>ProgramArguments</key>
 \t<array>
 \t\t<string>${xmlEscape(nodePath)}</string>
@@ -69,7 +174,11 @@ export const launchdPlist = ({ nodePath, cliPath, home = homedir() }) => `<?xml
 </plist>
 `;
 
-export const systemdUnit = ({ nodePath, cliPath }) => `[Unit]
+export const systemdUnit = ({ nodePath, cliPath, providerEnv = [] }) => {
+  const providerLines = providerEnv.length
+    ? `\n${providerEnv.map(([name, value]) => `Environment="${systemdEscape(`${name}=${value}`)}"`).join('\n')}`
+    : '';
+  return `[Unit]
 Description=Commonly local agent daemon (ADR-026)
 After=network-online.target
 
@@ -77,23 +186,28 @@ After=network-online.target
 ExecStart=${nodePath} ${cliPath} daemon run --foreground
 Restart=always
 RestartSec=5
-Environment=PATH=${childPath(nodePath)}
+Environment=PATH=${childPath(nodePath)}${providerLines}
 
 [Install]
 WantedBy=default.target
 `;
+};
 
 export const installDaemonService = async ({
   platform = process.platform,
   home = homedir(),
   nodePath = process.execPath,
   cliPath = resolve(process.argv[1]),
-  writeFile,
+  // The provider keys the seats' adapters declare (adapters/index.js).
+  providerKeyEnvNames = [],
+  env = process.env,
+  writeFile = writeServiceFile,
   mkdirp,
   execCmd, // async (argv: string[]) => void — throws on failure
   chmod = () => {},
   ensureFile,
   log = () => {},
+  warn = log,
 }) => {
   const target = servicePaths(platform, home);
   mkdirp(dirname(target.file));
@@ -104,17 +218,27 @@ export const installDaemonService = async ({
     chmod(daemonLogPath(home), 0o600);
   }
 
+  const providerEnv = providerEnvPairs({ names: providerKeyEnvNames, env });
+  const missing = missingProviderKeys({ names: providerKeyEnvNames, env });
+
   if (target.kind === 'launchd') {
-    writeFile(target.file, launchdPlist({ nodePath, cliPath, home }));
+    // The mode and the atomicity are the WRITER's, not an ordering rule here:
+    // `writeServiceFile` creates a 0600 sibling and renames it over the target,
+    // so no chmod is needed on this path and no half-written unit is ever
+    // visible to launchd (see the writer for why neither half could cover both).
+    writeFile(target.file, launchdPlist({ nodePath, cliPath, home, providerEnv }));
     // Reload cleanly if a previous version is loaded; the unload of an
     // unknown label fails by design and is ignored.
     await execCmd(['launchctl', 'unload', target.file]).catch(() => {});
     await execCmd(['launchctl', 'load', '-w', target.file]);
   } else {
-    writeFile(target.file, systemdUnit({ nodePath, cliPath }));
+    writeFile(target.file, systemdUnit({ nodePath, cliPath, providerEnv }));
     await execCmd(['systemctl', '--user', 'daemon-reload']);
     await execCmd(['systemctl', '--user', 'enable', '--now', SYSTEMD_UNIT]);
   }
+  for (const name of missing) {
+    warn(`${name} is not set in this shell, so it is NOT in the service file. A seat whose adapter needs it will fail to start; export it and re-run: commonly daemon install (docs/agents/daemon-service-environment.md)`);
+  }
   log(`Installed ${target.kind} service (${target.file}). Logs: ${daemonLogPath(home)}`);
   return target;
 };