@commonlyai/cli 0.1.34 → 0.1.36

package/package.json

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

package/src/commands/agent.js

@@ -50,6 +50,7 @@ import {
   createClaimHandicap,
   createClaimKeeper,
   deliverChatReply,
+  frameDecisionForkRule,
   peerHoldsFrame,
   resolveCascadeSettings,
 } from '../lib/enforcement.js';
@@ -694,6 +695,18 @@ const extractPrompt = (event) => {
       'Only post a concise pod update if a human needs it; otherwise return NO_REPLY.',
     ].join('\n');
   }
+  if (event.type === 'decision.ruled') {
+    if (!p.decisionId || !p.pick || !p.ruledAt) return null;
+    const ruler = p.ruledBy?.username || 'A human';
+    return [
+      '[Decision ruled]',
+      `${ruler} chose: ${String(p.pick)}`,
+      `Decision: ${String(p.decisionId)}`,
+      `Ruled at: ${String(p.ruledAt)}`,
+      '',
+      'Continue with this ruling. Post a concise update only if it materially helps the pod; otherwise return NO_REPLY.',
+    ].join('\n');
+  }
   return null;
 };
 
@@ -1050,7 +1063,7 @@ export const performRun = ({
     const memoryLongTerm = await readLongTerm(client, { onError });
 
     log(`[${event.type}] spawning ${adapter.name}`);
-    const result = await adapter.spawn(prompt, {
+    const result = await adapter.spawn(frameDecisionForkRule(prompt), {
       sessionId,
       cwd: agentCwd,
       env: process.env,

package/src/commands/daemon.js

@@ -8,7 +8,9 @@
 
 import { hostname, homedir } from 'os';
 import { spawn } from 'child_process';
-import { existsSync, mkdirSync, openSync } from 'fs';
+import {
+  existsSync, mkdirSync, openSync, rmSync, writeFileSync,
+} from 'fs';
 import { join } from 'path';
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
@@ -20,6 +22,10 @@ import {
 } from '../lib/daemon-supervisor.js';
 import { loadAgentToken, saveAgentToken } from './agent.js';
 import { getAdapter } from '../lib/adapters/index.js';
+import {
+  installDaemonService,
+  uninstallDaemonService,
+} from '../lib/daemon-service.js';
 
 const requireDaemonRecord = () => {
   const record = loadDaemonRecord();
@@ -171,6 +177,49 @@ Examples:
       }
     });
 
+  // ── install / uninstall (ADR-026 D1) ──────────────────────────────────────
+  const serviceDeps = () => ({
+    writeFile: (file, content) => writeFileSync(file, content, 'utf8'),
+    mkdirp: (dir) => { if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); },
+    existsFile: (file) => existsSync(file),
+    removeFile: (file) => rmSync(file),
+    execCmd: (argv) => new Promise((resolvePromise, rejectPromise) => {
+      const child = spawn(argv[0], argv.slice(1), { stdio: 'ignore' });
+      child.on('error', rejectPromise);
+      child.on('exit', (code) => (code === 0
+        ? resolvePromise()
+        : rejectPromise(new Error(`${argv.join(' ')} exited ${code}`))));
+    }),
+    log: (line) => console.log(line),
+  });
+
+  daemon
+    .command('install')
+    .description('Register the daemon as a login service (launchd/systemd) so it survives reboots')
+    .action(async () => {
+      try {
+        // A service without a credential just crash-loops at boot.
+        requireDaemonRecord();
+        await installDaemonService(serviceDeps());
+        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}`);
+        process.exitCode = 1;
+      }
+    });
+
+  daemon
+    .command('uninstall')
+    .description('Remove the daemon login service (agents stop being supervised on this machine)')
+    .action(async () => {
+      try {
+        await uninstallDaemonService(serviceDeps());
+      } catch (error) {
+        console.error(`Daemon uninstall failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   // ── run (ADR-026 Phase 2, slice 2) ────────────────────────────────────────
   daemon
     .command('run')

package/src/lib/daemon-service.js

@@ -0,0 +1,135 @@
+/**
+ * ADR-026 D1: install-once service registration for the resident daemon.
+ *
+ * macOS gets a launchd LaunchAgent (KeepAlive — launchd itself restarts a
+ * dead daemon), Linux a systemd user unit (Restart=always). Both run the
+ * exact interpreter + CLI entry that executed `daemon install`, resolved at
+ * install time — a PATH lookup at boot would race version managers and
+ * silently run a different install than the one the user tested.
+ *
+ * Pure generators + injected side effects, same discipline as the
+ * supervisor: the unit CONTENT is unit-testable without touching launchctl.
+ */
+
+import { homedir } from 'os';
+import { join, dirname, resolve } from 'path';
+
+export const LAUNCHD_LABEL = 'me.commonly.daemon';
+export const SYSTEMD_UNIT = 'commonly-daemon.service';
+
+export const daemonLogPath = (home = homedir()) => join(home, '.commonly', 'logs', 'daemon', 'daemon.log');
+
+export const servicePaths = (platform = process.platform, home = homedir()) => (
+  platform === 'darwin'
+    ? { kind: 'launchd', file: join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`) }
+    : { kind: 'systemd', file: join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT) }
+);
+
+const xmlEscape = (value) => String(value)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// 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
+// seat dies at adapter detection.
+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"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${LAUNCHD_LABEL}</string>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+\t\t<key>PATH</key>
+\t\t<string>${xmlEscape(childPath(nodePath))}</string>
+\t\t<key>HOME</key>
+\t\t<string>${xmlEscape(home)}</string>
+\t</dict>
+\t<key>ProgramArguments</key>
+\t<array>
+\t\t<string>${xmlEscape(nodePath)}</string>
+\t\t<string>${xmlEscape(cliPath)}</string>
+\t\t<string>daemon</string>
+\t\t<string>run</string>
+\t</array>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<true/>
+\t<key>StandardOutPath</key>
+\t<string>${xmlEscape(daemonLogPath(home))}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xmlEscape(daemonLogPath(home))}</string>
+</dict>
+</plist>
+`;
+
+export const systemdUnit = ({ nodePath, cliPath }) => `[Unit]
+Description=Commonly local agent daemon (ADR-026)
+After=network-online.target
+
+[Service]
+ExecStart=${nodePath} ${cliPath} daemon run
+Restart=always
+RestartSec=5
+Environment=PATH=${childPath(nodePath)}
+
+[Install]
+WantedBy=default.target
+`;
+
+export const installDaemonService = async ({
+  platform = process.platform,
+  home = homedir(),
+  nodePath = process.execPath,
+  cliPath = resolve(process.argv[1]),
+  writeFile,
+  mkdirp,
+  execCmd, // async (argv: string[]) => void — throws on failure
+  log = () => {},
+}) => {
+  const target = servicePaths(platform, home);
+  mkdirp(dirname(target.file));
+  mkdirp(dirname(daemonLogPath(home)));
+
+  if (target.kind === 'launchd') {
+    writeFile(target.file, launchdPlist({ nodePath, cliPath, home }));
+    // 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 }));
+    await execCmd(['systemctl', '--user', 'daemon-reload']);
+    await execCmd(['systemctl', '--user', 'enable', '--now', SYSTEMD_UNIT]);
+  }
+  log(`Installed ${target.kind} service (${target.file}). Logs: ${daemonLogPath(home)}`);
+  return target;
+};
+
+export const uninstallDaemonService = async ({
+  platform = process.platform,
+  home = homedir(),
+  existsFile,
+  removeFile,
+  execCmd,
+  log = () => {},
+}) => {
+  const target = servicePaths(platform, home);
+  if (!existsFile(target.file)) {
+    log('No installed daemon service found.');
+    return null;
+  }
+  if (target.kind === 'launchd') {
+    await execCmd(['launchctl', 'unload', '-w', target.file]).catch(() => {});
+  } else {
+    await execCmd(['systemctl', '--user', 'disable', '--now', SYSTEMD_UNIT]).catch(() => {});
+  }
+  removeFile(target.file);
+  log(`Removed ${target.kind} service (${target.file}).`);
+  return target;
+};

package/src/lib/enforcement.js

@@ -28,6 +28,20 @@ export const CLAIMABLE_EVENT_TYPES = new Set([
   'dm.message',
 ]);
 
+// A decision card is the durable path for a real human choice. This lives in
+// wrapper enforcement, rather than only in the MCP tool description, because
+// a task-shaped prompt can otherwise make an agent phrase the same fork as a
+// prose @ask. The rule is framing, not a classifier: the agent still judges
+// whether the work genuinely cannot continue without a human ruling.
+export const DECISION_FORK_FRAME = [
+  '[Decision forks]',
+  'If you are blocked on a genuine fork that needs a human choice, call commonly_request_decision; do not post a prose @ask.',
+  'Use it only when you cannot safely continue before a ruling. Give 2–4 concrete options and mark one recommendation.',
+  'Use ordinary pod messages for status, factual questions, and coordination that do not require a human choice.',
+].join('\n');
+
+export const frameDecisionForkRule = (prompt) => `${DECISION_FORK_FRAME}\n\n${prompt}`;
+
 // ── trigger classification ──────────────────────────────────────────────────
 
 /**