@karma42/agent 0.0.0-stage → 0.1.0-beta.2

package/src/session.mjs

@@ -0,0 +1,110 @@
+import { join, resolve } from 'node:path';
+import { readdirSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { makePlan, VERSION } from './plan.mjs';
+import { canonicalPath, connectionDir, digest, ensureHome, list, load, lstatExists, privateDir, readPrivate, save, withLock, writePrivate } from './state.mjs';
+import { system } from './system.mjs';
+
+export const sessionHome = () => join(homedir(), '.karma42', 'sessions');
+const TOKEN = /^[\w-]{43}$/;
+// Include the service origin: the same project/agent IDs on a local service and production are distinct.
+export const sessionId = (service, agentId) => `${digest(service)}/${agentId}`;
+export const sessionName = record => `karma42-${digest([record.service, record.agentId]).slice(0, 24)}`;
+export function validateSession(record, id) {
+  if (record?.schema !== 'client-session-1' || record.id !== id || record.id !== sessionId(record.service, record.agentId) || record.packageVersion !== VERSION
+    || !/^[\w-]{1,200}$/.test(record.agentId ?? '') || !/^[\w-]{1,64}$/.test(record.agentName ?? '')) throw new Error('Invalid session identity. Reconnect using My agents.');
+  const plan = makePlan({ provider: record.provider, mode: 'guarded', projectUrl: record.service, repo: record.repo, folder: record.folder });
+  if (plan.projectUrl !== record.service || canonicalPath(record.folder) !== record.folder) throw new Error('Session workspace changed. Review the connection again.');
+  if (record.consent !== digest([record.id, record.service, record.agentName, record.repo, record.folder, record.provider, record.packageVersion])) throw new Error('Session approval is missing or changed. Review the connection again.');
+  return record;
+}
+export function sessionConfiguration(record, home = sessionHome()) {
+  validateSession(record, record.id);
+  const name = sessionName(record);
+  // Client launches only the pinned bridge, never a model. No credential is in configuration.
+  const args = ['--yes', '--ignore-scripts', `@karma42/agent@${record.packageVersion}`, 'session-serve', '--connection', record.id, '--state-dir', home];
+  const entry = { command: 'npx', args };
+  const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+  return { name, workspace: record.folder, agent: record.agentName, project: record.service,
+    claudeCommand: ['claude', 'mcp', 'add', '--scope', 'local', name, '--', 'npx', ...args].map(quote).join(' '),
+    claude: { mcpServers: { [name]: entry } },
+    codex: `[mcp_servers.${name}]\ncommand = "npx"\nargs = ${JSON.stringify(args)}\nstartup_timeout_sec = 30\n`,
+  };
+}
+export function createSessionOperations({ home = sessionHome(), io, sys = system } = {}) {
+  home = canonicalPath(home);
+  const confirm = async text => { if (!io.interactive || !await io.confirm(text)) throw new Error('Cancelled. No coding agent or MCP connection was started.'); };
+  async function finish(dir, receipt, locked = false) {
+    const action = async () => {
+      if (!TOKEN.test(receipt.token ?? '') || !/^[\w-]{1,200}$/.test(receipt.agentId ?? '') || !/^[\w-]{1,64}$/.test(receipt.agentName ?? '')) throw new Error('Invalid private pairing receipt. Generate a fresh code.');
+      const plan = makePlan({ provider: receipt.provider, mode: 'guarded', projectUrl: receipt.service, repo: receipt.repo, folder: receipt.folder });
+      const id = sessionId(plan.projectUrl, receipt.agentId);
+      if (connectionDir(home, id) !== dir) throw new Error('Recovery identity mismatch.');
+      io.say(`Agent: ${receipt.agentName}\nProject: ${plan.projectUrl}\nRepository: ${plan.repo}\nWorkspace: ${plan.folder}\nYour existing client controls model usage, filesystem access and approvals. The package will not change permission settings or launch another coding agent. Native MCP trust prompts remain yours to approve. GitHub access and repository checkout have not been checked.`);
+      await confirm('I will supervise this session, review changes and grant only the permissions I intend. Save this named connection?');
+      const record = { schema: 'client-session-1', id, service: plan.projectUrl, agentId: receipt.agentId, agentName: receipt.agentName, repo: plan.repo, folder: plan.folder, provider: plan.provider, packageVersion: VERSION, createdAt: sys.now() };
+      record.consent = digest([id, record.service, record.agentName, record.repo, record.folder, record.provider, VERSION]);
+      // Preserve old journals on re-pair; they are credential-bound and use separate names.
+      writePrivate(join(dir, 'token'), receipt.token); save(dir, record);
+      unlinkSync(join(dir, 'pending-session.json'));
+      const config = sessionConfiguration(record, home);
+      io.say(`Saved session connection: ${id}\nMCP entry: ${config.name}\nAdd this entry ONLY to the current workspace’s MCP configuration, preserving other entries. Claude Code: run the local-scope command from the workspace below; native trust prompts remain yours. Codex: merge the TOML entry into ${record.folder}/.codex/config.toml in this trusted workspace. Never replace the entire config or change approval settings.\n${record.provider === 'claude' ? config.claudeCommand : config.codex}\nAsk this current agent to use ${config.name}, call get_project and verify agent ${record.agentName}. If the tools are missing, reload the client’s MCP configuration and return to this conversation. No separate start command is needed.\nEach project/agent has its own entry. Only one active connection may use this identity; another agent needs its own code/name. Closing a chat does not necessarily close the client’s MCP process. Disconnect this named MCP entry to release it.`);
+      return record;
+    };
+    return locked ? action() : withLock(dir, action);
+  }
+  return {
+    async connect(options) {
+      const folder = canonicalPath(resolve(options.folder ?? process.cwd()));
+      const plan = makePlan({ provider: options.provider, mode: 'guarded', projectUrl: options['project-url'], repo: 'https://github.com/placeholder/project', folder });
+      if (options['agent-id'] !== undefined && !/^[\w-]{1,200}$/.test(options['agent-id'])) throw new Error('Choose a valid agent ID.');
+      sys.verifyBundle();
+      ensureHome(home);
+      return withLock(home, async () => {
+        const expected = options['agent-id'];
+        const expectedDir = expected ? connectionDir(home, sessionId(plan.projectUrl, expected)) : null;
+        const pair = async () => {
+          await confirm('Connect your current coding session to this project? Enter the setup code privately; never paste it into your AI chat. This rotates this agent’s credential: stop its previous connection first.');
+          const code = await io.secret('One-time setup code (hidden):');
+          if (!TOKEN.test(code)) throw new Error('Use the 43-character code from My agents.');
+          const paired = await sys.request(plan.projectUrl, 'exchange', { code });
+          if (!TOKEN.test(paired?.token ?? '') || !/^[\w-]{1,200}$/.test(paired.agentId ?? '') || !/^[\w-]{1,64}$/.test(paired.agentName ?? '')) throw new Error('Unexpected pairing reply. Generate a fresh code.');
+          const authoritative = makePlan({ ...plan, projectUrl: plan.projectUrl, repo: paired.repoUrl });
+          const id = sessionId(plan.projectUrl, paired.agentId), dir = connectionDir(home, id);
+          // Recovery receipt before further approval; never lose an exchanged credential.
+          writePrivate(join(dir, 'pending-session.json'), { token: paired.token, service: plan.projectUrl, agentId: paired.agentId, agentName: paired.agentName, repo: authoritative.repo, folder, provider: plan.provider });
+          io.say(`Pairing saved privately for ${id}. Interrupted setup can be recovered with session-prepare --connection ${id}.`);
+          if (expected && expected !== paired.agentId) throw new Error('This code belongs to a different agent. Its private recovery receipt was saved; the requested connection was preserved. Review My agents before proceeding.');
+          return finish(dir, readPrivate(join(dir, 'pending-session.json'), true), Boolean(expectedDir));
+        };
+        return expectedDir ? withLock(expectedDir, pair) : pair();
+      });
+    },
+    prepare(options) {
+      const dir = connectionDir(home, options.connection);
+      if (!lstatExists(join(dir, 'pending-session.json'))) throw new Error('No interrupted session pairing found. Use session-config for a saved connection, or Reconnect for a new code.');
+      return finish(dir, readPrivate(join(dir, 'pending-session.json'), true));
+    },
+    config(options) {
+      const record = validateSession(load(connectionDir(home, options.connection)), options.connection);
+      io.say(JSON.stringify(sessionConfiguration(record, home), null, 2));
+    },
+    status() {
+      const records = list(home);
+      if (lstatExists(home)) for (const key of readdirSync(home)) {
+        if (!/^[a-f0-9]{64}$/.test(key)) continue;
+        privateDir(join(home, key));
+        for (const agent of readdirSync(join(home, key))) {
+          if (!/^[\w-]{1,200}$/.test(agent)) continue;
+          const id = `${key}/${agent}`, dir = connectionDir(home, id);
+          if (lstatExists(join(dir, 'pending-session.json'))) {
+            const { token, ...receipt } = readPrivate(join(dir, 'pending-session.json'), true);
+            const position = records.findIndex(record => record.id === id);
+            const pending = { ...receipt, id, pending: true };
+            if (position >= 0) records[position] = pending; else records.push(pending);
+          }
+        }
+      }
+      io.say(JSON.stringify(records.map(record => ({ id: record.id, agent: record.agentName, project: record.service, workspace: record.folder, provider: record.provider, mcp: sessionName(record), state: record.pending ? 'interrupted pairing; use session-prepare' : 'saved locally; live activity not checked' })), null, 2)); },
+  };
+}

package/src/state.mjs

@@ -0,0 +1,93 @@
+import { constants, lstatSync, realpathSync, fstatSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync, readdirSync } from 'node:fs';
+import { join, dirname, basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID, createHash } from 'node:crypto';
+
+export const defaultHome = () => join(homedir(), '.karma42', 'connections');
+export function canonicalPath(value) {
+  let path = resolve(value);
+  const tail = [];
+  while (!lstatExists(path)) { tail.unshift(basename(path)); path = dirname(path); }
+  return join(realpathSync(path), ...tail);
+}
+export const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function privateDir(path) {
+  try { mkdirSync(path, { mode: 0o700 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)) throw new Error('Connection storage must be a private directory, without symbolic links.');
+}
+export function ensureHome(home) {
+  // Only the caller-selected root is created recursively. Existing root must be private.
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  privateDir(home);
+}
+export function readPrivate(path, json = false) {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o077) || stat.nlink !== 1) throw new Error('Connection files must be private regular files.');
+    const value = readFileSync(fd, 'utf8');
+    if (!json) return value;
+    try { return JSON.parse(value); } catch { throw new Error('Invalid private connection record. Restore its backup or reconnect.'); }
+  } finally { closeSync(fd); }
+}
+export function writePrivate(path, value) {
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) || stat.nlink !== 1) throw new Error('Refusing to replace unsafe connection storage.');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try { writeFileSync(fd, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`); }
+  finally { closeSync(fd); }
+  try { renameSync(temp, path); } finally { try { unlinkSync(temp); } catch {} }
+}
+export function connectionDir(home, id) {
+  if (!/^[a-f0-9]{64}\/[\w-]{1,200}$/.test(id ?? '')) throw new Error('Choose a connection ID from status.');
+  ensureHome(home);
+  const [project, agent] = id.split('/');
+  privateDir(join(home, project));
+  const dir = join(home, project, agent);
+  privateDir(dir);
+  return dir;
+}
+export function save(dir, record) { writePrivate(join(dir, 'connection.json'), record); }
+export function load(dir) { return readPrivate(join(dir, 'connection.json'), true); }
+export function binding(record) {
+  return digest([record.schema, record.id, record.service, record.agentId, record.agentName, record.repo, record.folder, record.provider, record.mode, record.copyVersion, record.runtimePolicy, record.bundleHash]);
+}
+export function withLock(dir, action) {
+  const lock = join(dir, 'operation.lock');
+  let fd;
+  try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Another operation holds this connection. After a crash, check that its process has stopped before removing operation.lock.');
+    throw error;
+  }
+  writeFileSync(fd, `${process.pid}\n`); closeSync(fd);
+  return Promise.resolve().then(action).finally(() => unlinkSync(lock));
+}
+export function list(home) {
+  if (!lstatExists(home)) return [];
+  ensureHome(home);
+  const result = [];
+  for (const project of readdirSync(home)) {
+    if (!/^[a-f0-9]{64}$/.test(project)) continue;
+    privateDir(join(home, project));
+    for (const agent of readdirSync(join(home, project))) {
+      if (!/^[\w-]{1,200}$/.test(agent)) continue;
+      const dir = connectionDir(home, `${project}/${agent}`);
+      if (lstatExists(join(dir, 'connection.json'))) result.push(load(dir));
+      else if (lstatExists(join(dir, 'pending-pair.json'))) {
+        const { token, ...pending } = readPrivate(join(dir, 'pending-pair.json'), true);
+        result.push({ ...pending, phase: 'paired', consent: null });
+      }
+    }
+  }
+  return result;
+}
+export function lstatExists(path) { try { lstatSync(path); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } }
+export function cleanEnvironment(input = process.env) {
+  return Object.fromEntries(Object.entries(input).filter(([key]) => !key.startsWith('PILOT_')));
+}

package/src/supervisor.mjs

@@ -0,0 +1,17 @@
+// Separate process keeps ambient PILOT_* overrides out of the canonical supervisor.
+import { join } from 'node:path';
+import { load, binding } from './state.mjs';
+import { COPY_VERSION } from './plan.mjs';
+import { supervise } from '../runtime/launcher.mjs';
+const dir = process.argv[2];
+const record = load(dir);
+if (record.phase !== 'prepared' || record.copyVersion !== COPY_VERSION || record.consent?.binding !== binding(record)) throw new Error('Prepare this connection and confirm its permissions before starting.');
+process.exitCode = await supervise({
+  service: record.service, agentName: record.agentName, repoDir: record.folder, home: join(dir, 'agent-state'),
+  env: {
+    PILOT_PROVIDER: record.provider,
+    PILOT_PERMISSION_MODE: record.mode === 'bypass' ? 'bypassPermissions' : 'acceptEdits',
+    PILOT_MAX_TURNS_PER_HOUR: '0', PILOT_TURN_SECONDS: '0', PILOT_TURN_BUDGET_USD: '0',
+    PILOT_WORK_INTERVAL_MINUTES: '15',
+  },
+});

package/src/system.mjs

@@ -0,0 +1,75 @@
+import { spawnSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { doctor } from './doctor.mjs';
+import { cleanEnvironment, privateDir, readPrivate, writePrivate } from './state.mjs';
+
+export function run(command, args, cwd) {
+  const result = spawnSync(command, args, { cwd, shell: false, encoding: 'utf8', timeout: 120_000, maxBuffer: 1024 * 1024, env: cleanEnvironment(), windowsHide: true });
+  // Do not print raw subprocess errors/output: they can contain credentials or terminal escapes.
+  if (result.error || result.status !== 0) return null;
+  return result.stdout.trim();
+}
+export async function request(service, route, body, token) {
+  let response;
+  try {
+    response = await fetch(`${service}/api/join/${route}`, {
+      method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
+      headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify(body),
+    });
+  } catch { throw new Error(route === 'exchange' ? 'Pairing reply unavailable. The code may have been consumed; generate a fresh code in My agents.' : 'Could not update the readiness check. Retry prepare when the service is available.'); }
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) throw new Error(route === 'exchange' ? 'The setup code is expired, invalid or no longer authorized. Generate a fresh code in My agents.' : 'This connection is no longer authorized. Check membership and reconnect in My agents.');
+    if (response.status === 429) throw new Error('Too many requests. Wait before retrying.');
+    throw new Error('The project service could not complete this request.');
+  }
+  const raw = await response.text();
+  if (raw.length > 16_384) throw new Error('Unexpected project service response.');
+  try { return JSON.parse(raw); } catch { throw new Error('Unexpected project service response.'); }
+}
+export function verifyBundle() {
+  const root = fileURLToPath(new URL('../runtime/', import.meta.url));
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8')); }
+  catch { throw new Error('Packaged runtime missing. Build or reinstall this package before preparing an agent.'); }
+  const names = ['runner.mjs', 'control-v2.mjs', 'runtime.mjs', 'launcher.mjs', 'claude-settings.json', 'AGENT_PROMPT_V2.md', 'providers.mjs'];
+  if (Object.keys(manifest.files ?? {}).sort().join() !== [...names].sort().join()) throw new Error('Invalid packaged runtime manifest.');
+  const files = {};
+  for (const name of names) {
+    const content = readFileSync(join(root, name));
+    if (createHash('sha256').update(content).digest('hex') !== manifest.files[name]) throw new Error('Packaged runtime integrity check failed. Reinstall the package.');
+    files[name] = content;
+  }
+  return { files, fingerprint: createHash('sha256').update(JSON.stringify(manifest.files)).digest('hex') };
+}
+export function installBundle(state) {
+  const bundle = verifyBundle();
+  const kit = join(state, 'kit'); privateDir(kit);
+  for (const [name, content] of Object.entries(bundle.files)) writePrivate(join(kit, name), content.toString('utf8'));
+  return bundle.fingerprint;
+}
+export function verifyInstalled(state) {
+  const bundle = verifyBundle();
+  for (const [name, content] of Object.entries(bundle.files)) {
+    if (readPrivate(join(state, 'kit', name)) !== content.toString('utf8')) throw new Error('Prepared runtime files changed. Run prepare before starting.');
+  }
+  return bundle.fingerprint;
+}
+export function launch(dir, record) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./supervisor.mjs', import.meta.url)), dir], {
+      shell: false, stdio: 'inherit', env: cleanEnvironment(),
+    });
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    let stopping = false;
+    const handlers = Object.fromEntries(signals.map(signal => [signal, () => { stopping = true; child.kill(signal); }]));
+    for (const [signal, handler] of Object.entries(handlers)) process.on(signal, handler);
+    function cleanup() { for (const [signal, handler] of Object.entries(handlers)) process.off(signal, handler); }
+    child.once('error', () => { cleanup(); reject(new Error('Could not launch the foreground supervisor.')); });
+    child.once('exit', (code, signal) => { cleanup(); resolve(stopping && signal ? 0 : code ?? 1); });
+  });
+}
+export const system = { doctor, run, request, installBundle, verifyBundle, verifyInstalled, launch, now: () => new Date().toISOString() };

package/src/terminal.mjs

@@ -0,0 +1,33 @@
+import { createInterface } from 'node:readline/promises';
+export function terminal(input = process.stdin, output = process.stdout) {
+  return {
+    interactive: !!input.isTTY && !!output.isTTY,
+    say: text => output.write(`${text}\n`),
+    async ask(text) {
+      const rl = createInterface({ input, output });
+      try { return (await rl.question(`${text} `)).trim(); } finally { rl.close(); }
+    },
+    async confirm(text) { return (await this.ask(`${text} [yes/no]`)).toLowerCase() === 'yes'; },
+    secret(text) {
+      if (!input.isTTY || !output.isTTY) throw new Error('Enter the setup code in an interactive terminal.');
+      return new Promise((resolve, reject) => {
+        const wasRaw = input.isRaw; let value = '';
+        input.setRawMode(true); input.resume(); output.write(`${text} `);
+        const finish = (error) => {
+          input.off('data', onData); input.off('end', onEnd); input.setRawMode(wasRaw); input.pause(); output.write('\n');
+          if (error) reject(error); else resolve(value);
+        };
+        const onEnd = () => finish(new Error('Code entry cancelled.'));
+        const onData = chunk => {
+          for (const char of chunk.toString('utf8')) {
+            if (char === '\x03' || char === '\x04') { finish(new Error('Code entry cancelled.')); return; }
+            if (char === '\r' || char === '\n') { finish(); return; }
+            if (char === '\x7f' || char === '\b') value = value.slice(0, -1);
+            else if (/[\w-]/.test(char) && value.length < 100) value += char;
+          }
+        };
+        input.on('data', onData); input.once('end', onEnd);
+      });
+    },
+  };
+}