@commonlyai/cli 0.1.44 → 0.1.45

package/package.json

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

package/src/commands/agent.js

@@ -111,7 +111,7 @@ export const deleteAgentToken = (name) => {
 // podId) or is a local fact (which CLI binary to wrap). Returns a record ready
 // for saveAgentToken, or null when COMMONLY_AGENT_TOKEN isn't set (caller
 // falls back to the attach hint).
-export const BOOTSTRAP_ADAPTER_DETECT_ORDER = ['claude', 'codex'];
+export const BOOTSTRAP_ADAPTER_DETECT_ORDER = ['claude', 'codex', 'pi'];
 
 export const bootstrapAgentRecordFromEnv = async ({
   name,
@@ -254,7 +254,7 @@ const PRIVATE_RESPONSE_EVENT_TYPES = new Set(['agent.ask', 'agent.ask.response']
 // agent posted through the operator's CLI profile because it had no
 // commonly_* tools of its own). `stub` does not. Returning null means "no
 // default" — the wrapper proceeds with environment=null exactly like before.
-const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex']);
+const ADAPTERS_WITH_DEFAULT_MCP = new Set(['claude', 'codex', 'pi']);
 const CODEX_PERMISSION_PROFILE_MIN_VERSION = [0, 138, 0];
 
 const versionAtLeast = (version, minimum) => {

package/src/lib/adapters/index.js

@@ -10,11 +10,13 @@
 import stub from './stub.js';
 import claude from './claude.js';
 import codex from './codex.js';
+import pi from './pi.js';
 
 const ADAPTERS = {
   [stub.name]: stub,
   [claude.name]: claude,
   [codex.name]: codex,
+  [pi.name]: pi,
 };
 
 export const listAdapterNames = () => Object.keys(ADAPTERS);

package/src/lib/adapters/pi-commonly-mcp.mjs

@@ -0,0 +1,45 @@
+/**
+ * pi extension: Commonly's tools for a pi seat, over MCP stdio.
+ *
+ * Loaded by adapters/pi.js with `-e`. Reads COMMONLY_PI_MCP — a JSON list of
+ * `{ name, command: [...], env: {...} }` — starts each server on stdio, asks
+ * it for its tools, and registers every one with pi under its own name, so a
+ * pi seat calls `commonly_post_message` exactly as a claude or codex seat
+ * does. Tool calls are forwarded as MCP `tools/call`; results come back as
+ * text. The client lives in pi-mcp-client.mjs (jest-tested); this file only
+ * binds it to pi's `registerTool`. `typebox` resolves through pi's extension
+ * loader, which aliases its bundled copy — it is not a CLI dependency.
+ */
+
+import { Type } from 'typebox';
+import { connectMcp, readServers, toPiResult } from './pi-mcp-client.mjs';
+
+export default async function commonlyMcpBridge(pi) {
+  const servers = readServers(process.env.COMMONLY_PI_MCP);
+  const clients = [];
+  for (const server of servers) {
+    const client = connectMcp(server);
+    clients.push(client);
+    try {
+      await client.initialize();
+      const tools = await client.listTools();
+      for (const tool of tools) {
+        pi.registerTool({
+          name: tool.name,
+          label: tool.name,
+          description: tool.description || tool.name,
+          // The server's JSON schema, passed through: pi validates against it as-is.
+          parameters: Type.Unsafe(tool.inputSchema || { type: 'object', properties: {} }),
+          async execute(_toolCallId, params) {
+            return toPiResult(await client.callTool(tool.name, params));
+          },
+        });
+      }
+    } catch (error) {
+      process.stderr.write(`[commonly-pi-bridge] ${server.name}: ${error.message}\n`);
+    }
+  }
+  const shutdown = () => { for (const client of clients) client.close(); };
+  process.on('exit', shutdown);
+  if (typeof pi.on === 'function') pi.on('session_shutdown', shutdown);
+}

package/src/lib/adapters/pi-mcp-client.mjs

@@ -0,0 +1,85 @@
+/**
+ * A minimal MCP stdio client for the pi bridge (pi-commonly-mcp.mjs).
+ *
+ * The stdio transport is newline-delimited JSON-RPC; a client for four
+ * methods (initialize, tools/list, tools/call, the initialized notification)
+ * is smaller than a dependency, and keeping it in a file with no pi imports
+ * means the CLI's own jest can test it — `typebox` only resolves inside pi's
+ * extension loader, so the extension file stays thin and untested by jest.
+ */
+
+import { spawn } from 'node:child_process';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const MAX_TEXT = 50 * 1024;
+
+const truncate = (text) => (text.length <= MAX_TEXT
+  ? text
+  : `${text.slice(0, MAX_TEXT)}\n… [truncated ${text.length - MAX_TEXT} bytes]`);
+
+/** A minimal MCP stdio client: initialize, tools/list, tools/call. */
+export const connectMcp = ({ name, command, env }, { spawnImpl = spawn, timeoutMs = 60_000 } = {}) => {
+  const [cmd, ...args] = command;
+  const proc = spawnImpl(cmd, args, { env: { ...process.env, ...(env || {}) }, stdio: ['pipe', 'pipe', 'pipe'] });
+  const pending = new Map();
+  let nextId = 1;
+  let buffer = '';
+  proc.stdout.on('data', (chunk) => {
+    buffer += chunk.toString();
+    let nl;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      const waiter = msg && msg.id !== undefined ? pending.get(msg.id) : null;
+      if (!waiter) continue;
+      pending.delete(msg.id);
+      clearTimeout(waiter.timer);
+      if (msg.error) waiter.reject(new Error(`${name}: ${msg.error.message || JSON.stringify(msg.error)}`));
+      else waiter.resolve(msg.result);
+    }
+  });
+  proc.on('exit', (code) => {
+    for (const [id, waiter] of pending) {
+      pending.delete(id);
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(`${name}: MCP server exited (${code}) before answering`));
+    }
+  });
+  const send = (obj) => proc.stdin.write(`${JSON.stringify(obj)}\n`);
+  const request = (method, params) => new Promise((resolve, reject) => {
+    const id = nextId++;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`${name}: ${method} timed out after ${timeoutMs}ms`)); }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    send({ jsonrpc: '2.0', id, method, params: params || {} });
+  });
+  const notify = (method, params) => send({ jsonrpc: '2.0', method, params: params || {} });
+  const initialize = async () => {
+    const result = await request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'commonly-pi-bridge', version: '1.0.0' },
+    });
+    notify('notifications/initialized');
+    return result;
+  };
+  const listTools = async () => (await request('tools/list')).tools || [];
+  const callTool = (toolName, args) => request('tools/call', { name: toolName, arguments: args || {} });
+  const close = () => { try { proc.kill('SIGTERM'); } catch { /* already gone */ } };
+  return { initialize, listTools, callTool, close, proc };
+};
+
+/** MCP `{ content, isError }` → pi tool result. Non-text parts are named, not dropped silently. */
+export const toPiResult = (result) => {
+  const parts = (result?.content || []).map((c) => (c?.type === 'text' ? String(c.text ?? '') : `[${c?.type || 'content'} omitted]`));
+  const text = truncate(parts.join('\n'));
+  return { content: [{ type: 'text', text: result?.isError ? `error: ${text}` : text }], details: { isError: !!result?.isError } };
+};
+
+export const readServers = (raw) => {
+  if (!raw) return [];
+  try { return JSON.parse(raw).filter((s) => s?.name && Array.isArray(s.command) && s.command.length); } catch { return []; }
+};
+

