@karma42/agent 0.1.0-beta.10 → 0.1.0-beta.12

package/src/browser-batch.mjs

@@ -1,130 +0,0 @@
-import { randomBytes, randomUUID, createHash } from 'node:crypto';
-import { join, isAbsolute } from 'node:path';
-import { projectIdentity } from './project-identity.mjs';
-import { assertStateOutsideWorkspace, canonicalPath, connectionDir, digest, load, lstatExists, readPrivate, save, writePrivate } from './state.mjs';
-import { sessionHome, sessionId, validateSession } from './session.mjs';
-import { browserApprovalUrl, withBrowserLock } from './browser-pairing.mjs';
-import { system } from './system.mjs';
-
-const hash = value => createHash('sha256').update(value).digest('hex');
-const TOKEN = /^[\w-]{43}$/;
-const uuid = /^[a-f0-9-]{36}$/;
-const validClient = value => typeof value === 'string' && value.trim() && value.length <= 100 && !/[\x00-\x1f\x7f-\x9f]/.test(value);
-const batchPath = dir => join(dir, 'pending-batch.json');
-const agentPath = dir => join(dir, 'pending-browser.json');
-function select(options, home) {
-  if (!validClient(options.clientName) || !Array.isArray(options.agents) || options.agents.length < 1 || options.agents.length > 10) throw new Error('Use a valid client name and one to ten explicitly selected agents for one project.');
-  const agents = options.agents.map(agent => {
-    if (!agent || Object.keys(agent).some(key => !['agent_id', 'agent_name', 'folder'].includes(key)) || !/^[\w-]{1,200}$/.test(agent.agent_id ?? '') || !/^[\w-]{1,64}$/.test(agent.agent_name ?? '') || typeof agent.folder !== 'string' || !isAbsolute(agent.folder)) throw new Error('Use each agent’s exact ID, name and approved absolute working folder.');
-    const folder = canonicalPath(agent.folder); assertStateOutsideWorkspace(home, folder);
-    const plan = projectIdentity({ projectUrl: options.project_url, folder });
-    return { id: sessionId(plan.projectUrl, agent.agent_id), service: plan.projectUrl, agentId: agent.agent_id, agentName: agent.agent_name, folder };
-  }).sort((a,b) => a.agentId.localeCompare(b.agentId));
-  if (new Set(agents.map(agent => agent.agentId)).size !== agents.length) throw new Error('Use distinct agent IDs in a batch.');
-  return agents;
-}
-function validate(receipt, id, home) {
-  if (receipt?.schema !== 'mcp-browser-batch-1' || receipt.id !== id || !uuid.test(receipt.batchId ?? '') || !validClient(receipt.clientName) || !Array.isArray(receipt.agents)) throw new Error('Invalid private batch receipt. Existing connections preserved.');
-  const agents = select({ project_url: receipt.service, clientName: receipt.clientName, agents: receipt.agents.map(agent => ({ agent_id: agent.agentId, agent_name: agent.agentName, folder: agent.folder })) }, home);
-  const expected = sessionId(receipt.service, `batch-${digest([receipt.clientName, agents]).slice(0,32)}`);
-  if (expected !== id || agents.length !== receipt.agents.length) throw new Error('Invalid private batch identity. Existing connections preserved.');
-  for (let index = 0; index < agents.length; index++) {
-    const request = receipt.agents[index];
-    if (JSON.stringify(agents[index]) !== JSON.stringify({ id: request.id, service: request.service, agentId: request.agentId, agentName: request.agentName, folder: request.folder }) || !uuid.test(request.requestId ?? '') || !TOKEN.test(request.candidateToken ?? '') || !TOKEN.test(request.pollingSecret ?? '')) throw new Error('Invalid private batch request. Existing connections preserved.');
-  }
-  if (new Set(receipt.agents.map(agent => agent.requestId)).size !== agents.length) throw new Error('Invalid private batch request IDs.');
-  return receipt;
-}
-export function createBatchBrowserOperations({ home = sessionHome(), io, sys = system } = {}) {
-  home = canonicalPath(home);
-  const locks = (agents, action, index = 0) => index === agents.length ? action() : withBrowserLock(connectionDir(home, agents[index].id), () => locks(agents, action, index + 1));
-  const summary = receipt => ({ id: receipt.id, batchId: receipt.batchId, status: receipt.status, approvalUrl: browserApprovalUrl({ service: receipt.service, requestId: receipt.batchId }), requestCheck: receipt.verificationCode, agents: receipt.agents.map(({ id, agentId, agentName, folder }) => ({ id, agentId, agentName, folder })) });
-  function writeAgent(receipt, agent) {
-    writePrivate(agentPath(connectionDir(home, agent.id)), { schema: 'mcp-browser-pairing-1', ...agent, clientName: receipt.clientName, batchId: receipt.batchId, createdAt: receipt.createdAt, registered: true, expiresAt: receipt.expiresAt, status: agent.status === 'saved' ? 'saved' : receipt.status });
-  }
-  async function register(dir, receipt) {
-    let reply;
-    try { reply = await sys.request(receipt.service, 'pairing-batches/start', { batchId: receipt.batchId, requests: receipt.agents.map(agent => ({ requestId: agent.requestId, agentId: agent.agentId, clientName: receipt.clientName, folder: agent.folder, pollingSecret: agent.pollingSecret, candidateTokenHash: hash(agent.candidateToken) })) }); }
-    catch { throw new Error(`Browser batch reply unavailable. Your private batch is saved. Retry this exact batch with connection ${receipt.id}; do not create another request.`); }
-    if (reply?.batchId !== receipt.batchId || !['pending', 'approved', 'cancelled', 'expired'].includes(reply.status) || !/^[A-F0-9]{8}$/.test(reply.verificationCode ?? '')) throw new Error('Unexpected browser batch reply. Private requests preserved.');
-    receipt = { ...receipt, registered: true, status: reply.status, expiresAt: reply.expiresAt, verificationCode: reply.verificationCode };
-    writePrivate(batchPath(dir), receipt);
-    for (const agent of receipt.agents) writeAgent(receipt, agent);
-    return receipt;
-  }
-  function recordFor(agent) {
-    const dir = connectionDir(home, agent.id), record = validateSession(load(dir), agent.id);
-    if (record.service !== agent.service || record.agentId !== agent.agentId || record.agentName !== agent.agentName || record.folder !== agent.folder || readPrivate(join(dir,'token')).trim() !== agent.candidateToken) throw new Error('Browser batch was superseded by another connection. Use the current exact agent approval; credentials were preserved.');
-    return record;
-  }
-  function currentAgents(receipt) {
-    for (const agent of receipt.agents) {
-      const path = agentPath(connectionDir(home,agent.id));
-      if (!lstatExists(path)) throw new Error('Browser batch agent receipt is missing. Existing connections preserved.');
-      const current = readPrivate(path,true);
-      if (current.batchId !== receipt.batchId || current.requestId !== agent.requestId || current.candidateToken !== agent.candidateToken || current.pollingSecret !== agent.pollingSecret || current.folder !== agent.folder) throw new Error('Browser batch was superseded by another setup. Finish the current exact request; credentials were preserved.');
-    }
-  }
-  return {
-    async connect(options) {
-      const agents = select(options, home), service = agents[0].service;
-      if (options.reconnect !== undefined && typeof options.reconnect !== 'boolean') throw new Error('Use an explicit human-approved reconnect choice.');
-      sys.verifyBundle();
-      const id = sessionId(service, `batch-${digest([options.clientName, agents]).slice(0,32)}`), dir = connectionDir(home, id);
-      return withBrowserLock(dir, () => locks(agents, async () => {
-        let receipt = lstatExists(batchPath(dir)) ? validate(readPrivate(batchPath(dir), true), id, home) : null;
-        if (receipt?.status === 'saved' && !options.reconnect) return { id, batchId: receipt.batchId, status: 'saved', records: receipt.agents.map(recordFor) };
-        if (receipt && ['saved', 'expired', 'cancelled'].includes(receipt.status) && options.reconnect) receipt = null;
-        if (!receipt) {
-          for (const agent of agents) {
-            const path = agentPath(connectionDir(home, agent.id));
-            if (lstatExists(path)) {
-              const pending = readPrivate(path, true);
-              if (!['saved','cancelled','expired'].includes(pending.status)) throw new Error('Another browser setup is pending for an agent in this batch. Finish or cancel that exact request first.');
-            }
-            if (lstatExists(join(connectionDir(home, agent.id), 'connection.json'))) validateSession(load(connectionDir(home, agent.id)), agent.id);
-          }
-          receipt = { schema: 'mcp-browser-batch-1', id, service, batchId: randomUUID(), clientName: options.clientName, createdAt: sys.now(), status: 'pending', registered: false, agents: agents.map(agent => ({ ...agent, requestId: randomUUID(), candidateToken: randomBytes(32).toString('base64url'), pollingSecret: randomBytes(32).toString('base64url') })) };
-          // The full immutable manifest and every candidate are durable before any network call.
-          writePrivate(batchPath(dir), receipt);
-          for (const agent of receipt.agents) writeAgent(receipt, agent);
-        }
-        currentAgents(receipt);
-        if (!receipt.registered) receipt = await register(dir, receipt);
-        return summary(receipt);
-      }));
-    },
-    async prepare({ connection }) {
-      const dir = connectionDir(home, connection);
-      return withBrowserLock(dir, async () => {
-        if (!lstatExists(batchPath(dir))) throw new Error('No browser batch found. Retry the exact batch returned during onboarding.');
-        let receipt = validate(readPrivate(batchPath(dir), true), connection, home);
-        return locks(receipt.agents, async () => {
-          currentAgents(receipt);
-          if (!receipt.registered) receipt = await register(dir, receipt);
-          if (['cancelled','expired'].includes(receipt.status)) return summary(receipt);
-          const records = [];
-          for (const agent of receipt.agents) {
-            if (agent.status === 'saved') { records.push(recordFor(agent)); continue; }
-            let reply;
-            try { reply = await sys.request(receipt.service, `pairings/${agent.requestId}/poll`, {}, agent.pollingSecret); }
-            catch { throw new Error(`Browser batch approval reply unavailable. Retry connection ${connection}; saved credentials and remaining requests are preserved.`); }
-            if (!['pending','approved','cancelled','expired'].includes(reply?.status)) throw new Error('Unexpected browser batch approval reply. Existing connections preserved.');
-            if (reply.status !== 'approved') {
-              if (reply.status !== 'pending') { receipt.status = reply.status; writePrivate(batchPath(dir), receipt); for (const request of receipt.agents) writeAgent(receipt, request); }
-              return { ...summary(receipt), status: reply.status, savedAgents: records.map(record => record.agentId) };
-            }
-            if (reply.agentId !== agent.agentId || reply.agentName !== agent.agentName || !Number.isFinite(reply.approvedAt)) throw new Error('Approved batch identity differs from the requested agent. Existing connection preserved.');
-            const plan = projectIdentity({ projectUrl: receipt.service, repo: reply.repoUrl, folder: agent.folder });
-            const record = validateSession({ schema:'mcp-connection-1', id:agent.id, service:receipt.service, agentId:agent.agentId, agentName:agent.agentName, repo:plan.repo, folder:plan.folder, createdAt:sys.now(), approvedAt:reply.approvedAt }, agent.id);
-            const agentDir = connectionDir(home, agent.id);
-            writePrivate(join(agentDir, 'token'), agent.candidateToken); save(agentDir, record);
-            agent.status = 'saved'; writeAgent(receipt, agent); writePrivate(batchPath(dir), receipt); records.push(record);
-          }
-          receipt.status = 'saved'; writePrivate(batchPath(dir), receipt);
-          return { id: receipt.id, batchId: receipt.batchId, status:'saved', records };
-        });
-      });
-    },
-  };
-}

