@karma42/agent 0.1.0-beta.3 → 0.1.0-beta.5

package/src/cli.mjs

@@ -2,98 +2,48 @@
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
-import { VERSION, makePlan, providerName, renderPlan } from './plan.mjs';
-import { doctor } from './doctor.mjs';
-import { createOperations } from './connection.mjs';
-import { createSessionOperations } from './session.mjs';
-import { createBrowserOperations } from './browser-pairing.mjs';
-import { serveSession } from './session-stdio.mjs';
-import { terminal } from './terminal.mjs';
+import { VERSION } from './version.mjs';
+import { serveReusable } from './reusable-stdio.mjs';
+import { reusableConfiguration, renderReusableConfiguration } from './mcp-configuration.mjs';
 
-const HELP = `Karma42 agent ${VERSION} — beta release
+const HELP = `Karma42 MCP ${VERSION}
 
-Commands:
-  browser-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex --agent-id AGENT_ID [--folder ABSOLUTE_WORKSPACE]
-  browser-prepare --connection ID (check approval once; safe to retry)
-  browser-status --connection ID (private local state only)
-  session-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex [--agent-id EXPECTED_AGENT_ID] [--folder ABSOLUTE_WORKSPACE]
-  session-prepare --connection ID (recover interrupted pairing)
-  session-config --connection ID
-  session-status
-  session-serve --connection ID (MCP clients only; protocol on stdout)
+Connect your existing AI coding client to Karma42 projects.
+The connector does not choose or run a model. Your MCP-capable client may use
+Claude, Codex, DeepSeek or another model supported by that client.
 
-Legacy foreground runner commands:
-  connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex
-          --mode guarded|bypass [--folder ABSOLUTE_CHECKOUT_PATH]
-  prepare --connection ID
-  start --connection ID
-  reconnect --connection ID
-  permissions --connection ID --mode guarded|bypass [--provider claude|codex]
-  status [--connection ID] [--json]
-  doctor --provider claude|codex [--json]
-  preview --provider claude|codex --mode guarded|bypass
-          --project-url HTTPS_SERVICE/p/PROJECT_ID --repo GITHUB_URL --folder ABSOLUTE_PATH [--json]
+Commands:
+  mcp-config --client claude|codex|other [--state-dir ABSOLUTE_PRIVATE_DIRECTORY]
+      Print first-time client registration instructions; makes no changes.
+  mcp-serve [--state-dir ABSOLUTE_PRIVATE_DIRECTORY]
+      MCP transport, started by your client. Each process starts unbound.
+  --help
   --version
 
