@commonlyai/cli 0.1.229 → 0.1.231

package/package.json

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

package/src/commands/agent.js

@@ -560,7 +560,12 @@ const listAgents = async (opts, deps) => {
       return 0;
     }
 
-    log(`${col('NAME', 16)} ${col('INSTANCE', 10)} ${col('RUNTIME', 14)} ${col('HOST', 6)} ${col('STATUS', 10)} LAST SEEN`);
+    // The pod roster also names the handle a person types to reach each agent
+    // (F44). It is printed whole: a cut handle reaches nobody.
+    const handleOf = (inst) => (inst.mention ? `@${inst.mention}` : '');
+    const handleWidth = opts.pod ? Math.max(6, ...rows.map((inst) => handleOf(inst).length)) : 0;
+    const handleCol = (s) => (opts.pod ? `${col(s, handleWidth)} ` : '');
+    log(`${col('NAME', 16)} ${col('INSTANCE', 10)} ${handleCol('HANDLE')}${col('RUNTIME', 14)} ${col('HOST', 6)} ${col('STATUS', 10)} LAST SEEN`);
     log('─'.repeat(80));
     rows.forEach((inst) => {
       // The pod roster names the agent `name`; the admin route uses `agentName`.
@@ -569,7 +574,7 @@ const listAgents = async (opts, deps) => {
       const host = inst.config?.runtime?.host || inst.runtime?.host || '';
       const seen = inst.lastActiveAt || inst.usage?.lastUsedAt || inst.connection?.lastSeenAt;
       const lastSeen = seen ? new Date(seen).toLocaleString() : 'never';
-      log(`${col(displayName, 16)} ${col(inst.instanceId, 10)} ${col(runtimeType, 14)} ${col(host, 6)} ${col(inst.status, 10)} ${lastSeen}`);
+      log(`${col(displayName, 16)} ${col(inst.instanceId, 10)} ${handleCol(handleOf(inst))}${col(runtimeType, 14)} ${col(host, 6)} ${col(inst.status, 10)} ${lastSeen}`);
     });
     return 0;
   } catch (err) {
@@ -579,6 +584,64 @@ const listAgents = async (opts, deps) => {
   }
 };
 