package/src/lib/adapters/pi.js

@@ -0,0 +1,241 @@
+/**
+ * pi adapter — ADR-005 adapter contract for the pi coding agent
+ * (https://pi.dev, `@earendil-works/pi-coding-agent`), the harness that lets
+ * a wrapper seat run on any OpenAI-compatible model: DeepSeek through
+ * LiteLLM today, anything LiteLLM routes tomorrow.
+ *
+ * Why a third adapter (2026-09-18): the Luna code-writer seats ran codex on
+ * ChatGPT quota, and when that ran out the fleet stalled. codex 0.153 cannot
+ * drive DeepSeek — it sends a `namespace`-type tool DeepSeek's API rejects
+ * even with every feature flag off — while pi headless on LiteLLM's
+ * `deepseek-v4-flash` wrote a file with its `write` tool, ran it with `bash`
+ * and resumed its session on the next turn (proof on this laptop, 03:57Z).
+ * pi was already the hosted turn engine (ADR-021); this is pi as a wrapper.
+ *
+ * How pi is driven:
+ *   pi -p --mode json --provider <p> --model <m> --thinking <t>
+ *      --session-dir <seat dir> (--session-id <uuid> | --session <uuid>)
+ *      -e pi-commonly-mcp.mjs "<prompt>"
+ *
+ *   - `--session-id` creates the session on the first turn; `--session`
+ *     resumes it (`--session-id` cannot be combined with `--continue`).
+ *   - stdout is NDJSON; the reply is the last assistant `message_end`.
+ *   - Provider config is a per-seat models.json under
+ *     `~/.commonly/pi-homes/<hash>/agent`, pointed at by
+ *     PI_CODING_AGENT_DIR — never the operator's ~/.pi. The API key is an
+ *     env reference (`$COMMONLY_LITELLM_KEY`), so it never lands on disk.
+ *   - Commonly's tools reach pi through pi-commonly-mcp.mjs, an extension
+ *     that speaks MCP over stdio to every server in `environment.mcp` and
+ *     registers each tool. The token rides through the child env, never argv
+ *     (same rule as codex.js).
+ *
+ * Contract (see stub.js): detect() and spawn(prompt, ctx) → { text, newSessionId }.
+ */
+
+import { spawn as childSpawn, spawnSync } from 'child_process';
+import { createHash, randomUUID } from 'crypto';
+import { mkdir, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { buildMemoryPreamble } from '../memory-bridge.js';
+
+const DEFAULT_TIMEOUT_MS = (() => {
+  const fallback = 15 * 60 * 1000;
+  const raw = process.env.COMMONLY_AGENT_RUN_TIMEOUT_MS;
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+})();
+
+// The default provider is Commonly's own LiteLLM, reachable from a laptop
+// seat at the public ingress and from a cluster seat at the service.
+export const DEFAULT_PROVIDER = Object.freeze({
+  name: 'litellm',
+  baseUrl: 'https://litellm.commonly.me/v1',
+  api: 'openai-completions',
+  apiKeyEnv: 'COMMONLY_LITELLM_KEY',
+});
+export const DEFAULT_MODEL = 'deepseek-v4-flash';
+
+// ADR-008 `effort` → pi `--thinking`. pi's ladder is off/minimal/low/medium/high/xhigh/max.
+const THINKING = { none: 'off', off: 'off', minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max' };
+export const thinkingFor = (effort) => (effort ? THINKING[String(effort).toLowerCase()] || null : null);
+
+const BRIDGE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'pi-commonly-mcp.mjs');
+
+// Same substitution contract as claude.js / codex.js: ${COMMONLY_*}
+// placeholders in the declared MCP env are the wrapper's per-(agent, pod)
+// runtime values, filled at spawn time.
+const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
+const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
+const substitutePlaceholders = (value, ctx) => {
+  if (typeof value !== 'string' || !value.includes('${COMMONLY_')) return value;
+  const subs = {
+    COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    COMMONLY_API_URL: ctx.instanceUrl || '',
+    COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
+  };
+  return value.replace(PLACEHOLDER_RE, (whole, key) => (SUBSTITUTION_KEYS.includes(key) && subs[key] ? subs[key] : whole));
+};
+
+/** stdio MCP servers from the environment spec, placeholders filled; url-only entries are skipped. */
+export const resolveMcpServers = (mcpServers, ctx = {}) => (mcpServers || [])
+  .filter((server) => server?.name && Array.isArray(server.command) && server.command.length)
+  .map((server) => ({
+    name: server.name,
+    command: server.command.map((a) => substitutePlaceholders(a, ctx)),
+    env: Object.fromEntries(Object.entries(server.env || {}).map(([k, v]) => [k, substitutePlaceholders(v, ctx)])),
+  }));
+
+/** The provider block for models.json: the env spec's `provider` over the LiteLLM default. */
+export const resolveProvider = (environment = {}) => {
+  const spec = environment?.provider || {};
+  return {
+    name: spec.name || DEFAULT_PROVIDER.name,
+    baseUrl: spec.baseUrl || DEFAULT_PROVIDER.baseUrl,
+    api: spec.api || DEFAULT_PROVIDER.api,
+    apiKeyEnv: spec.apiKeyEnv || DEFAULT_PROVIDER.apiKeyEnv,
+  };
+};
+
+/** models.json content for one seat: one provider, one model, key by env reference. */
+export const buildModelsJson = (provider, model) => ({
+  providers: {
+    [provider.name]: {
+      name: provider.name,
+      baseUrl: provider.baseUrl,
+      apiKey: `$${provider.apiKeyEnv}`,
+      api: provider.api,
+      models: [{
+        id: model,
+        name: model,
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 32000,
+      }],
+    },
+  },
+});
+
+/** Per-seat pi home: `~/.commonly/pi-homes/<hash(agent)>`. Never the operator's ~/.pi. */
+export const seatHome = (ctx) => {
+  const identity = ctx.agentName || ctx.cwd || 'anonymous';
+  const hash = createHash('sha256').update(identity).digest('hex').slice(0, 20);
+  return ctx._piHome || join(homedir(), '.commonly', 'pi-homes', hash);
+};
+
+export const buildArgs = ({
+  prompt, provider, model, thinking, sessionId, isResume, sessionDir, bridge,
+}) => [
+  '-p',
+  '--mode', 'json',
+  '--no-extensions',
+  '--no-skills',
+  '--no-prompt-templates',
+  '--no-themes',
+  '--provider', provider,
+  '--model', model,
+  ...(thinking ? ['--thinking', thinking] : []),
+  '--session-dir', sessionDir,
+  ...(isResume ? ['--session', sessionId] : ['--session-id', sessionId]),
+  ...(bridge ? ['-e', bridge] : []),
+  prompt,
+];
+
+/** The reply is the last assistant `message_end`'s text parts; tool calls are not text. */
+export const extractReply = (stdout) => {
+  let text = '';
+  let sawAssistant = false;
+  const errors = [];
+  for (const line of String(stdout).split('\n')) {
+    if (!line.trim()) continue;
+    let event;
+    try { event = JSON.parse(line); } catch { continue; }
+    if (event?.type === 'message_end' && event.message?.role === 'assistant') {
+      const parts = (event.message.content || []).filter((c) => c?.type === 'text').map((c) => c.text || '');
+      if (parts.length) { text = parts.join('\n').trim(); sawAssistant = true; }
+    }
+    if (event?.type === 'error') errors.push(String(event.message || event.error || 'error'));
+  }
+  return { text, sawAssistant, errors };
+};
+
+const runPi = ({ args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
+  let stdout = '';
+  let stderr = '';
+  let timedOut = false;
+  const proc = spawnImpl('pi', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+  const timer = setTimeout(() => { timedOut = true; proc.kill('SIGTERM'); }, timeoutMs);
+  proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+  proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+  proc.on('error', (err) => { clearTimeout(timer); reject(err); });
+  proc.on('close', (code) => {
+    clearTimeout(timer);
+    if (timedOut) return reject(new Error(`pi timed out after ${timeoutMs}ms`));
+    const reply = extractReply(stdout);
+    if (code !== 0 && !reply.sawAssistant) {
+      const tail = (reply.errors.join(' | ') || stderr).trim().slice(-600);
+      return reject(new Error(`pi exited ${code}: ${tail}`));
+    }
+    return resolve(reply);
+  });
+});
+
+export default {
+  name: 'pi',
+
+  async detect() {
+    const res = spawnSync('pi', ['--version'], { encoding: 'utf8' });
+    if (res.error || res.status !== 0) return null;
+    const version = String(res.stdout || '').trim().split('\n').pop() || 'unknown';
+    const which = spawnSync('which', ['pi'], { encoding: 'utf8' });
+    return { path: String(which.stdout || 'pi').trim() || 'pi', version };
+  },
+
+  async spawn(prompt, ctx = {}) {
+    const isResume = !!ctx.sessionId;
+    const sessionId = ctx.sessionId || randomUUID();
+    const fullPrompt = buildMemoryPreamble(prompt, ctx.memoryLongTerm, { freshSession: !isResume });
+    const provider = resolveProvider(ctx.environment);
+    const model = ctx.environment?.model || DEFAULT_MODEL;
+    const thinking = thinkingFor(ctx.environment?.effort);
+    const baseEnv = ctx.env || process.env;
+    if (!baseEnv[provider.apiKeyEnv]) {
+      throw new Error(`pi adapter: ${provider.apiKeyEnv} is not set — the seat's environment must carry the provider key (LiteLLM virtual key)`);
+    }
+
+    // Per-seat pi home: models.json holds the provider by env reference.
+    const home = seatHome(ctx);
+    const agentDir = join(home, 'agent');
+    const sessionDir = join(home, 'sessions');
+    await mkdir(agentDir, { recursive: true, mode: 0o700 });
+    await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+    await writeFile(join(agentDir, 'models.json'), `${JSON.stringify(buildModelsJson(provider, model), null, 2)}\n`, { mode: 0o600 });
+
+    const servers = resolveMcpServers(ctx.environment?.mcp, ctx);
+    const childEnv = {
+      ...baseEnv,
+      PI_CODING_AGENT_DIR: agentDir,
+      PI_SKIP_VERSION_CHECK: '1',
+      ...(servers.length ? { COMMONLY_PI_MCP: JSON.stringify(servers) } : {}),
+    };
+    const args = buildArgs({
+      prompt: fullPrompt, provider: provider.name, model, thinking, sessionId, isResume, sessionDir,
+      bridge: servers.length ? (ctx._bridgePath || BRIDGE_PATH) : null,
+    });
+
+    const reply = await runPi({
+      args,
+      cwd: ctx.cwd,
+      env: childEnv,
+      timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+      spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
+    });
+    // Empty text with a clean exit is a silent turn; the run loop treats it
+    // as NO_REPLY-shaped and re-delivers on its own rules.
+    return { text: reply.text, newSessionId: sessionId };
+  },
+};