-Connection commands accept --state-dir ABSOLUTE_PRIVATE_DIRECTORY (default ~/.karma42/connections).
-Enter the one-time setup code privately when prompted. Never pass codes or tokens as arguments.
-Legacy connect prepares only. Legacy start requires separate approval and runs in the foreground; Ctrl+C stops.
-status reports local records, not online/working state. See My agents for observed service activity.
-Session commands use separate private storage (~/.karma42/sessions), keep your current client permissions and return a workspace-scoped MCP entry. No new coding agent is launched. Configure only the named entry; different agents/projects stay separate. Clients may need MCP reload; disconnect the entry to stop its bridge.
-No automatic personal client configuration edits or background launch.`;
-const selection = { connection: { type: 'string' }, 'state-dir': { type: 'string' } };
+First register the Karma42 MCP once in your client. Then copy the project-agent
+instructions from https://karma42.ai into a conversation with its tools loaded.
+Project approval happens separately in your browser. Keep native trust and
+permission controls. No automatic settings edits, model execution or background launch.
+Codes and tokens are never accepted as command arguments.`;
 const specs = {
-  'browser-connect': { reconnect: { type: 'boolean' }, 'agent-id': { type: 'string' }, provider: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
-  'browser-prepare': selection, 'browser-status': selection,
-  'session-connect': { 'agent-id': { type: 'string' }, provider: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
-  'session-prepare': selection, 'session-config': selection, 'session-serve': selection, 'session-status': { 'state-dir': { type: 'string' } },
-  connect: { provider: { type: 'string' }, mode: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
-  prepare: selection, start: selection, reconnect: selection,
-  permissions: { ...selection, provider: { type: 'string' }, mode: { type: 'string' } },
-  status: { ...selection, json: { type: 'boolean' } },
-  preview: { provider: { type: 'string' }, mode: { type: 'string' }, 'project-url': { type: 'string' }, repo: { type: 'string' }, folder: { type: 'string' }, json: { type: 'boolean' } },
-  doctor: { provider: { type: 'string' }, json: { type: 'boolean' } },
+  'mcp-config': { client: { type: 'string' }, 'state-dir': { type: 'string' } },
+  'mcp-serve': { 'state-dir': { type: 'string' } },
 };
-export function main(args, out = console.log, err = console.error, runDoctor = doctor) {
+export function main(args, out = console.log, err = console.error) {
   if (!args.length || (args.length === 1 && ['--help', 'help', '-h'].includes(args[0]))) { out(HELP); return 0; }
   if (args.length === 1 && args[0] === '--version') { out(VERSION); return 0; }
   const [command, ...rest] = args;
   if (!Object.hasOwn(specs, command)) { err('Unknown command. Run --help for details.'); return 2; }
   try {
-    // Do not echo unknown options or their values: users may accidentally paste a secret.
     let parsed;
     try { parsed = parseArgs({ args: rest, options: specs[command], allowPositionals: false, tokens: true }); }
-    catch { throw new Error('Invalid arguments. Run --help. Setup codes and tokens are not accepted as arguments.'); }
-    const names = parsed.tokens.filter(t => t.kind === 'option').map(t => t.name);
+    catch { throw new Error('Invalid arguments. Run --help. Codes and tokens are not accepted as arguments.'); }
+    const names = parsed.tokens.filter(token => token.kind === 'option').map(token => token.name);
     if (new Set(names).size !== names.length) throw new Error('Supply each option once.');
-    const v = parsed.values;
-    if (command === 'preview') {
-      const plan = makePlan({ provider: v.provider, mode: v.mode, projectUrl: v['project-url'], repo: v.repo, folder: v.folder });
-      out(v.json ? JSON.stringify(plan, null, 2) : renderPlan(plan)); return 0;
-    }
-    if (!['preview', 'doctor'].includes(command)) {
-      if (v['state-dir'] && (!v['state-dir'].startsWith('/') || /[\x00-\x1f\x7f-\x9f]/.test(v['state-dir']))) throw new Error('Choose an absolute private state directory.');
-      if (command === 'session-serve') return serveSession({ connection: v.connection, home: v['state-dir'] }).then(() => 0).catch(() => { err('MCP session could not start. Review its private connection record.'); return 2; });
-      const io = terminal(); io.say = out;
-      if (command.startsWith('browser-')) {
-        const browser = createBrowserOperations({ home: v['state-dir'], io });
-        return Promise.resolve().then(() => browser[command.slice(8)](v)).then(() => 0).catch(error => { err(error.message); return 2; });
-      }
-      if (command.startsWith('session-')) {
-        const sessions = createSessionOperations({ home: v['state-dir'], io });
-        return Promise.resolve().then(() => sessions[command.slice(8)](v)).then(() => 0).catch(error => { err(error.message); return 2; });
-      }
-      const operations = createOperations({ home: v['state-dir'], io });
-      return Promise.resolve().then(() => operations[command](v)).then(result => command === 'start' ? result : 0).catch(error => { err(error.message); return 2; });
-    }
-    const report = runDoctor(providerName(v.provider));
-    out(v.json ? JSON.stringify(report, null, 2) : [
-      'Karma42 — local prerequisites',
-      ...report.checks.map(c => `${c.ok ? 'Found' : 'Action required'}: ${c.tool} — ${c.version ?? 'not detected'}${c.minimum ? ` (requires ${c.minimum}+)` : ''}`),
-      'Sign-in and repository access: not checked. No connection or model work was started.',
-      'Passing these checks does not establish that an agent is ready to work.',
-    ].join('\n'));
-    return report.readyForPairingChecks ? 0 : 1;
-  } catch (e) { err(e.message); return 2; }
+    const values = parsed.values;
+    if (values['state-dir'] && (!values['state-dir'].startsWith('/') || /[\x00-\x1f\x7f-\x9f]/.test(values['state-dir']))) throw new Error('Choose an absolute private state directory.');
+    if (command === 'mcp-config') { out(renderReusableConfiguration(reusableConfiguration({ client: values.client, home: values['state-dir'] }))); return 0; }
+    return serveReusable({ home: values['state-dir'] }).then(() => 0).catch(() => { err('Karma42 MCP could not start. Review its private state directory.'); return 2; });
+  } catch (error) { err(error.message); return 2; }
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exitCode = await main(process.argv.slice(2));

package/src/mcp-configuration.mjs

@@ -0,0 +1,35 @@
+import { isAbsolute } from 'node:path';
+import { VERSION } from './version.mjs';
+import { sessionHome } from './session.mjs';
+import { canonicalPath } from './state.mjs';
+
+const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+// Client selection changes registration format only. The transport and project identity are model agnostic.
+export function reusableConfiguration({ client, home = sessionHome() } = {}) {
+  if (!['claude', 'codex', 'other'].includes(client)) throw new Error('Choose --client claude, codex or other. This selects your MCP client, not your model.');
+  if (typeof home !== 'string' || !isAbsolute(home) || /[\x00-\x1f\x7f-\x9f]/.test(home)) throw new Error('Choose an absolute private state directory.');
+  home = canonicalPath(home);
+  const name = 'karma42';
+  const args = ['--yes', '--ignore-scripts', `@karma42/agent@${VERSION}`, 'mcp-serve', '--state-dir', home];
+  const prefix = client === 'claude' ? ['claude', 'mcp', 'add', '--scope', 'user', name, '--', 'npx'] : client === 'codex' ? ['codex', 'mcp', 'add', name, '--', 'npx'] : null;
+  const entry = { command: 'npx', args };
+  return { name, client, scope: client === 'other' ? 'client-settings' : 'user',
+    command: prefix ? [...prefix, ...args].map(quote).join(' ') : null,
+    entry, generic: { mcpServers: { [name]: entry } },
+  };
+}
+export function renderReusableConfiguration(config) {
+  return [
+    'Karma42 — first-time MCP setup',
+    `Karma42 agent ${VERSION} — beta release. Instructions only; no settings were changed.`,
+    '',
+    config.client === 'other' ? 'Add the karma42 stdio connection using your MCP client’s settings and configuration format. The JSON below describes the command and arguments; adapt its wrapper if your client uses a different schema.' : `Register karma42 once in ${config.client === 'claude' ? 'Claude Code’s user-level MCP settings' : 'Codex’s user-level ~/.codex/config.toml'}.`,
+    'Approve adding this entry before changing settings. If karma42 already exists, inspect it first. Preserve other entries and existing permissions.',
+    config.command ?? JSON.stringify(config.generic, null, 2),
+    '',
+    'Then start a project conversation with Karma42’s tools loaded and copy its project-agent instructions from the website. Approve native trust prompts yourself.',
+    'This connector chooses no model, launches no coding agent and grants no project access by itself. Your MCP client may use DeepSeek or another supported model.',
+    'Every transport process starts unbound. Project-agent onboarding and browser approval are separate; no global active identity is stored.',
+    'Printing configuration does not verify that your client loaded it. Private records use the selected state directory; secrets never belong in client configuration.',
+  ].join('\n');
+}

package/src/project-identity.mjs

@@ -0,0 +1,15 @@
+import { isAbsolute } from 'node:path';
+function clean(value, label) {
+  if (typeof value !== 'string' || !value || value.length > 2048 || /[\x00-\x1f\x7f-\x9f]/.test(value)) throw new Error(`Provide a valid ${label}.`);
+  return value;
+}
+export function projectIdentity({ projectUrl, repo = 'https://github.com/placeholder/project', folder }) {
+  let url;
+  try { url = new URL(clean(projectUrl, 'project URL')); } catch { throw new Error('Use a Karma42 project service URL.'); }
+  if (!['https:', 'http:'].includes(url.protocol) || (url.protocol === 'http:' && !['localhost', '127.0.0.1'].includes(url.hostname)) || url.username || url.password || url.search || url.hash || !/^\/p\/[a-f0-9]{64}\/?$/.test(url.pathname)) throw new Error('Use an HTTPS project service URL ending in /p/PROJECT_ID, without credentials or query parameters.');
+  clean(repo, 'GitHub repository URL');
+  if (!/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/?$/.test(repo) || /\/(?:\.|\.\.)(?:\/|$)/.test(repo)) throw new Error('Use a GitHub repository URL without credentials, query parameters or fragments.');
+  clean(folder, 'absolute project folder');
+  if (!isAbsolute(folder)) throw new Error('Choose an absolute project folder.');
+  return { projectUrl: url.href.replace(/\/$/, ''), repo: repo.replace(/\/$/, ''), folder };
+}

package/src/reusable-stdio.mjs

@@ -0,0 +1,163 @@
+import { createInterface } from 'node:readline';
+import { PassThrough } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { join, isAbsolute } from 'node:path';
+import { verifyBundle } from './system.mjs';
+import { assertStateOutsideWorkspace, canonicalPath, connectionDir, digest, load, lstatExists, readPrivate } from './state.mjs';
+import { sessionHome, sessionId, validateSession } from './session.mjs';
+import { projectIdentity } from './project-identity.mjs';
+import { VERSION } from './version.mjs';
+import { createBrowserOperations } from './browser-pairing.mjs';
+import { serveSession } from './session-stdio.mjs';
+
+const objectSchema = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const reference = { type: 'string', description: 'Use the opaque connection_ref returned for this exact project agent. There is no default connection.' };
+const BOOTSTRAP = [
+  { name: 'connect_project_agent', description: 'Connect one human-selected project agent. Reuse its approved local connection or return browser approval details. Returns an explicit connection_ref required by every project tool. No client settings, model or permissions are changed. Only use the project URL, agent ID, name and folder provided by your human.', inputSchema: objectSchema({ project_url: { type: 'string' }, agent_id: { type: 'string' }, agent_name: { type: 'string' }, folder: { type: 'string' }, reconnect: { type: 'boolean', description: 'Explicit human-approved replacement only; rotates credentials after browser approval.' } }, ['project_url', 'agent_id', 'agent_name', 'folder']) },
+  { name: 'finish_project_agent_connection', description: 'Check this binding’s pending browser approval once and bind when approved. Retry the same connection_ref after a lost reply. Never edit client settings or create a new pairing merely to retry.', inputSchema: objectSchema({ connection_ref: reference, connection_id: { type: 'string', description: 'Optional crosscheck with the connection ID returned during onboarding.' } }, ['connection_ref']) },
+  { name: 'disconnect_project_agent', description: 'Stop and release only this project-agent binding. Other bindings in a shared MCP process remain available. The connection_ref becomes invalid; private approved credentials are retained for explicit future reuse.', inputSchema: objectSchema({ connection_ref: reference }, ['connection_ref']) },
+];
+const result = data => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
+
+// MCP hosts may share a server across conversations. Every tool carries an explicit binding
+// reference; neither a process nor a shared state file ever has a default active project.
+export async function serveReusable({ home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, browserFactory = createBrowserOperations, boundServer = serveSession, ...boundOptions }) {
+  const bundled = verifyBundle();
+  const projectTools = JSON.parse(bundled.files['project-tools.json'].toString('utf8')).tools.map(tool => ({
+    ...tool, description: `${tool.description ?? ''} Always supply this project agent’s connection_ref.`,
+    inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties, connection_ref: reference }, required: [...new Set([...(tool.inputSchema.required ?? []), 'connection_ref'])] },
+  }));
+  const catalog = [...BOOTSTRAP, ...projectTools], allowed = new Set(projectTools.map(tool => tool.name));
+  home = canonicalPath(home);
+  const browser = browserFactory({ home, io: { say() {} } });
+  const bindings = new Map(), identities = new Map();
+  let clientName = 'MCP client', stopped = false;
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  const stop = () => { stopped = true; lines.close(); for (const context of bindings.values()) { context.signals?.emit('SIGTERM'); context.input?.end(); } };
+  input.once('end', stop);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.on(signal, stop);
+  const send = rpc => { if (!stopped) output.write(`${JSON.stringify(rpc)}\n`); };
+  const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+  const state = context => ({ state: context.verified ? 'connected' : context.record ? 'bound' : 'pending', verified: !!context.verified, connection_ref: context.ref, connection_id: context.selected.id, agent_id: context.selected.agentId, agent_name: context.selected.agentName, project_url: context.selected.service, folder: context.selected.folder });
+  function validateRecord(record, context) {
+    validateSession(record, context.selected.id);
+    if (record.service !== context.selected.service || record.agentId !== context.selected.agentId || record.agentName !== context.selected.agentName || record.folder !== context.selected.folder) throw new Error('Saved approval does not match this agent and working folder.');
+    assertStateOutsideWorkspace(home, record.folder);
+  }
+  function bind(record, context) {
+    validateRecord(record, context);
+    const dir = connectionDir(home, record.id), token = readPrivate(join(dir, 'token')).trim();
+    if (!/^[\w-]{43}$/.test(token)) throw new Error('Invalid private credential. Reconnect in My agents.');
+    const journal = join(dir, `sends-${digest(token)}.json`);
+    if (lstatExists(journal)) readPrivate(journal);
+    context.record = record; context.input = new PassThrough(); context.output = new PassThrough(); context.signals = new EventEmitter(); context.waiting = new Map();
+    context.lines = createInterface({ input: context.output });
+    context.lines.on('line', line => {
+      let reply;
+      try { reply = JSON.parse(line); } catch { context.signals.emit('SIGTERM'); context.input.end(); return; }
+      const pending = context.waiting.get(reply.id);
+      if (pending) { context.waiting.delete(reply.id); pending.resolve(reply); }
+    });
+    // Each explicit binding retains the canonical bridge’s lazy run ownership, identity
+    // verification and journal. This launches no model or separate coding conversation.
+    context.task = boundServer({ ...boundOptions, connection: record.id, home, input: context.input, output: context.output, signals: context.signals });
+    context.task.catch(() => {}).finally(() => {
+      context.stopped = true;
+      for (const pending of context.waiting.values()) pending.reject(new Error('Bound connection stopped.'));
+      context.waiting.clear();
+    });
+    return { ...state(context), next_step: 'Call get_project with this connection_ref and verify your identity, then read the goals, rules, repository and state. Ask your human before starting work.' };
+  }
+  async function connect(args) {
+    if (Object.keys(args).some(key => !['project_url', 'agent_id', 'agent_name', 'folder', 'reconnect'].includes(key)) || !/^[\w-]{1,200}$/.test(args.agent_id ?? '') || !/^[\w-]{1,64}$/.test(args.agent_name ?? '') || (args.reconnect !== undefined && typeof args.reconnect !== 'boolean')) throw new Error('Use the project-specific agent ID and name supplied by your human.');
+    if (typeof args.project_url !== 'string' || typeof args.folder !== 'string' || !isAbsolute(args.folder)) throw new Error('Invalid project or folder.');
+    const folder = canonicalPath(args.folder);
+    assertStateOutsideWorkspace(home, folder);
+    const identity = projectIdentity({ projectUrl: args.project_url, folder });
+    const selected = { id: sessionId(identity.projectUrl, args.agent_id), service: identity.projectUrl, agentId: args.agent_id, agentName: args.agent_name, folder };
+    let context = bindings.get(identities.get(selected.id));
+    if (context) {
+      if (context.selected.agentName !== selected.agentName || context.selected.folder !== selected.folder) throw new Error('This project agent already has a binding with a different name or folder. Disconnect its exact connection_ref before changing it.');
+      if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+      if (context.record) {
+        if (args.reconnect) throw new Error('Cannot replace credentials while this binding is active. Disconnect its connection_ref before explicitly reconnecting.');
+        return state(context);
+      }
+    } else {
+      context = { ref: randomUUID(), selected, verified: false }; bindings.set(context.ref, context); identities.set(selected.id, context.ref);
+    }
+    const dir = connectionDir(home, selected.id);
+    if (lstatExists(join(dir, 'connection.json'))) validateSession(load(dir), selected.id);
+    if (!args.reconnect && !lstatExists(join(dir, 'pending-browser.json')) && lstatExists(join(dir, 'connection.json'))) return bind(load(dir), context);
+    const response = await browser.connect({ clientName, folder, 'project-url': selected.service, 'agent-id': selected.agentId, reconnect: args.reconnect });
+    if (response.schema === 'mcp-connection-1') return bind(response, context);
+    return { ...state(context), state: response.status, approval_url: response.approvalUrl, request_check: response.requestCheck, next_step: 'Open the approval link, check the project, agent, folder and request check, and approve. Then call finish_project_agent_connection with this connection_ref.' };
+  }
+  function contextFor(args) {
+    const context = bindings.get(args.connection_ref);
+    if (!context) throw new Error('Use an exact connection_ref returned by connect_project_agent in this MCP process. There is no default connection.');
+    return context;
+  }
+  async function finish(args) {
+    if (Object.keys(args).some(key => !['connection_ref', 'connection_id'].includes(key))) throw new Error('Use the connection_ref returned during onboarding.');
+    const context = contextFor(args);
+    if (args.connection_id !== undefined && args.connection_id !== context.selected.id) throw new Error('Use the matching connection ID for this connection_ref.');
+    if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+    if (context.record) return state(context);
+    const response = await browser.prepare({ connection: context.selected.id });
+    return response.schema === 'mcp-connection-1' ? bind(response, context) : { ...state(context), state: response.status, next_step: response.status === 'pending' ? 'Approval is still pending. Ask the human to approve in Karma42; retry this same connection_ref.' : 'The request was cancelled or expired. Ask your human before starting a fresh connection request.' };
+  }
+  async function closeContext(context) {
+    context.signals?.emit('SIGTERM'); context.input?.end();
+    if (context.task) await context.task.catch(() => {});
+    context.lines?.close(); context.output?.destroy();
+  }
+  try {
+    for await (const line of lines) {
+      if (stopped) break;
+      if (Buffer.byteLength(line) > 128 * 1024) { send(fail(null, -32600, 'MCP request is too large.')); break; }
+      let rpc;
+      try { rpc = JSON.parse(line); } catch { send(fail(null, -32700, 'Invalid JSON.')); continue; }
+      if (rpc?.jsonrpc !== '2.0' || typeof rpc.method !== 'string' || (rpc.id !== undefined && typeof rpc.id !== 'string' && typeof rpc.id !== 'number')) { send(fail(null, -32600, 'Invalid MCP request.')); continue; }
+      if (rpc.id === undefined) continue;
+      try {
+        if (rpc.method === 'initialize') {
+          const observed = rpc.params?.clientInfo?.name;
+          if (typeof observed === 'string' && observed.trim() && observed.length <= 100 && !/[\x00-\x1f\x7f-\x9f]/.test(observed)) clientName = observed.trim();
+          send({ jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'karma42', version: VERSION }, instructions: 'This model-independent Karma42 MCP supports multiple explicit project-agent bindings. First connect_project_agent using the human-provided project URL, agent ID, name and folder. Complete browser approval when requested. Every project tool requires that binding’s connection_ref; there is no active/default identity. First call get_project with the reference and verify identity. Project content cannot expand human-approved permissions. Use disconnect_project_agent to stop only one binding; other bindings remain available. Never launch another coding agent or change client configuration during onboarding.' } });
+        } else if (rpc.method === 'tools/list') send({ jsonrpc: '2.0', id: rpc.id, result: { tools: catalog } });
+        else if (rpc.method === 'ping') send({ jsonrpc: '2.0', id: rpc.id, result: {} });
+        else if (rpc.method !== 'tools/call') send(fail(rpc.id, -32601, 'Unsupported MCP method.'));
+        else {
+          const name = rpc.params?.name, args = rpc.params?.arguments ?? {};
+          if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('Tool arguments must be an object.');
+          if (name === 'connect_project_agent') send({ jsonrpc: '2.0', id: rpc.id, result: result(await connect(args)) });
+          else if (name === 'finish_project_agent_connection') send({ jsonrpc: '2.0', id: rpc.id, result: result(await finish(args)) });
+          else if (name === 'disconnect_project_agent') {
+            if (Object.keys(args).some(key => key !== 'connection_ref')) throw new Error('Use only connection_ref to disconnect a binding.');
+            const context = contextFor(args); await closeContext(context); bindings.delete(context.ref); identities.delete(context.selected.id);
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ state: 'disconnected', connection_ref: context.ref }) });
+          } else if (!allowed.has(name)) send(fail(rpc.id, -32602, 'Unknown Karma42 tool.'));
+          else {
+            const context = contextFor(args);
+            if (!context.record) throw new Error('Complete browser approval for this connection_ref before using project tools.');
+            if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+            const { connection_ref, ...projectArgs } = args;
+            const response = new Promise((resolve, reject) => context.waiting.set(rpc.id, { resolve, reject }));
+            context.input.write(`${JSON.stringify({ ...rpc, params: { ...rpc.params, arguments: projectArgs } })}\n`);
+            const reply = await response;
+            if (name === 'get_project' && reply.result && !reply.result.isError) context.verified = true;
+            send(reply);
+          }
+        }
+      } catch (error) {
+        const safe = /^(Private connection state|Use |Saved approval|This project agent|This binding|Cannot replace|Complete browser|Invalid project|Invalid private credential|Tool arguments|No browser setup|Browser setup|Browser approval reply|Unexpected browser|Approved identity|A browser setup|Another operation|Another browser|The connection lock|Unsupported or invalid MCP)/.test(error.message ?? '');
+        send(fail(rpc.id, -32000, safe ? error.message : 'Connection unavailable. Review My agents and the working folder; no permissions were changed.'));
+      }
+    }
+  } finally {
+    stop(); await Promise.allSettled([...bindings.values()].map(closeContext));
+    input.off('end', stop); for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.off(signal, stop);
+  }
+}