+/**
+ * The seat `agent logs <name> --pod` reads (F44). An agent has three names: its
+ * agentName, its instance, and the handle its @mentions route to. Any of them
+ * finds it in the pod roster, so a seat whose instance isn't "default" no longer
+ * reads as idle. An explicit --instance-id is used as given.
+ */
+export const resolveLogsSeat = async (client, podId, typed, instanceId) => {
+  // Activity is stored under the bare agentName, never an @ spelling.
+  const bare = String(typed).trim().replace(/^@/, '');
+  const isHandle = String(typed).trim().startsWith('@');
+  // A plain name with an explicit instance is used as given. An @handle still
+  // needs the roster: activity is stored under the agentName, not the handle.
+  if (instanceId && !isHandle) return { agentName: bare, instanceId };
+  const want = bare.toLowerCase();
+  let agents;
+  try {
+    ({ agents = [] } = await client.get(`/api/registry/pods/${encodeURIComponent(podId)}/agents`));
+  } catch (err) {
+    // The default instance is still worth reading when the roster isn't.
+    return {
+      agentName: bare,
+      instanceId: instanceId || 'default',
+      note: `The pod roster couldn't be read (${err.message}), so instance ${instanceId || 'default'} was read for '${bare}'.`,
+    };
+  }
+  const seatOf = (inst) => ({ agentName: inst.name || inst.agentName, instanceId: inst.instanceId || 'default' });
+  // An @handle routes to one seat, so it wins over another seat's instance of the same name.
+  if (isHandle) {
+    const byHandle = agents.filter((inst) => typeof inst.mention === 'string' && inst.mention.toLowerCase() === want);
+    if (byHandle.length === 1) return instanceId ? { ...seatOf(byHandle[0]), instanceId } : seatOf(byHandle[0]);
+    if (instanceId) {
+      return {
+        agentName: bare,
+        instanceId,
+        note: `'${typed}' is not a handle in this pod's roster, so agent name '${bare}' was read at instance ${instanceId}.`,
+      };
+    }
+  }
+  const named = (inst) => [inst.mention, inst.name || inst.agentName, inst.instanceId !== 'default' && inst.instanceId]
+    .some((n) => typeof n === 'string' && n.toLowerCase() === want);
+  const hits = agents.filter(named);
+  if (hits.length > 1) {
+    const pairs = hits.map((h) => `${h.name || h.agentName}/${h.instanceId}`).join(', ');
+    throw new Error(`${hits.length} seats are named '${typed}' here: ${pairs}. `
+      + `Run: commonly agent logs <agentName> --pod ${podId} --instance-id <instance>`);
+  }
+  if (hits.length === 0) {
+    // A typo must not read like an idle seat, so say what was read instead.
+    const handles = agents.map((inst) => inst.mention).filter(Boolean).map((m) => `@${m}`).join(', ');
+    return {
+      agentName: bare,
+      instanceId: 'default',
+      note: `'${typed}' is not in this pod's roster, so instance default was read.${handles ? ` Seats here: ${handles}` : ''}`,
+    };
+  }
+  return seatOf(hits[0]);
+};
+
 /**
  * Enumerate every agent attached on this laptop — i.e. every file in
  * ~/.commonly/tokens/*.json. Cross-references the session store for a
@@ -4466,7 +4529,7 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
     .command('logs <name>')
     .description("Show a seat's recent log: local daemon log, or server activity with --pod")
     .option('--pod <podId>', 'Read server-side events and runs for a pod you belong to')
-    .option('--instance-id <id>', 'Seat instance ID', 'default')
+    .option('--instance-id <id>', 'Seat instance ID (with --pod, found from the name when omitted)')
     .option('--follow', 'Continue printing new output', false)
     .option('--lines <n>', 'Number of trailing local lines to show', '50')
     .option('--instance <url>', 'Target Commonly instance (with --pod)')
@@ -4520,10 +4583,12 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
       if (!token) { console.error('Not logged in. Run: commonly login'); process.exit(1); }
       const client = createClient({ instance: resolveInstanceUrl(opts.instance), token });
       const printActivity = async () => {
+        const seat = await resolveLogsSeat(client, opts.pod, name, opts.instanceId);
+        if (seat.note) console.error(seat.note);
         const { events = [], runs = [] } = await client.get('/api/agents/seat-activity', {
           podId: opts.pod,
-          agentName: name,
-          instanceId: opts.instanceId,
+          agentName: seat.agentName,
+          instanceId: seat.instanceId,
         });
         events.forEach((e) => {
           const ts = new Date(e.createdAt).toTimeString().slice(0, 8);

package/src/lib/git-remote-commonly.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/** Push-only Git remote helper for a confined host seat. No provider credential enters this process. */
+import { spawn } from 'child_process';
+import { connect } from 'net';
+import { mkdtemp, readFile, rm } from 'fs/promises';
+import { createInterface } from 'readline';
+import { join } from 'path';
+
+const MAX_BUNDLE_BYTES = 6 * 1024 * 1024;
+const OID = /^[0-9a-f]{40}$/;
+const REF = /^refs\/heads\/seat\/[A-Za-z0-9._/-]+$/;
+const grantId = String(process.argv[3] || '').replace(/^commonly::/, '');
+
+const git = (args) => new Promise((resolve, reject) => {
+  const child = spawn('git', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+  let stdout = '';
+  let stderr = '';
+  child.stdout.on('data', (chunk) => { stdout += chunk; if (stdout.length > 4096) child.kill(); });
+  child.stderr.on('data', (chunk) => { stderr += chunk; if (stderr.length > 4096) child.kill(); });
+  child.on('error', reject);
+  child.on('close', (code) => (code === 0 ? resolve(stdout.trim()) : reject(new Error(stderr.trim() || 'git command failed'))));
+});
+
+const broker = (args) => new Promise((resolve, reject) => {
+  const path = process.env.COMMONLY_GH_SOCKET;
+  if (!path?.startsWith('/')) return reject(new Error('seat GitHub broker is unavailable'));
+  const socket = connect(path);
+  const chunks = [];
+  let bytes = 0;
+  socket.setTimeout(185_000, () => socket.destroy(new Error('push broker timed out')));
+  socket.on('connect', () => socket.end(JSON.stringify({ grantId, operation: 'push.branch', args })));
+  socket.on('data', (chunk) => {
+    bytes += chunk.length;
+    if (bytes > 128 * 1024) socket.destroy(new Error('push broker response is too large'));
+    else chunks.push(chunk);
+  });
+  socket.on('error', reject);
+  socket.on('end', () => {
+    try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); } catch {
+      reject(new Error('push broker response is invalid'));
+    }
+  });
+});
+
+const push = async (commands) => {
+  if (commands.length !== 1 || !commands[0].startsWith('push ')) {
+    throw new Error('exactly one branch push is allowed');
+  }
+  const spec = commands[0].slice(5);
+  if (spec.startsWith('+') || spec.split(':').length !== 2) throw new Error('force and deletion are not allowed');
+  const [source, ref] = spec.split(':');
+  if (!/^(HEAD|refs\/heads\/[A-Za-z0-9._/-]+)$/.test(source)
+    || !REF.test(ref) || ref.includes('..') || ref.endsWith('.lock') || ref.endsWith('.')) {
+    throw new Error('branch ref is not allowed');
+  }
+  const newOid = await git(['rev-parse', '--verify', `${source}^{commit}`]);
+  const baseOid = await git(['merge-base', newOid, 'refs/remotes/origin/main']);
+  if (!OID.test(newOid) || !OID.test(baseOid)) throw new Error('invalid local commit');
+  const gitPath = await git(['rev-parse', '--git-path', 'commonly-push']);
+  const directory = await mkdtemp(`${gitPath}-`);
+  try {
+    const file = join(directory, 'push.bundle');
+    await git(['bundle', 'create', file, source, `^${baseOid}`]);
+    const bundle = await readFile(file);
+    if (bundle.length > MAX_BUNDLE_BYTES) throw new Error('push bundle exceeds 6 MiB');
+    const answer = await broker({ ref, baseOid, newOid, bundle: bundle.toString('base64') });
+    if (answer.status !== 200) throw new Error(answer.body?.error || 'broker refused push');
+    return ref;
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+};
+
+const main = async () => {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(grantId)) throw new Error('invalid broker grant id');
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  let batch = [];
+  for await (const line of lines) {
+    if (line === 'capabilities') {
+      process.stdout.write('push\n\n');
+    } else if (line === 'list for-push') {
+      process.stdout.write('\n');
+    } else if (line.startsWith('push ')) {
+      batch.push(line);
+    } else if (line === '' && batch.length) {
+      const ref = batch[0].split(':').at(-1);
+      try {
+        const accepted = await push(batch);
+        process.stdout.write(`ok ${accepted}\n\n`);
+      } catch (error) {
+        process.stdout.write(`error ${ref} ${String(error.message).replace(/[\r\n]/g, ' ')}\n\n`);
+      }
+      batch = [];
+    } else if (line !== '') {
+      throw new Error('unsupported Git remote command');
+    }
+  }
+};
+
+main().catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 2; });

