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

package/src/reusable-stdio.mjs

@@ -8,31 +8,26 @@ 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 { createBatchBrowserOperations } from './browser-batch.mjs';
+import { VERSION, GUIDE_REVISION } from './version.mjs';
 import { serveSession } from './session-stdio.mjs';
 import { createProjectWorker } from './worker-runtime.mjs';
 import { workerRecoveryStatus, cancelWorkerRecovery } from './worker-recovery.mjs';
-import { createOwnerClient, OWNER_TOOLS } from './owner-client.mjs';
+import { createOwnerClient, OWNER_TOOLS, startQuestion } from './owner-client.mjs';
 import { createDiscovery, DISCOVERY_TOOLS } from './discovery.mjs';
 
 const objectSchema = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
-const approvalWaitSchema = { type: 'integer', minimum: 0, maximum: 60, default: 0, description: 'Wait without a model for browser approval, up to this many seconds. Reuse the same reference if still pending; no typed done is required.' };
 const reference = { type: 'string', description: 'Use the opaque connection_ref returned for this exact project agent. There is no default connection.' };
 const GUIDE = readFileSync(new URL('../skills/karma42/SKILL.md', import.meta.url), 'utf8');
 const BOOTSTRAP = [
   { name:'get_karma42_guide', description:'Read the Karma42 owner/team orchestration skill before managing projects or assembling agents. No sign-in or connection needed.', annotations:{readOnlyHint:true}, inputSchema:objectSchema({},[]) },
-  { 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. Use the human-selected project/folder and exact agent IDs/names provided by the human or returned by the owner team tools.', 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 browser approval and bind when approved. Optional wait_seconds waits within a bounded budget without blocking other agents. 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, wait_seconds: approvalWaitSchema, connection_id: { type: 'string', description: 'Optional crosscheck with the connection ID returned during onboarding.' } }, ['connection_ref']) },
+  { name: 'connect_project_agent', description: 'Connect one existing project agent of your human’s by its exact ID and name. Reuses its saved local connection, or connects it through this computer’s one-time approval; there is no browser step per agent. A computer that is not approved yet is approved once with connect_owner_account. Returns an explicit connection_ref required by every project tool. No client settings, model or permissions are changed. To create a new agent use add_project_agent.', inputSchema: objectSchema({ project_url: { type: 'string' }, agent_id: { type: 'string' }, agent_name: { type: 'string' }, folder: { type: 'string' } }, ['project_url', 'agent_id', 'agent_name', 'folder']) },
   { 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 BATCH_TOOLS = [
-  { name: 'connect_project_agents', description: 'Connect an exact batch of one to ten of your own project agents. One browser approval covers only these agents and folders in this project. Never approve another participant’s agents. Each credential and connection_ref remains independent; this does not start workers or grant work authorization.', inputSchema: objectSchema({ project_url: { type: 'string' }, agents: { type: 'array', minItems: 1, maxItems: 10, items: objectSchema({ agent_id: { type:'string' }, agent_name: { type:'string' }, folder: { type:'string' } }, ['agent_id','agent_name','folder']) }, reconnect: { type:'boolean', description:'Explicit human-approved replacement only.' } }, ['project_url','agents']) },
-  { name: 'finish_project_agents_connection', description: 'Check the exact batch_ref returned during onboarding and bind each approved agent separately. Optional wait_seconds waits within a bounded budget without blocking other agents. Retry this same batch after a lost reply. No worker is started.', inputSchema: objectSchema({ batch_ref: { type:'string' }, wait_seconds: approvalWaitSchema }, ['batch_ref']) },
+  { name: 'connect_project_agents', description: 'Connect an exact batch of one to ten of your human’s own existing project agents through this computer’s one-time approval; there is no browser step. Each credential and connection_ref remains independent; this does not start workers or grant work authorization.', inputSchema: objectSchema({ project_url: { type: 'string' }, agents: { type: 'array', minItems: 1, maxItems: 10, items: objectSchema({ agent_id: { type:'string' }, agent_name: { type:'string' }, folder: { type:'string' } }, ['agent_id','agent_name','folder']) } }, ['project_url','agents']) },
 ];
 const WORKER_TOOLS = [
-  { name: 'start_project_worker', description: 'After your human explicitly approves this work, start one supervised worker for this verified project agent. Uses the existing coordination connection and guarded native permissions. Return promptly; the supervisor can steer, pause or stop through worker controls. Requires a separate approved Git checkout/worktree matching the project repository, distinct from the connection/main-chat folder. Agents may self-organize within the shared approved mission; fixed roles are optional.', inputSchema: objectSchema({ connection_ref: reference, recovery_ref: { type: 'string', format: 'uuid', description: 'Only after explicit approval to recover the exact saved mission from get_project_worker. Repeat its saved client/model/scope/folder and omit minutes. Preserves the original deadline; never takes over a surviving supervisor or native process.' }, client: { type: 'string', enum: ['claude', 'codex'] }, model: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,149}$', description: 'Optional human-approved model ID or client alias. Omit for the client default; verify the actual model through worker status.' }, minutes: { type: 'integer', minimum: 15, maximum: 240, multipleOf: 15, default: 60 }, scope: { type: 'string', minLength: 1, maxLength: 4000 }, folder: { type: 'string' }, approved: { type: 'boolean', const: true, description: 'Set true only after the human explicitly approves this worker, duration, workspace and work scope. Connection approval alone is insufficient.' } }, ['connection_ref', 'client', 'scope', 'folder', 'approved']) },
+  { name: 'start_project_worker', description: 'After your human approves this work, start one supervised worker for this verified project agent. Uses the existing coordination connection and guarded native permissions. Return promptly; the supervisor can steer, pause or stop through worker controls. An agent added with add_project_agent works in its own folder: leave folder out, after cloning the project repository there. Any other agent requires a separate approved Git checkout/worktree matching the project repository, distinct from the connection/main-chat folder. Agents may self-organize within the shared approved mission; fixed roles are optional.', inputSchema: objectSchema({ connection_ref: reference, recovery_ref: { type: 'string', format: 'uuid', description: 'Only after explicit approval to recover the exact saved mission from get_project_worker. Repeat its saved client/model/scope/folder and omit minutes. Preserves the original deadline; never takes over a surviving supervisor or native process.' }, client: { type: 'string', enum: ['claude', 'codex'] }, model: { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,149}$', description: 'Optional human-approved model ID or client alias. Omit for the client default; verify the actual model through worker status.' }, minutes: { type: 'integer', minimum: 15, maximum: 240, multipleOf: 15, default: 60 }, scope: { type: 'string', minLength: 1, maxLength: 4000 }, folder: { type: 'string' }, approved: { type: 'boolean', const: true, description: 'Set true only after the human explicitly approves starting this worker under its limits. Adding or connecting an agent alone is insufficient.' } }, ['connection_ref', 'client', 'scope', 'approved']) },
   { name: 'get_project_worker', description: 'Read this binding’s actual supervised worker status or saved mission recovery details after its supervisor ended. Reports model, last-turn usage, permission observations, original deadline, requested/applied steering and safe failure stage/code. Saved records are not live process observations. This does not restart work or extend the deadline.', inputSchema: objectSchema({ connection_ref: reference }, ['connection_ref']) },
   { name: 'control_project_worker', description: 'Steer, pause, resume or stop only this binding’s supervised worker. Steering waits for the next natural model turn without interrupting active work; check requested/applied sequence rather than assuming delivery. Explicit pause/stop still interrupts execution. Resuming preserves the original deadline. Instruction is required only for steer.', inputSchema: objectSchema({ connection_ref: reference, action: { type: 'string', enum: ['pause', 'resume', 'stop', 'steer'] }, instruction: { type: 'string', minLength: 1, maxLength: 2000 } }, ['connection_ref', 'action']) },
 ];
@@ -41,7 +36,7 @@ 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, batchBrowserFactory = createBatchBrowserOperations, boundServer = serveSession, workerFactory, discoveryOptions, ownerFactory = createOwnerClient, ownerOptions, approvalWait = ms => new Promise(resolve => setTimeout(resolve, ms)), ...boundOptions }) {
+export async function serveReusable({ home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, boundServer = serveSession, workerFactory, discoveryOptions, ownerFactory = createOwnerClient, ownerOptions, approvalWait = ms => new Promise(resolve => setTimeout(resolve, ms)), openApproval = () => false, ...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.`,
@@ -53,10 +48,9 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
   let ownerConnected = false;
   const catalog = [...OWNER_TOOLS, ...DISCOVERY_TOOLS, localList, ...BOOTSTRAP, ...BATCH_TOOLS, ...WORKER_TOOLS, ...projectTools], allowed = new Set(projectTools.map(tool => tool.name));
   home = canonicalPath(home);
-  const browser = browserFactory({ home, io: { say() {} } });
-  const batchBrowser = batchBrowserFactory({ home, io: { say() {} } });
-  const bindings = new Map(), identities = new Map(), batches = new Map();
+  const bindings = new Map(), identities = new Map();
   const approvalTasks = new Map();
+  let openedOwnerApproval = null;
   let clientName = 'MCP client', stopped = false;
   const lines = createInterface({ input, crlfDelay: Infinity });
   const stop = () => { stopped = true; lines.close(); for (const context of bindings.values()) void closeContext(context).catch(() => {}); };
@@ -64,7 +58,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
   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.stopped || context.stopping || context.closing ? 'stopped' : context.verified ? 'connected' : context.record ? 'bound' : context.observedState ?? 'pending', verified: !!context.verified && !context.stopped && !context.stopping && !context.closing, 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 });
+  const state = context => ({ state: context.stopped || context.stopping || context.closing ? 'stopped' : context.verified ? 'connected' : context.record ? 'bound' : context.observedState ?? 'pending', verified: !!context.verified && !context.stopped && !context.stopping && !context.closing, 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, guide_revision: GUIDE_REVISION });
   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.');
@@ -106,10 +100,10 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
       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.' };
+    return { ...state(context), next_step: 'Call get_project with this connection_ref and verify your identity, then read the goals, rules, repository and state. Follow the guide for when work may start.' };
   }
   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 (Object.keys(args).some(key => !['project_url', 'agent_id', 'agent_name', 'folder'].includes(key)) || !/^[\w-]{1,200}$/.test(args.agent_id ?? '') || !/^[\w-]{1,64}$/.test(args.agent_name ?? '')) throw new Error('Use the project-specific agent ID and name supplied by your human. A connected agent keeps its connection; there is no replacing it.');
     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);
@@ -124,24 +118,31 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     if (context) {
       assertLive(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.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);
-      }
+      if (context.record) return state(context);
     } else {
       context = { ref: randomUUID(), selected, verified: false }; bindings.set(context.ref, context); identities.set(selected.id, context.ref);
     }
+    try { return bind(await savedOrApproved(selected, context), context); }
+    catch (error) { forget(context); throw error; }
+  }
+  // A connect that did not complete leaves nothing behind: its reference was never returned to the caller.
+  function forget(context) {
+    if (context.record || bindings.get(context.ref) !== context) return;
+    bindings.delete(context.ref); identities.delete(context.selected.id);
+  }
+  // The one validation: a connection this computer already saved, or this computer's approval. The approval
+  // connects the exact existing agent the caller named; without it the owner client says how to approve the computer.
+  async function savedOrApproved(selected, context) {
     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 (lstatExists(join(dir, 'connection.json'))) return validateSession(load(dir), selected.id);
+    const url = new URL(selected.service);
+    if (url.origin !== owner.origin) throw new Error('Use a project on the Karma42 site this computer is set up for.');
+    const added = await owner.addAgent({ project_id: url.pathname.split('/')[2], agent_name: selected.agentName, folder: selected.folder }, clientName, { exact: selected.agentId, own: false });
     assertLive(context);
-    if (response.schema === 'mcp-connection-1') return bind(response, context);
-    context.observedState = response.status;
-    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. Wait for browser approval with finish_project_agent_connection, this connection_ref and wait_seconds:60; no typed done is required.' };
+    return added.record;
   }
   async function connectBatch(args) {
-    if (Object.keys(args).some(key => !['project_url','agents','reconnect'].includes(key)) || !Array.isArray(args.agents) || args.agents.length < 1 || args.agents.length > 10 || (args.reconnect !== undefined && typeof args.reconnect !== 'boolean')) throw new Error('Use one to ten explicitly selected agents for one project.');
+    if (Object.keys(args).some(key => !['project_url','agents'].includes(key)) || !Array.isArray(args.agents) || args.agents.length < 1 || args.agents.length > 10) throw new Error('Use one to ten explicitly selected agents for one project.');
     const selected = args.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);
@@ -159,80 +160,24 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
       const context = contexts[index]; if (!context) continue;
       assertLive(context);
       if (context.selected.agentName !== selected[index].agentName || context.selected.folder !== selected[index].folder) throw new Error('This project agent already has a different name or folder. Disconnect its exact connection_ref first.');
-      if (context.record && args.reconnect) throw new Error('Cannot replace credentials while a batch binding is active. Disconnect its exact connection_ref first.');
     }
-    if (contexts.every(context => context?.record)) return { state:'bound', agents:contexts.map(state), next_step:'Verify each agent with get_project using its separate connection_ref. Work requires separate approval.' };
-    if (contexts.some(context => context?.record)) throw new Error('Cannot replace credentials for active agents in a batch. Select only unbound agents or disconnect their exact connection_ref first.');
-    const response = await batchBrowser.connect({ ...args, clientName });
-    if (stopped) throw new Error('The MCP session closed before the batch could be bound.');
-    for (const context of contexts) if (context) assertLive(context);
-    const key = response.id;
-    let batch = [...batches.values()].find(candidate => candidate.id === key);
-    if (!batch) { batch = { ref:randomUUID(), id:key, contexts:selected.map((agent,index) => {
+    const batch = selected.map((agent,index) => {
       const context = contexts[index] ?? { ref:randomUUID(), selected:agent, verified:false };
       bindings.set(context.ref,context); identities.set(agent.id,context.ref); return context;
-    }) }; batches.set(batch.ref,batch); }
-    return batchResponse(response,batch);
-  }
-  function batchResponse(response,batch) {
-    for (const context of batch.contexts) assertLive(context);
-    if (response.status === 'saved') {
-      // Validate every record before binding any, so a mismatch cannot select another agent.
-      if (response.records.length !== batch.contexts.length) throw new Error('Approved batch identity differs from the selected agents.');
-      for (const context of batch.contexts) validateRecord(response.records.find(record => record.id === context.selected.id),context);
-      for (const context of batch.contexts) if (!context.record) bind(response.records.find(record => record.id === context.selected.id),context);
-      return { state:'bound', batch_ref:batch.ref, agents:batch.contexts.map(state), next_step:'Verify each agent with get_project using its separate connection_ref. Work requires separate approval.' };
-    }
-    for (const context of batch.contexts) context.observedState = response.status;
-    return { state:response.status, batch_ref:batch.ref, approval_url:response.approvalUrl, request_check:response.requestCheck, agents:batch.contexts.map(state), next_step:'Approve this exact batch of your own agents in Karma42, wait for the result with finish_project_agents_connection, this batch_ref and wait_seconds:60; no typed done is required. Connection approval does not start work.' };
-  }
-  function queueApprovalWait(rpc, args, once) {
-    const key = `${once === finishBatch ? 'batch' : 'agent'}:${args.batch_ref ?? args.connection_ref}`;
-    if (approvalTasks.has(key)) throw new Error('Use the existing approval wait for this same reference; it is still running.');
-    if (approvalTasks.size >= 20) throw new Error('Approval wait limit reached. Finish or cancel a pending request first.');
-    // Waiting for a browser must not block steering or stopping another bound agent.
-    const task = waitForApproval(args, once).then(value => send({ jsonrpc:'2.0', id:rpc.id, result:result(value) }), error => {
-      const safe = /^(Use |Approval wait|This binding|This project agent|Browser setup|Another operation|Another browser)/.test(error.message ?? '');
-      send(fail(rpc.id, -32000, safe ? error.message : 'Connection unavailable. Review the original request; no permissions were changed.'));
-    }).finally(() => approvalTasks.delete(key));
-    approvalTasks.set(key, task);
-    return task;
-  }
-  async function waitForApproval(args, once) {
-    const { wait_seconds = 0, ...selection } = args;
-    if (!Number.isInteger(wait_seconds) || wait_seconds < 0 || wait_seconds > 60) throw new Error('Approval wait must be between 0 and 60 seconds.');
-    let remaining = wait_seconds * 1000;
-    while (true) {
-      const response = await once(selection);
-      if (response.state !== 'pending' || remaining <= 0 || stopped) return response;
-      const delay = Math.min(5000, remaining);
-      await approvalWait(delay); remaining -= delay;
-      if (stopped) return response;
+    });
+    // Each agent is connected and bound on its own; one that fails leaves the others bound, and
+    // repeating the same call connects the rest.
+    for (const context of batch) {
+      assertLive(context);
+      if (!context.record) try { bind(await savedOrApproved(context.selected, context), context); } catch (error) { for (const other of batch) forget(other); throw error; }
     }
-  }
-  async function finishBatch(args) {
-    if (Object.keys(args).some(key => key !== 'batch_ref') || !batches.has(args.batch_ref)) throw new Error('Use the exact batch_ref returned during onboarding in this MCP process.');
-    const batch = batches.get(args.batch_ref);
-    for (const context of batch.contexts) assertLive(context);
-    if (batch.contexts.every(context => context.record)) return { state:'bound', batch_ref:batch.ref, agents:batch.contexts.map(state) };
-    return batchResponse(await batchBrowser.prepare({ connection:batch.id }),batch);
+    return { state:'bound', agents:batch.map(state), next_step:'Verify each agent with get_project using its separate connection_ref. Work requires separate approval.' };
   }
   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.');
-    assertLive(context);
-    if (context.record) return state(context);
-    const response = await browser.prepare({ connection: context.selected.id });
-    assertLive(context);
-    context.observedState = response.status;
-    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.closing ??= (async () => {
       // Stop the model process before aborting/releasing its shared coordination run.
@@ -260,7 +205,8 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     const current = context.worker?.status();
     if (current && (current.state !== 'idle' || current.mission_ref)) return current;
     const recovery = context.record ? workerRecoveryStatus(connectionDir(home, context.record.id), context.record) : null;
-    return recovery ? { state: 'recovery_required', active: false, recovery } : current ?? { state: 'not_started', active: false };
+    const status = recovery ? { state: 'recovery_required', active: false, recovery } : current ?? { state: 'not_started', active: false };
+    return { ...status, report_delivery: context.ready?.control?.reportDeliveryStatus?.() ?? null };
   }
   async function startWorker(args) {
     if (Object.keys(args).some(key => !['connection_ref', 'client', 'model', 'minutes', 'scope', 'folder', 'approved', 'recovery_ref'].includes(key))) throw new Error('Use only the documented worker options.');
@@ -268,8 +214,9 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     if (args.approved !== true) throw new Error('Worker start requires your human’s explicit approval for this worker, duration, folder and work scope. Connection approval is insufficient.');
     if (!['claude', 'codex'].includes(args.client) || !Number.isInteger(minutes) || minutes < 15 || minutes > 240 || minutes % 15 !== 0) throw new Error('Choose a supported worker client and 15–240 minutes in 15-minute increments.');
     if (typeof args.scope !== 'string' || !args.scope.trim() || args.scope.length > 4000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/.test(args.scope)) throw new Error('Use a clear, human-approved work scope of at most 4000 characters.');
-    if (typeof args.folder !== 'string' || !isAbsolute(args.folder)) throw new Error('Use the approved absolute worker checkout folder.');
-    const folder = canonicalPath(args.folder); assertStateOutsideWorkspace(home, folder);
+    const ownFolder = context.record.ownFolder === true ? context.record.folder : undefined;
+    if (args.folder === undefined ? !ownFolder : typeof args.folder !== 'string' || !isAbsolute(args.folder)) throw new Error('Use the approved absolute worker checkout folder.');
+    const folder = canonicalPath(args.folder ?? ownFolder); assertStateOutsideWorkspace(home, folder);
     for (const other of bindings.values()) {
       if (other === context || other.stopped || other.closing) continue;
       const candidates = [other.selected.folder, ...(workerOwnsMutations(other) && other.workerFolder ? [other.workerFolder] : [])];
@@ -342,13 +289,43 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
           if (name === 'connect_owner_account') {
             if (Object.keys(args).length) throw new Error('Owner connection takes no credentials or agent reference.');
             const account = await owner.connect(clientName); ownerConnected = true;
-            send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
+            // Open the approval page once per request in this process, as for an agent's approval; the link is still returned.
+            let opened = false;
+            if (account.status === 'pending' && openedOwnerApproval !== account.approval_url) {
+              try { opened = !!openApproval(account.approval_url); } catch { opened = false; }
+              if (opened) openedOwnerApproval = account.approval_url;
+            }
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, ...(account.status === 'pending' ? { browser_opened: opened, next_step: opened ? 'The approval page is open in their browser. Tell the human so in message text, with a labeled link to approval_url and the request check, then call finish_owner_account_connection with wait_seconds 60 in the same turn.' : 'No browser could be opened. Make a labeled link to approval_url and the request check your whole reply and end your turn, so the human sees it; call finish_owner_account_connection when they say they approved.' } : {}), owner_ref: ownerReference, guide_revision: GUIDE_REVISION }) });
           } else {
             if (!ownerConnected || args.owner_ref !== ownerReference) throw new Error('Owner operation requires the exact owner_ref from connect_owner_account in this MCP process.');
             const { owner_ref, ...fields } = args;
-            const account = name === 'finish_owner_account_connection' ? (Object.keys(fields).length ? (() => { throw new Error('Owner finish takes only owner_ref.'); })() : await owner.finish()) : await owner.operation(name, fields);
+            if (name === 'add_project_agent') {
+              // The saved connection binds exactly as an approved one does; its reference is then verified with get_project.
+              const added = await owner.addAgent(fields, clientName);
+              const bound = await connect({ project_url: added.record.service, agent_id: added.record.agentId, agent_name: added.record.agentName, folder: added.record.folder });
+              send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...bound, created: added.created, project_name: added.project_name, project_id: added.record.service.split('/p/')[1], work_settings: added.settings, folder: added.record.folder, repository: added.repo, start_question: startQuestion(added.record.agentName, added.project_name, added.settings), next_step: 'Call get_project with this connection_ref and check you.agentName. If project.started is true and project.paused is false, ask start_question with your question tool (AskUserQuestion in Claude Code), using exactly its question and its three options; use a numbered list only when your client has no question tool, and never ask it as a plain sentence. If the project has not started or is paused, ask nothing: say in one line what it is waiting for. Clone the repository into folder only after the human answers Yes. The guide section “Ask once before starting” says what each answer means.', owner_ref: ownerReference }) });
+            } else if (name === 'finish_owner_account_connection') {
+              const { wait_seconds = 0, ...extra } = fields;
+              if (Object.keys(extra).length) throw new Error('Owner finish takes only owner_ref and wait_seconds.');
+              if (!Number.isInteger(wait_seconds) || wait_seconds < 0 || wait_seconds > 60) throw new Error('Use an approval wait between 0 and 60 seconds.');
+              if (approvalTasks.has('owner')) throw new Error('Use the existing approval wait for this same reference; it is still running.');
+              // Waiting for the browser must not block steering or stopping a bound agent.
+              const task = (async () => {
+                for (let remaining = wait_seconds * 1000; ; ) {
+                  const account = await owner.finish();
+                  if (account.status !== 'pending' || remaining <= 0 || stopped) return account;
+                  const delay = Math.min(5000, remaining); await approvalWait(delay); remaining -= delay;
+                }
+              })().then(account => send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference, guide_revision: GUIDE_REVISION }) }),
+                error => send(fail(rpc.id, -32000, /^Owner /.test(error.message ?? '') ? error.message : 'Connection unavailable. Review the original request; no permissions were changed.')))
+                .finally(() => approvalTasks.delete('owner'));
+              approvalTasks.set('owner', task);
+              await (wait_seconds === 0 ? task : Promise.resolve());
+            } else {
+            const account = await owner.operation(name, fields);
             if (name === 'disconnect_owner_account') ownerConnected = false;
-            send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference, guide_revision: GUIDE_REVISION }) });
+            }
           }
         }
         else if (DISCOVERY_TOOLS.some(tool => tool.name === name)) send({ jsonrpc: '2.0', id: rpc.id, result: result(await discovery.call(name, args)) });
@@ -361,9 +338,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
           send({ jsonrpc: '2.0', id: rpc.id, result: result({ scope: 'this_mcp_process', agents: page.map(context => ({ ...state(context), worker: workerStatus(context) })), next: entries.length > offset + 20 ? page.at(-1).ref : null, active_workers: entries.filter(workerOwnsMutations).length, presence: 'local observation; not service online state' }) });
         }
         else if (name === 'connect_project_agents') send({ jsonrpc:'2.0', id:rpc.id, result:result(await connectBatch(args)) });
-        else if (name === 'finish_project_agents_connection') await queueApprovalWait(rpc, args, finishBatch);
         else if (name === 'connect_project_agent') send({ jsonrpc: '2.0', id: rpc.id, result: result(await connect(args)) });
-        else if (name === 'finish_project_agent_connection') await queueApprovalWait(rpc, args, finish);
         else if (name === 'start_project_worker') send({ jsonrpc: '2.0', id: rpc.id, result: result(await startWorker(args)) });
         else if (name === 'get_project_worker') {
           if (Object.keys(args).some(key => key !== 'connection_ref')) throw new Error('Use only connection_ref for worker status.');
@@ -374,12 +349,11 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
         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);
-          for (const [key,batch] of batches) if (batch.contexts.includes(context)) batches.delete(key);
           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.record) throw new Error('This project agent is not connected. Call connect_project_agent or add_project_agent again and use the connection_ref it returns.');
           if (context.stopped) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
           if (context.closing || context.stopping) throw new Error('This binding is stopping. Wait for the worker to stop before reconnecting.');
           if (workerOwnsMutations(context) && !READ_TOOLS.has(name)) throw new Error('This worker owns project mutations. Use control_project_worker to steer or stop it; the supervisor must not mutate concurrently.');
@@ -396,7 +370,7 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
         }
       }
     } catch (error) {
-      const safe = /^(Owner |Public discovery|This project is not published|Start the project|The MCP session closed|Only paused or blocked|There is no active work|Too many steering|Call get_project|Worker |Worker start|Choose |Provide a clear|Explicit human approval|Supervised workers|Saved worker model session|The worker folder|This work session|This worker|Sign in locally|Cannot run (claude|codex)|This adapter requires|Cannot inspect local MCP|Invalid local MCP|Unsupported local MCP|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 ?? '');
+      const safe = /^(Owner |Public discovery|This project is not published|Start the project|The MCP session closed|Only paused or blocked|There is no active work|Too many steering|Call get_project|Worker |Worker start|Choose |Provide a clear|Explicit human approval|Supervised workers|Saved worker model session|The worker folder|This work session|This worker|Sign in locally|Cannot run (claude|codex)|This adapter requires|Cannot inspect local MCP|Invalid local MCP|Unsupported local MCP|Private connection state|Use |Saved approval|This project agent|This binding|This computer is not approved|Adding an agent|An unfinished request|Saved agent request|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.'));
     }
   }
@@ -408,10 +382,9 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     const name = rpc.params?.name, args = rpc.params?.arguments;
     if (rpc.method !== 'tools/call' || ['get_karma42_guide', 'list_project_agents', 'get_project_worker'].includes(name)) return { priority: true };
     if (['control_project_worker', 'disconnect_project_agent'].includes(name)) return { priority: true, lane: `control:${args?.connection_ref}` };
-    if (OWNER_TOOLS.some(tool => tool.name === name)) return { lane: 'owner' };
+    if (OWNER_TOOLS.some(tool => tool.name === name) || ['connect_project_agent', 'connect_project_agents'].includes(name)) return { lane: 'owner' };
     if (DISCOVERY_TOOLS.some(tool => tool.name === name)) return { lane: 'discovery' };
-    if (['connect_project_agent', 'connect_project_agents', 'start_project_worker'].includes(name)) return { lane: 'setup' };
-    if (name === 'finish_project_agent_connection' || name === 'finish_project_agents_connection') return {};
+    if (name === 'start_project_worker') return { lane: 'setup' };
     return allowed.has(name) ? { lane: `project:${args?.connection_ref}` } : {};
   }
   function dispatch(rpc) {

package/src/session-stdio.mjs

@@ -31,7 +31,7 @@ export async function serveSession({ connection, home = sessionHome(), input = p
       active = withLock(dir, async () => {
         try {
           requestAbort = new AbortController();
-          control = new Control(record.service, token, { takeover: false, requestSignal: requestAbort.signal, onFatal: stop });
+          control = new Control(record.service, token, { stateDir: dir, agentId: record.agentId, takeover: false, requestSignal: requestAbort.signal, onFatal: stop });
           const startupTimeout = setTimeout(() => { requestAbort.abort(); control.abort.abort(); }, 30_000);
           try { await control.start(); control.loop?.catch(() => {}); } finally { clearTimeout(startupTimeout); }
           if (stopped) throw new Error('Client disconnected.');

package/src/system.mjs

@@ -2,31 +2,14 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
+import { spawn } from 'node:child_process';
 
-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('Browser pairing reply unavailable. Retry the same pending connection.'); }
-  if (!response.ok) {
-    if (response.status === 401 || response.status === 403) throw new Error('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 = ['control-v2.mjs', 'work-controller.mjs', 'providers.mjs', 'claude-settings.json', 'AGENT_PROMPT_V2.md', 'project-tools.json'];
+  const names = ['control-v2.mjs', 'turn-report-journal.mjs', 'work-controller.mjs', 'providers.mjs', 'claude-settings.json', 'AGENT_PROMPT_V2.md', 'project-tools.json'];
   if (Object.keys(manifest.files ?? {}).sort().join() !== [...names].sort().join()) throw new Error('Invalid packaged runtime manifest.');
   const files = {};
   for (const name of names) {
@@ -36,4 +19,21 @@ export function verifyBundle() {
   }
   return { files, fingerprint: createHash('sha256').update(JSON.stringify(manifest.files)).digest('hex') };
 }
-export const system = { request, verifyBundle, now: () => new Date().toISOString() };
+
+// Opens only a Karma42 approval page, in the person's default browser. Returns whether an attempt was made;
+// the caller still shows the link, because a launched command is not proof that a page appeared.
+export function openApprovalPage(address, { platform = process.platform, env = process.env, spawnImpl = spawn } = {}) {
+  let url;
+  try { url = new URL(address); } catch { return false; }
+  const karma = url.protocol === 'https:' && ['karma42.ai', 'karma42-beta.web.app'].includes(url.hostname) && !url.port;
+  const local = url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname);
+  if (!(karma || local) || url.username || url.password || !url.pathname.startsWith('/viewer/')) return false;
+  // No desktop to open a page on: remote shells, CI, and Linux without a display.
+  if (env.KARMA42_NO_BROWSER || env.CI || env.SSH_CONNECTION || env.SSH_TTY || (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY)) return false;
+  const [command, args] = platform === 'darwin' ? ['open', [url.href]] : platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url.href]] : ['xdg-open', [url.href]];
+  try {
+    const child = spawnImpl(command, args, { detached: true, stdio: 'ignore' });
+    child.on?.('error', () => {}); child.unref?.();
+    return true;
+  } catch { return false; }
+}

package/src/version.mjs

@@ -1 +1,3 @@
-export const VERSION = '0.1.0-beta.10';
+export const VERSION = '0.1.0-beta.12';
+// Raised when the bundled guide gains rules a website prompt depends on; prompts name the minimum they need.
+export const GUIDE_REVISION = 5;

package/src/worker-runtime.mjs

@@ -27,14 +27,16 @@ const bounded = (value, label, max = 2000) => {
   if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) throw new Error(`Provide a clear ${label}.`);
   return value.trim();
 };
-const faultCodes = new Set(['rate_limited', 'project_busy', 'internal_error', 'unauthorized', 'forbidden', 'run_superseded', 'runtime_update_required', 'runtime_conflict', 'run_active', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN']);
+const faultCodes = new Set(['rate_limited', 'project_busy', 'internal_error', 'unauthorized', 'forbidden', 'run_superseded', 'runtime_conflict', 'run_active', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN']);
 const contactIsTransient = failure => failure.fatal === false || failure.name === 'TimeoutError'
   || (failure instanceof TypeError && failure.message === 'fetch failed')
   || ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN'].includes(failure.cause?.code);
 export function validateWorkerWorkspace(folder, record) {
   if (typeof folder !== 'string' || !folder.startsWith('/')) throw new Error('Choose a separate absolute Git checkout or worktree for the worker.');
   const cwd = canonicalPath(folder);
-  try { assertStateOutsideWorkspace(record.folder, cwd); } catch { throw new Error('Use separate sibling checkouts or worktrees so the worker and current chat do not edit the same files.'); }
+  // An agent added through the approved computer has a folder of its own, which is also its checkout.
+  // A connection made from a chat folder still needs a separate one, so the chat and worker never share files.
+  if (!(record.ownFolder === true && cwd === record.folder)) try { assertStateOutsideWorkspace(record.folder, cwd); } catch { throw new Error('Use separate sibling checkouts or worktrees so the worker and current chat do not edit the same files.'); }
   const git = args => { const result = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 15000, maxBuffer: 16384, env: { PATH: process.env.PATH, HOME: process.env.HOME, GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1' } }); return result.status === 0 ? result.stdout.trim() : null; };
   const root = git(['rev-parse', '--show-toplevel']), origin = git(['remote', 'get-url', 'origin']);
   if (!root || canonicalPath(root) !== cwd || !origin || origin.replace(/\.git$/, '').replace(/\/$/, '') !== record.repo.replace(/\/$/, '')) throw new Error('The worker folder must be a Git repository root with the project’s HTTPS GitHub origin. No repository was changed.');
@@ -118,7 +120,7 @@ export function createProjectWorker({ control, bridge, record, stateDir = connec
       requested_model: requestedModel, model: actualModel, last_turn_usage: lastUsage,
       permission_denials: { count: denialCount, tools: [...denialTools], last_at: lastDenialAt },
       unread_messages: Number.isSafeInteger(news?.pending) ? news.pending : null,
-      scheduling, delivery: { pending: journal()?.data?.pending?.length ?? 0, notices: journal()?.data?.notices?.length ?? 0 },
+      scheduling, report_delivery: control.reportDeliveryStatus?.() ?? null, delivery: { pending: journal()?.data?.pending?.length ?? 0, notices: journal()?.data?.notices?.length ?? 0 },
       contact_known: typeof news?.project?.started === 'boolean' && typeof news?.project?.paused === 'boolean',
       work_available: news?.work?.runnable === true && Number.isSafeInteger(news.work.revision)
         && news.work.revision > (scheduling?.handledRevision ?? -1),
@@ -172,6 +174,7 @@ export function createProjectWorker({ control, bridge, record, stateDir = connec
       failureInfo = null; error = null;
       for (const item of applied) item.state = 'applied';
       failureStage = 'checkout_ownership';
+      control.assertReportCapacity?.();
       checkoutClaim.beginTurn(); invokedAt = now(); actualModel = null;
       failureStage = 'native_execution';
       notify();
@@ -184,8 +187,6 @@ export function createProjectWorker({ control, bridge, record, stateDir = connec
     })();
     try {
       const result = await turn;
-      failureStage = 'checkout_cleanup';
-      checkoutClaim.endTurn();
       let lastTurn;
       if (invokedAt !== undefined) {
         // Sequence belongs to the fenced service run, not this finite worker mission.
@@ -199,6 +200,9 @@ export function createProjectWorker({ control, bridge, record, stateDir = connec
             ...lastUsage, ...(lastUsage?.tokens ? { tokens: { input: null, output: null, cacheRead: null, cacheWrite: null, modelCalls: null, ...lastUsage.tokens } } : {}),
             sequence: usageSequence, seconds: Math.max(0, (endedAt - invokedAt) / 1000) } };
       }
+      if (lastTurn) { failureStage = 'completion_storage'; lastTurn = control.recordTurn?.(lastTurn) ?? lastTurn; }
+      failureStage = 'checkout_cleanup';
+      checkoutClaim.endTurn();
       if (result?.interrupted) { scheduler.recordOutcome({ kind: sendDeferred ? 'send_deferred' : 'interrupted', news: control.news, now: now() }); if (!stopRequested && phase !== 'paused') phase = 'waiting'; }
       else if (result?.failed) {
         if (result.failureCode !== 'runtime_contact_failure') {
@@ -220,7 +224,7 @@ export function createProjectWorker({ control, bridge, record, stateDir = connec
       try { await control.setPhase?.('idle', lastTurn); }
       catch (failure) {
         if (failure.fatal) throw failure;
-        // Control keeps the report for its next phase/contact/close request. Retrying
+        // Control retains the durable queue for its next phase/contact/close request. Retrying
         // telemetry must neither rerun completed model work nor cancel a model turn.
         control.log?.('Worker turn report pending; runtime contact will retry.');
       }