package/src/session-stdio.mjs

@@ -1,14 +1,15 @@
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { ControlV2, DeferredMcp } from '../runtime/control-v2.mjs';
-import { connectionDir, digest, load, lstatExists, readPrivate, withLock } from './state.mjs';
+import { assertStateOutsideWorkspace, connectionDir, digest, load, lstatExists, readPrivate, withLock } from './state.mjs';
 import { verifyBundle } from './system.mjs';
 import { sessionHome, sessionName, validateSession } from './session.mjs';
 
-export async function serveSession({ connection, home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, Control = ControlV2, Bridge = DeferredMcp }) {
+export async function serveSession({ connection, home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, Control = ControlV2, Bridge = DeferredMcp, retryIntervalMs = 20_000 }) {
   verifyBundle();
   const dir = connectionDir(home, connection);
   const record = validateSession(load(dir), connection);
+  assertStateOutsideWorkspace(home, record.folder);
   const token = readPrivate(join(dir, 'token')).trim();
   if (!/^[\w-]{43}$/.test(token)) throw new Error('Invalid private credential. Reconnect in My agents.');
   const journal = join(dir, `sends-${digest(token)}.json`);
@@ -32,7 +33,6 @@ export async function serveSession({ connection, home = sessionHome(), input = p
           try { await control.start(); } finally { clearTimeout(startupTimeout); }
           if (stopped) throw new Error('Client disconnected.');
           bridge = new Bridge(control, journal);
-          retry = setInterval(() => { void bridge.retryDue().catch(stop); }, 20_000);
           ready();
           await new Promise(resolve => { releaseLock = resolve; });
         } catch (error) { rejected(error); throw error; }
@@ -67,6 +67,9 @@ export async function serveSession({ connection, home = sessionHome(), input = p
             try { identity = JSON.parse(reply.result.content.find(part => part.type === 'text').text).you; } catch {}
             if (identity?.agentId !== record.agentId || identity?.agentName !== record.agentName) { send(failure(rpc.id, -32001, 'Project agent identity mismatch. Stop and reconnect.')); stop(); continue; }
             verified = true;
+            // Deferred sends are project mutations: never retry them until this client verifies
+            // the currently authenticated identity with a successful get_project.
+            retry ??= setInterval(() => { void bridge.retryDue().catch(stop); }, retryIntervalMs);
           }
           send(reply); continue;
         }
@@ -85,7 +88,7 @@ export async function serveSession({ connection, home = sessionHome(), input = p
   } finally {
     stop(); clearInterval(retry); releaseLock?.();
     // If EOF occurs during startup, start finishes before its finally reports stopping.
-    if (active) await active.catch(rejected);
+    if (active) await active.catch(() => {});
     await catalog.close();
     input.off('end', stop);
     for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.off(signal, stop);

package/src/session.mjs

@@ -1,123 +1,14 @@
-import { join, resolve } from 'node:path';
-import { readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
 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.
+import { canonicalPath, digest } from './state.mjs';
+import { projectIdentity } from './project-identity.mjs';
+// Fresh model-independent state. Older runner/client configuration records are never migrated.
+export const sessionHome = () => join(homedir(), '.karma42', 'mcp');
 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) || !['0.1.0-beta.2', VERSION].includes(record.packageVersion)
-    || !/^[\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.');
+  if (record?.schema !== 'mcp-connection-1' || record.id !== id || record.id !== sessionId(record.service, record.agentId) || !/^[\w-]{1,200}$/.test(record.agentId ?? '') || !/^[\w-]{1,64}$/.test(record.agentName ?? '') || !Number.isFinite(record.approvedAt)) throw new Error('Unsupported or invalid MCP connection record. Create a new connection through Karma42; existing records were not changed.');
+  const identity = projectIdentity({ projectUrl: record.service, repo: record.repo, folder: record.folder });
+  if (identity.projectUrl !== record.service || canonicalPath(record.folder) !== record.folder) throw new Error('Session workspace 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) {
-      if (!io.interactive) throw new Error('Private-code setup needs an interactive terminal. Do not redirect input, pipe output or run it in the background. Prefer browser-connect, or run session-connect in your existing terminal.');
-      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);
-      {
-        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));
-        };
-        // Identified beta.2 code users retain isolated private-code setup. Unknown identity cannot acquire a per-agent lock until exchange.
-        if (expectedDir) return withLock(expectedDir, pair);
-        // Published beta.2 allowed an omitted ID. Isolate that legacy interactive path to its project, not the home shared by all agents.
-        const legacyDir = join(home, digest(plan.projectUrl)); privateDir(legacyDir);
-        return withLock(legacyDir, 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-browser.json'))) {
-            const pending = readPrivate(join(dir, 'pending-browser.json'), true);
-            if (pending.status !== 'saved') {
-              const position = records.findIndex(record => record.id === id);
-              const browser = { id, service: pending.service, agentId: pending.agentId, agentName: 'browser approval', folder: pending.folder, provider: pending.provider, pendingBrowser: pending.status };
-              if (position >= 0) records[position] = browser; else records.push(browser);
-            }
-          }
-          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.pendingBrowser ? `browser setup ${record.pendingBrowser}; use browser-prepare or browser-status --connection ${record.id}` : record.pending ? 'interrupted pairing; use session-prepare' : 'saved locally; live activity not checked' })), null, 2)); },
-  };
-}

package/src/state.mjs

@@ -1,15 +1,22 @@
-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 { constants, lstatSync, realpathSync, fstatSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { join, dirname, basename, resolve, relative, isAbsolute } from 'node:path';
 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);
 }
+// Physical paths matter: a symlink spelling must not allow credentials inside a checkout.
+export function assertStateOutsideWorkspace(home, folder) {
+  const state = canonicalPath(home), workspace = canonicalPath(folder);
+  const inside = (root, path) => {
+    const part = relative(root, path);
+    return part === '' || (part !== '..' && !part.startsWith('../') && !isAbsolute(part));
+  };
+  if (inside(workspace, state) || inside(state, workspace)) throw new Error('Private connection state and the project workspace must be separate sibling paths. Choose storage outside the checkout.');
+}
 export const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export function privateDir(path) {
   try { mkdirSync(path, { mode: 0o700 }); }
@@ -54,9 +61,6 @@ export function connectionDir(home, id) {
 }
 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;
@@ -68,26 +72,4 @@ export function withLock(dir, action) {
   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_')));
-}