package/src/lib/host-gh-broker.js

@@ -0,0 +1,152 @@
+/**
+ * Per-spawn GitHub command bridge for a confined host seat. The socket carries
+ * no secret: its trusted owner holds the runtime token and chooses the backend
+ * URL. The Codex permission profile must allow only this seat's exact socket.
+ */
+import { createServer } from 'net';
+import { chmod, lstat, mkdir, mkdtemp, readFile, rm, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { join, resolve } from 'path';
+
+const MAX_REQUEST_BYTES = 64 * 1024;
+const MAX_RESPONSE_BYTES = 128 * 1024;
+const SHIM_SOURCE = fileURLToPath(new URL('./host-gh-shim.mjs', import.meta.url));
+const PUSH_HELPER_SOURCE = fileURLToPath(new URL('./git-remote-commonly.mjs', import.meta.url));
+const MAX_PUSH_REQUEST_BYTES = 9 * 1024 * 1024;
+
+const reply = (socket, status, body) => {
+  if (!socket.destroyed) socket.end(JSON.stringify({ status, body }));
+};
+
+export const startSeatGhBroker = async ({
+  runtimeToken, instanceUrl, shimRoot, fetchImpl = fetch,
+  root = join(homedir(), '.commonly', 'host-gh'),
+}) => {
+  if (typeof runtimeToken !== 'string' || !runtimeToken.startsWith('cm_agent_')) {
+    throw new Error('host GitHub broker requires a runtime token');
+  }
+  const endpoint = new URL(instanceUrl);
+  if (!['https:', 'http:'].includes(endpoint.protocol) || endpoint.username || endpoint.password) {
+    throw new Error('host GitHub broker requires an HTTP instance URL');
+  }
+  if (endpoint.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(endpoint.hostname)) {
+    throw new Error('host GitHub broker requires HTTPS outside localhost');
+  }
+  if (typeof shimRoot !== 'string' || !shimRoot) {
+    throw new Error('host GitHub broker requires a seat-visible shim root');
+  }
+  if (resolve(shimRoot) === resolve(root)) {
+    throw new Error('host GitHub shims cannot share the protected socket root');
+  }
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const rootStats = await lstat(root);
+  if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+    throw new Error('host GitHub broker root must be a real directory');
+  }
+  await chmod(root, 0o700);
+  const shimRootStats = await lstat(shimRoot);
+  if (!shimRootStats.isDirectory() || shimRootStats.isSymbolicLink()) {
+    throw new Error('host GitHub shim root must be a real directory');
+  }
+  let socketDirectory;
+  let directory;
+  let server;
+  const connections = new Set();
+  try {
+    socketDirectory = await mkdtemp(join(root, 'seat-'));
+    directory = await mkdtemp(join(shimRoot, '.commonly-gh-'));
+    const socketPath = join(socketDirectory, 'broker.sock');
+    const shimPath = join(directory, 'gh');
+    const pushHelperPath = join(directory, 'git-remote-commonly');
+    const shimSource = await readFile(SHIM_SOURCE, 'utf8');
+    await writeFile(shimPath, `#!${process.execPath}\n${shimSource.replace(/^#![^\n]*\n/, '')}`, { mode: 0o500 });
+    await chmod(shimPath, 0o555);
+    const helperSource = await readFile(PUSH_HELPER_SOURCE, 'utf8');
+    await writeFile(pushHelperPath, `#!${process.execPath}\n${helperSource.replace(/^#![^\n]*\n/, '')}`, { mode: 0o500 });
+    await chmod(pushHelperPath, 0o555);
+    server = createServer({ allowHalfOpen: true }, (socket) => {
+      connections.add(socket);
+      socket.on('close', () => connections.delete(socket));
+      let chunks = [];
+      let size = 0;
+      socket.setTimeout(15_000, () => socket.destroy());
+      socket.on('error', () => {});
+      socket.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > MAX_PUSH_REQUEST_BYTES) {
+          reply(socket, 413, { error: 'request_too_large' });
+          chunks = [];
+        } else {
+          chunks.push(chunk);
+        }
+      });
+      socket.on('end', async () => {
+        if (socket.destroyed || size > MAX_PUSH_REQUEST_BYTES) return;
+        let request;
+        try { request = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch {
+          reply(socket, 400, { error: 'invalid_request' });
+          return;
+        }
+        const { grantId, operation, args } = request || {};
+        if (!/^[A-Za-z0-9_-]{1,128}$/.test(grantId)
+          || typeof operation !== 'string' || !args || typeof args !== 'object'
+          || Array.isArray(args) || Object.keys(request).some((key) => !['grantId', 'operation', 'args'].includes(key))) {
+          reply(socket, 400, { error: 'invalid_request' });
+          return;
+        }
+        if (operation !== 'push.branch' && size > MAX_REQUEST_BYTES) {
+          reply(socket, 413, { error: 'request_too_large' });
+          return;
+        }
+        if (operation === 'push.branch') socket.setTimeout(180_000, () => socket.destroy());
+        try {
+          const suffix = operation === 'push.branch' ? 'push' : 'cli';
+          const url = new URL(`/api/mcp/grants/${encodeURIComponent(grantId)}/${suffix}`, endpoint);
+          const response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${runtimeToken}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(operation === 'push.branch' ? args : { operation, args }),
+            signal: AbortSignal.timeout(operation === 'push.branch' ? 180_000 : 15_000),
+          });
+          const bodyText = await response.text();
+          if (Buffer.byteLength(bodyText, 'utf8') > MAX_RESPONSE_BYTES) {
+            reply(socket, 502, { error: 'broker_response_too_large' });
+            return;
+          }
+          let body;
+          try { body = JSON.parse(bodyText); } catch { body = { error: 'broker_response_invalid' }; }
+          reply(socket, response.status, body);
+        } catch {
+          reply(socket, 502, { error: 'broker_unavailable' });
+        }
+      });
+    });
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(socketPath, () => {
+        server.off('error', reject);
+        resolve();
+      });
+    });
+    return {
+      socketPath,
+      shimPath,
+      pushHelperPath,
+      directory,
+      socketDirectory,
+      async close() {
+        for (const socket of connections) socket.destroy();
+        await new Promise((resolve) => server.close(resolve));
+        await rm(directory, { recursive: true, force: true });
+        await rm(socketDirectory, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    for (const socket of connections) socket.destroy();
+    if (server?.listening) await new Promise((resolve) => server.close(resolve));
+    if (directory) await rm(directory, { recursive: true, force: true });
+    if (socketDirectory) await rm(socketDirectory, { recursive: true, force: true });
+    throw error;
+  }
+};

package/src/lib/host-gh-shim.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/** Narrow gh-compatible entrypoint for confined Commonly host seats. */
+import { connect } from 'net';
+
+const fail = (message) => {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 2;
+};
+
+const parse = (argv) => {
+  const parts = [...argv];
+  const grantFlag = parts.indexOf('--grant-id');
+  if (grantFlag < 0 || grantFlag + 1 >= parts.length) throw new Error('pass --grant-id <grant>');
+  const [grantId] = parts.splice(grantFlag + 1, 1);
+  parts.splice(grantFlag, 1);
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(grantId)) throw new Error('invalid grant id');
+
+  const [area, action, ...rest] = parts;
+  let operation;
+  let requiredFlags = [];
+  let allowedFlags = [];
+  let numberField;
+  if (area === 'pr' && action === 'create') {
+    operation = 'pr.create';
+    requiredFlags = ['--title', '--head', '--base'];
+    allowedFlags = [...requiredFlags, '--body', '--draft'];
+  } else if (area === 'pr' && action === 'view') {
+    operation = 'pr.view'; numberField = 'pullNumber';
+  } else if (area === 'pr' && action === 'comment') {
+    operation = 'pr.comment'; numberField = 'pullNumber';
+    requiredFlags = ['--body']; allowedFlags = requiredFlags;
+  } else if (area === 'pr' && action === 'review') {
+    operation = 'pr.review_comment'; numberField = 'pullNumber';
+    requiredFlags = ['--comment', '--body']; allowedFlags = requiredFlags;
+  } else if (area === 'issue' && action === 'comment') {
+    operation = 'issue.comment'; numberField = 'issueNumber';
+    requiredFlags = ['--body']; allowedFlags = requiredFlags;
+  } else {
+    throw new Error('gh operation is not allowed for this seat');
+  }
+
+  const args = {};
+  if (numberField) {
+    const value = rest.shift();
+    if (!/^[1-9][0-9]*$/.test(value || '') || !Number.isSafeInteger(Number(value))) {
+      throw new Error('pass a positive issue or PR number');
+    }
+    args[numberField] = Number(value);
+  }
+  const flags = new Set();
+  while (rest.length) {
+    const flag = rest.shift();
+    if (!allowedFlags.includes(flag) || flags.has(flag)) throw new Error(`flag is not allowed: ${flag}`);
+    flags.add(flag);
+    if (flag === '--draft' || flag === '--comment') continue;
+    const value = rest.shift();
+    if (value === undefined || value.startsWith('--')) throw new Error(`missing value for ${flag}`);
+    if (value.length > 32 * 1024) throw new Error(`value is too long for ${flag}`);
+    args[flag.slice(2)] = value;
+  }
+  if (requiredFlags.some((flag) => !flags.has(flag))) throw new Error('required flag is missing');
+  if (flags.has('--draft')) args.draft = true;
+  return { grantId, operation, args };
+};
+
+const main = async () => {
+  const request = parse(process.argv.slice(2));
+  const socketPath = process.env.COMMONLY_GH_SOCKET;
+  if (!socketPath || !socketPath.startsWith('/')) throw new Error('seat GitHub broker is unavailable');
+  const answer = await new Promise((resolve, reject) => {
+    const socket = connect(socketPath);
+    const chunks = [];
+    let size = 0;
+    socket.setTimeout(20_000, () => socket.destroy(new Error('seat GitHub broker timed out')));
+    socket.on('connect', () => socket.end(JSON.stringify(request)));
+    socket.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > 128 * 1024) socket.destroy(new Error('seat GitHub response is too large'));
+      else chunks.push(chunk);
+    });
+    socket.on('error', reject);
+    socket.on('end', () => {
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); } catch {
+        reject(new Error('seat GitHub response is invalid'));
+      }
+    });
+  });
+  if (answer.status === 202 && answer.body?.status === 'pending_approval') {
+    process.stdout.write(`${JSON.stringify(answer.body, null, 2)}\n`);
+    return;
+  }
+  if (answer.status < 200 || answer.status >= 300) {
+    throw new Error(answer.body?.error || answer.body?.status || 'GitHub operation refused');
+  }
+  process.stdout.write(`${JSON.stringify(answer.body, null, 2)}\n`);
+};
+
+main().catch((error) => fail(error.message));