package/src/browser-pairing.mjs

@@ -1,140 +0,0 @@
-import { randomBytes, randomUUID, createHash } from 'node:crypto';
-import { constants, openSync, closeSync, writeFileSync, lstatSync, unlinkSync } from 'node:fs';
-import { join, isAbsolute } from 'node:path';
-import { projectIdentity } from './project-identity.mjs';
-import { assertStateOutsideWorkspace, canonicalPath, connectionDir, lstatExists, readPrivate, save, writePrivate } from './state.mjs';
-import { sessionHome, sessionId, validateSession } from './session.mjs';
-import { system } from './system.mjs';
-
-const TOKEN = /^[\w-]{43}$/;
-const hash = value => createHash('sha256').update(value).digest('hex');
-// Only locks created by this browser flow can be recovered automatically. Legacy/live bridge locks remain untouched.
-export function withBrowserLock(dir, action, processAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; return true; } }) {
-  const path = join(dir, 'operation.lock'), guard = join(dir, 'browser-recovery.lock');
-  const create = () => {
-    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-    try { writeFileSync(fd, JSON.stringify({ kind: 'karma42-browser-operation-1', pid: process.pid, nonce: randomUUID() })); }
-    finally { closeSync(fd); }
-    return lstatSync(path);
-  };
-  let owned;
-  try { owned = create(); }
-  catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    let guardFd;
-    try { guardFd = openSync(guard, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
-    catch { throw new Error('Another browser setup operation is checking this connection. Retry shortly; no process was stopped.'); }
-    try {
-      writeFileSync(guardFd, `${process.pid}\n`);
-      const before = lstatSync(path), raw = readPrivate(path);
-      let holder;
-      try { holder = JSON.parse(raw); } catch {}
-      if (holder?.kind !== 'karma42-browser-operation-1' || !Number.isSafeInteger(holder.pid) || holder.pid <= 0 || typeof holder.nonce !== 'string' || processAlive(holder.pid)) {
-        throw new Error('Another operation holds this connection. Finish or cancel its setup, or disconnect its active MCP entry, before retrying. No process was stopped.');
-      }
-      // Guard serializes recovery attempts; reread inode/content before touching the confirmed-dead lock.
-      const current = lstatSync(path);
-      if (current.dev !== before.dev || current.ino !== before.ino || readPrivate(path) !== raw) throw new Error('The connection lock changed. Retry setup; no process was stopped.');
-      unlinkSync(path);
-      owned = create();
-    } finally { closeSync(guardFd); unlinkSync(guard); }
-  }
-  return Promise.resolve().then(action).finally(() => {
-    if (!lstatExists(path)) return;
-    const current = lstatSync(path);
-    if (current.dev === owned.dev && current.ino === owned.ino) unlinkSync(path);
-  });
-}
-const receiptPath = dir => join(dir, 'pending-browser.json');
-function validReceipt(receipt, id) {
-  if (receipt?.schema !== 'mcp-browser-pairing-1' || receipt.id !== id || id !== sessionId(receipt.service, receipt.agentId)
-    || !TOKEN.test(receipt.pollingSecret ?? '') || !TOKEN.test(receipt.candidateToken ?? '')
-    || !/^[\w-]{1,200}$/.test(receipt.agentId ?? '') || !/^[a-f0-9-]{36}$/.test(receipt.requestId ?? '')
-    || typeof receipt.clientName !== 'string' || !receipt.clientName.trim() || receipt.clientName.length > 100 || /[\x00-\x1f\x7f-\x9f]/.test(receipt.clientName)) throw new Error('Invalid private browser setup receipt. Review My agents.');
-  const plan = projectIdentity({ projectUrl: receipt.service, folder: receipt.folder });
-  if (plan.projectUrl !== receipt.service || canonicalPath(receipt.folder) !== receipt.folder) throw new Error('Browser setup workspace changed. Review My agents.');
-  return receipt;
-}
-export function browserApprovalUrl(receipt) {
-  const service = new URL(receipt.service);
-  const page = new URL('/viewer/', service.origin);
-  page.searchParams.set('project', service.pathname.split('/')[2]);
-  page.searchParams.set('view', 'agent-connect');
-  page.searchParams.set('request', receipt.requestId);
-  return page.href;
-}
-export function createBrowserOperations({ home = sessionHome(), io, sys = system } = {}) {
-  home = canonicalPath(home);
-  const showPending = receipt => io?.say?.('Browser approval is required. Complete it on Karma42, then check this same connection.');
-  const startBody = receipt => ({ requestId: receipt.requestId, agentId: receipt.agentId, clientName: receipt.clientName, folder: receipt.folder, pollingSecret: receipt.pollingSecret, candidateTokenHash: hash(receipt.candidateToken) });
-  async function start(dir, receipt) {
-    let result;
-    try { result = await sys.request(receipt.service, 'pairings/start', startBody(receipt)); }
-    catch { throw new Error(`Browser setup reply unavailable. Your private request is saved. Retry finish_project_agent_connection with connection ${receipt.id}; do not create another request or replace credentials.`); }
-    if (result?.requestId !== receipt.requestId || !['pending', 'approved', 'cancelled', 'expired'].includes(result.status)) throw new Error('Unexpected browser setup reply. The private request was preserved.');
-    receipt = { ...receipt, registered: true, expiresAt: result.expiresAt };
-    writePrivate(receiptPath(dir), receipt);
-    return receipt;
-  }
-  function saved(record) { return validateSession(record, record.id); }
-  return {
-    async connect(options) {
-      if (!/^[\w-]{1,200}$/.test(options['agent-id'] ?? '')) throw new Error('Browser setup requires the project-specific agent ID from the project instructions.');
-      if (typeof options.clientName !== 'string' || !options.clientName.trim() || options.clientName.length > 100 || /[\x00-\x1f\x7f-\x9f]/.test(options.clientName)) throw new Error('Use a valid MCP client name.');
-      if (typeof options.folder !== 'string' || !isAbsolute(options.folder)) throw new Error('Use the actual absolute working folder approved by your human.');
-      const folder = canonicalPath(options.folder);
-      assertStateOutsideWorkspace(home, folder);
-      const plan = projectIdentity({ projectUrl: options['project-url'], folder });
-      sys.verifyBundle();
-      const id = sessionId(plan.projectUrl, options['agent-id']), dir = connectionDir(home, id);
-      if (lstatExists(join(dir, 'connection.json'))) validateSession(readPrivate(join(dir, 'connection.json'), true), id);
-      return withBrowserLock(dir, async () => {
-        let receipt;
-        if (lstatExists(receiptPath(dir))) {
-          receipt = validReceipt(readPrivate(receiptPath(dir), true), id);
-          if (['cancelled', 'expired'].includes(receipt.status) || (receipt.status === 'saved' && options.reconnect)) receipt = null;
-          else {
-            if (receipt.folder !== folder) throw new Error('A browser setup or saved approval belongs to another workspace. Use an explicit reconnect after the completed setup, or finish/cancel its pending request first.');
-            if (receipt.status === 'saved') return saved(validateSession(readPrivate(join(dir, 'connection.json'), true), id));
-          }
-        }
-        if (!receipt) {
-          receipt = { schema: 'mcp-browser-pairing-1', id, service: plan.projectUrl, agentId: options['agent-id'], clientName: options.clientName, folder,
-            requestId: randomUUID(), candidateToken: randomBytes(32).toString('base64url'), pollingSecret: randomBytes(32).toString('base64url'), createdAt: sys.now(), status: 'pending', registered: false };
-          // Persist the candidate BEFORE contacting the server: lost start/approval replies never lose the credential.
-          writePrivate(receiptPath(dir), receipt);
-        }
-        if (!receipt.registered) receipt = await start(dir, receipt);
-        showPending(receipt); return { id, status: receipt.status, approvalUrl: browserApprovalUrl(receipt), requestCheck: hash(receipt.requestId + ':' + hash(receipt.candidateToken)).slice(0, 8).toUpperCase() };
-      });
-    },
-    async prepare(options) {
-      const id = options.connection, dir = connectionDir(home, id);
-      if (lstatExists(receiptPath(dir))) assertStateOutsideWorkspace(home, validReceipt(readPrivate(receiptPath(dir), true), id).folder);
-      return withBrowserLock(dir, async () => {
-        if (!lstatExists(receiptPath(dir))) throw new Error('No browser setup found. Use connect_project_agent from the project instructions.');
-        let receipt = validReceipt(readPrivate(receiptPath(dir), true), id);
-        if (receipt.status === 'saved') return saved(validateSession(readPrivate(join(dir, 'connection.json'), true), id));
-        if (!receipt.registered) receipt = await start(dir, receipt);
-        let result;
-        try { result = await sys.request(receipt.service, `pairings/${receipt.requestId}/poll`, {}, receipt.pollingSecret); }
-        catch { throw new Error(`Browser approval reply unavailable. Retry finish_project_agent_connection with connection ${id}; your private request and existing connection are preserved.`); }
-        if (!['pending', 'approved', 'cancelled', 'expired'].includes(result?.status)) throw new Error('Unexpected browser approval reply. Existing connection preserved.');
-        if (result.status === 'pending') { showPending(receipt); return { id, status: 'pending' }; }
-        if (result.status !== 'approved') {
-          writePrivate(receiptPath(dir), { ...receipt, status: result.status });
-          io.say(`Browser setup ${result.status}. Existing saved credentials were not changed. Ask your human before starting a fresh connection request.`);
-          return { id, status: result.status };
-        }
-        if (result.agentId !== receipt.agentId || !/^[\w-]{1,64}$/.test(result.agentName ?? '') || !Number.isFinite(result.approvedAt)) throw new Error('Approved identity differs from the requested agent. Existing connection preserved. Review My agents.');
-        assertStateOutsideWorkspace(home, receipt.folder);
-        const plan = projectIdentity({ projectUrl: receipt.service, repo: result.repoUrl, folder: receipt.folder });
-        const record = { schema: 'mcp-connection-1', id, service: receipt.service, agentId: receipt.agentId, agentName: result.agentName, repo: plan.repo, folder: plan.folder, createdAt: sys.now(), approvedAt: result.approvedAt };
-        writePrivate(join(dir, 'token'), receipt.candidateToken); save(dir, record);
-        // Keep the private receipt for restart/recovery; never exchange another credential on retry.
-        writePrivate(receiptPath(dir), { ...receipt, status: 'saved' });
-        return saved(record);
-      });
-    },
-  };
-}