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

package/src/reusable-stdio.mjs

@@ -9,37 +9,57 @@ 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 { serveSession } from './session-stdio.mjs';
+import { createOwnerClient, OWNER_TOOLS } 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 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: '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: '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']) },
+];
+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. The main chat must not edit concurrently.', inputSchema: objectSchema({ connection_ref: reference, client: { type: 'string', enum: ['claude', 'codex'] }, 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: 'get_project_worker', description: 'Read this binding’s actual supervised worker status, original deadline, activity and requested/applied steering sequence. 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 is queued as a request; check requested/applied sequence rather than assuming delivery. 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']) },
+];
+const READ_TOOLS = new Set(['get_project', 'find_work', 'find_agents', 'get_updates', 'read_thread', 'get_issue_coordination', 'list_work_intents', 'get_decision', 'list_decisions']);
 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 }) {
+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 }) {
   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));
+  const localList = { name: 'list_project_agents', description: 'List only project-agent bindings in this MCP process and their observed local worker status. Does not enumerate your account or claim online presence. No model is started. Use the returned connection_ref to steer or stop a specific worker.', annotations: { readOnlyHint: true, destructiveHint: false }, inputSchema: objectSchema({ cursor: { type: 'string', description: 'Use the next cursor returned by this local list.' } }, []) };
+  const discovery = createDiscovery(discoveryOptions);
+  const owner = ownerFactory({ home, ...ownerOptions }), ownerReference = randomUUID();
+  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 bindings = new Map(), identities = new Map();
+  const batchBrowser = batchBrowserFactory({ home, io: { say() {} } });
+  const bindings = new Map(), identities = new Map(), batches = new Map();
+  const approvalTasks = 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(); } };
+  const stop = () => { stopped = true; lines.close(); for (const context of bindings.values()) void closeContext(context).catch(() => {}); };
   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 });
+  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 });
   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.');
@@ -55,13 +75,22 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     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; }
+      try { reply = JSON.parse(line); } catch { void closeContext(context).catch(() => {}); 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 = boundServer({ ...boundOptions, connection: record.id, home, input: context.input, output: context.output, signals: context.signals,
+      onReady: async handles => { context.ready = handles; await boundOptions.onReady?.(handles); },
+      canRetry: () => {
+        if (boundOptions.canRetry && !boundOptions.canRetry()) return false;
+        if (!context.worker) return true;
+        const status = context.worker.status();
+        return status.active === true && ['working', 'running', 'waiting'].includes(status.state);
+      },
+      onStopping: async () => { context.stopping = true; await context.worker?.stop(); if (context.startTask) { await context.startTask.catch(() => {}); await context.worker?.stop(); } await boundOptions.onStopping?.(); },
+    });
     context.task.catch(() => {}).finally(() => {
       context.stopped = true;
       for (const pending of context.waiting.values()) pending.reject(new Error('Bound connection stopped.'));
@@ -74,6 +103,11 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     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);
+    for (const other of bindings.values()) {
+      if (workerOwnsMutations(other) && other.workerFolder) {
+        try { assertStateOutsideWorkspace(other.workerFolder, folder); } catch { throw new Error('Use a separate chat folder: this folder overlaps an active worker in this MCP process.'); }
+      }
+    }
     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));
@@ -92,7 +126,80 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     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.' };
+    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.' };
+  }
+  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.');
+    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);
+      const identity = projectIdentity({ projectUrl: args.project_url, folder });
+      for (const other of bindings.values()) {
+        if (workerOwnsMutations(other) && other.workerFolder) {
+          try { assertStateOutsideWorkspace(other.workerFolder, folder); } catch { throw new Error('Use a separate chat folder: this folder overlaps an active worker in this MCP process.'); }
+        }
+      }
+      return { id: sessionId(identity.projectUrl,agent.agent_id), service:identity.projectUrl, agentId:agent.agent_id, agentName:agent.agent_name, folder };
+    }).sort((a,b) => a.agentId.localeCompare(b.agentId));
+    if (new Set(selected.map(agent => agent.id)).size !== selected.length) throw new Error('Use distinct agent IDs in a batch.');
+    const contexts = selected.map(agent => bindings.get(identities.get(agent.id)));
+    for (let index=0; index<contexts.length; index++) {
+      const context = contexts[index]; if (!context) continue;
+      if (context.selected.agentName !== selected[index].agentName || context.selected.folder !== selected[index].folder || context.stopped) throw new Error('This project agent already has a different or stopped binding. 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 });
+    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 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) {
+    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);
+  }
+  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;
+    }
+  }
+  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);
+    if (batch.contexts.some(context => context.stopped || bindings.get(context.ref) !== context)) throw new Error('This binding stopped or disconnected. Retry with explicitly selected unbound agents.');
+    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);
   }
   function contextFor(args) {
     const context = bindings.get(args.connection_ref);
@@ -106,12 +213,81 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
     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 });
+    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.signals?.emit('SIGTERM'); context.input?.end();
-    if (context.task) await context.task.catch(() => {});
-    context.lines?.close(); context.output?.destroy();
+    context.closing ??= (async () => {
+      // Stop the model process before aborting/releasing its shared coordination run.
+      try {
+        // A start may be validating its checkout or preparing the local bridge. Signal stop
+        // immediately, then await that setup and stop again before releasing coordination.
+        await context.worker?.stop();
+        if (context.startTask) { await context.startTask.catch(() => {}); await context.worker?.stop(); }
+      }
+      finally {
+        context.signals?.emit('SIGTERM'); context.input?.end();
+        if (context.task) await context.task.catch(() => {});
+        context.lines?.close(); context.output?.destroy();
+      }
+    })();
+    return context.closing;
+  }
+  function verifiedContext(args) {
+    const context = contextFor(args);
+    if (!context.verified || !context.ready) throw new Error('Call get_project with this connection_ref and verify identity before controlling a worker.');
+    if (context.stopped || context.stopping || context.closing) throw new Error('This binding stopped. Disconnect its connection_ref before reconnecting.');
+    return context;
+  }
+  async function startWorker(args) {
+    if (Object.keys(args).some(key => !['connection_ref', 'client', 'minutes', 'scope', 'folder', 'approved'].includes(key))) throw new Error('Use only the documented worker options.');
+    const context = verifiedContext(args), minutes = args.minutes === undefined ? 60 : args.minutes;
+    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);
+    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] : [])];
+      for (const candidate of candidates) {
+        try { assertStateOutsideWorkspace(candidate, folder); } catch { throw new Error('Use separate sibling checkouts: this folder overlaps another project-agent binding or active worker in this MCP process.'); }
+      }
+    }
+    if (workerOwnsMutations(context)) throw new Error('This worker already owns the approved work session. Use worker controls; starting again cannot extend its deadline.');
+    if (!context.worker || ['completed', 'stopped'].includes(context.worker.status().state)) {
+      const factory = workerFactory ?? (await import('./worker-runtime.mjs')).createProjectWorker;
+      if (context.stopped || context.stopping || context.closing) throw new Error('This binding is stopping. A worker was not started.');
+      context.worker = factory({ ...context.ready, stateDir: connectionDir(home, context.record.id) });
+    }
+    try {
+      context.workerFolder = folder;
+      context.startTask = Promise.resolve().then(() => context.worker.start({ client: args.client, minutes, scope: args.scope.trim(), folder, approved: true }));
+      const snapshot = await context.startTask;
+      if (context.stopped || context.stopping || context.closing) { await context.worker.stop(); throw new Error('This binding is stopping. The worker was stopped.'); }
+      return { connection_ref: context.ref, worker: snapshot };
+    } catch (error) {
+      const safe = /^(Start the project|The MCP session closed|Use separate sibling|The worker folder|Choose a separate|This worker adapter|Saved worker model session|Explicit human approval|This work session already|Supervised workers|Choose a work duration|Provide a clear|Cannot run (claude|codex) --version|Sign in locally with codex login|This adapter requires Codex CLI|Cannot inspect local MCP configuration|Invalid local MCP configuration|Unsupported local MCP configuration)/.test(error.message ?? '');
+      throw new Error(safe ? error.message : 'Worker could not start. Check local client installation and sign-in, native permissions, and the approved separate repository checkout. No permissions were changed.');
+    }
+  }
+  async function controlWorker(args) {
+    if (Object.keys(args).some(key => !['connection_ref', 'action', 'instruction'].includes(key)) || !['pause', 'resume', 'stop', 'steer'].includes(args.action)) throw new Error('Use pause, resume, stop or steer for this exact worker.');
+    const context = verifiedContext(args);
+    if (!context.worker) throw new Error('This binding has no worker. Ask your human before starting one.');
+    if (args.action === 'steer') {
+      if (typeof args.instruction !== 'string' || !args.instruction.trim() || args.instruction.length > 2000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/.test(args.instruction)) throw new Error('Use a steering instruction of at most 2000 characters.');
+      const receipt = await context.worker.steer({ message: args.instruction.trim() });
+      return { connection_ref: context.ref, steering_request: receipt, worker: context.worker.status() };
+    }
+    if (args.instruction !== undefined) throw new Error('Use instruction only for a steer action.');
+    return { connection_ref: context.ref, worker: await context.worker[args.action]() };
+  }
+  function workerOwnsMutations(context) {
+    if (!context.worker) return false;
+    const current = context.worker.status();
+    if (typeof current.active === 'boolean') return current.active;
+    return !['idle', 'stopped', 'completed', 'expired', 'failed'].includes(current.state ?? current.status);
   }
   try {
     for await (const line of lines) {
@@ -125,15 +301,46 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
         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.' } });
+          send({ jsonrpc: '2.0', id: rpc.id, result: { protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'karma42', version: VERSION }, instructions: 'Human owner management uses connect_owner_account and browser approval, separate from agent identities. Use its exact owner_ref for proposal status, project readiness/start and project roles. Only act on the human’s explicit instruction for start/role changes. Connection approval does not authorize a model or platform privileges. Explore published projects first with explore_projects and get_public_project; no connection or sign-in is required for these reads. get_project_join_link sends your human to sign in, join and create/select an agent; never infer their agent ID. list_project_agents reports bindings in this MCP process only. Multiple workers require separate explicit human approval of each identity, scope, folder and duration; workers must use separate checkouts and cannot recruit or start other workers. 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. A supervised project worker can start only after separate human approval through start_project_worker. While it owns the work, this chat supervises and steers; do not edit the same repository or send project mutations concurrently.' } });
         } 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)) });
+          if (OWNER_TOOLS.some(tool => tool.name === name)) {
+            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 }) });
+            } 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 === 'disconnect_owner_account') ownerConnected = false;
+              send({ jsonrpc: '2.0', id: rpc.id, result: result({ ...account, owner_ref: ownerReference }) });
+            }
+          }
+          else if (DISCOVERY_TOOLS.some(tool => tool.name === name)) send({ jsonrpc: '2.0', id: rpc.id, result: result(await discovery.call(name, args)) });
+          else if (name === 'list_project_agents') {
+            if (Object.keys(args).some(key => key !== 'cursor')) throw new Error('Use only the cursor returned by list_project_agents.');
+            const entries = [...bindings.values()];
+            const offset = args.cursor === undefined ? 0 : entries.findIndex(context => context.ref === args.cursor) + 1;
+            if (args.cursor !== undefined && (typeof args.cursor !== 'string' || offset === 0)) throw new Error('Use the next cursor returned by this local agent list, or omit it to restart.');
+            const page = entries.slice(offset, offset + 20);
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ scope: 'this_mcp_process', agents: page.map(context => ({ ...state(context), worker: context.worker?.status() ?? { state: 'not_started', active: false } })), 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') 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') 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.');
+            const context = contextFor(args);
+            send({ jsonrpc: '2.0', id: rpc.id, result: result({ connection_ref: context.ref, worker: context.worker?.status() ?? { state: 'not_started', active: false } }) });
+          }
+          else if (name === 'control_project_worker') send({ jsonrpc: '2.0', id: rpc.id, result: result(await controlWorker(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);
@@ -143,6 +350,8 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
             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.');
+            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.');
             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`);
@@ -152,12 +361,12 @@ export async function serveReusable({ home = sessionHome(), input = process.stdi
           }
         }
       } 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 ?? '');
+        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 ?? '');
         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));
+    stop(); await Promise.allSettled([...approvalTasks.values(), ...[...bindings.values()].map(closeContext)]);
     input.off('end', stop); for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.off(signal, stop);
   }
 }

package/src/session-stdio.mjs

@@ -5,7 +5,7 @@ import { assertStateOutsideWorkspace, connectionDir, digest, load, lstatExists,
 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, retryIntervalMs = 20_000 }) {
+export async function serveSession({ connection, home = sessionHome(), input = process.stdin, output = process.stdout, signals = process, Control = ControlV2, Bridge = DeferredMcp, retryIntervalMs = 20_000, onReady, onStopping, canRetry = () => true }) {
   verifyBundle();
   const dir = connectionDir(home, connection);
   const record = validateSession(load(dir), connection);
@@ -14,9 +14,12 @@ export async function serveSession({ connection, home = sessionHome(), input = p
   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);
-  let stopped = false, verified = false, control, bridge, active, releaseLock, retry, requestAbort;
+  let stopped = false, verified = false, announced = false, stopping, control, bridge, active, releaseLock, retry, requestAbort;
   const lines = createInterface({ input, crlfDelay: Infinity });
-  const stop = () => { stopped = true; requestAbort?.abort(); control?.abort?.abort(); lines.close(); };
+  const stop = () => {
+    stopped = true; lines.close(); clearInterval(retry);
+    stopping ??= Promise.resolve().then(() => onStopping?.()).catch(() => {}).finally(async () => { requestAbort?.abort(); await control?.close('operator'); });
+  };
   input.once('end', stop);
   for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) signals.on(signal, stop);
   const send = reply => { if (!stopped && reply != null) output.write(`${JSON.stringify(reply)}\n`); };
@@ -30,7 +33,7 @@ export async function serveSession({ connection, home = sessionHome(), input = p
           requestAbort = new AbortController();
           control = new Control(record.service, token, { takeover: false, requestSignal: requestAbort.signal, onFatal: stop });
           const startupTimeout = setTimeout(() => { requestAbort.abort(); control.abort.abort(); }, 30_000);
-          try { await control.start(); } finally { clearTimeout(startupTimeout); }
+          try { await control.start(); control.loop?.catch(() => {}); } finally { clearTimeout(startupTimeout); }
           if (stopped) throw new Error('Client disconnected.');
           bridge = new Bridge(control, journal);
           ready();
@@ -67,9 +70,12 @@ 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;
+            if (!announced) { await onReady?.({ control, bridge, record, stateDir: dir }); announced = 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);
+            retry ??= setInterval(() => {
+              try { if (canRetry()) void bridge.retryDue().catch(stop); } catch { stop(); }
+            }, retryIntervalMs);
           }
           send(reply); continue;
         }
@@ -86,7 +92,7 @@ export async function serveSession({ connection, home = sessionHome(), input = p
       }
     }
   } finally {
-    stop(); clearInterval(retry); releaseLock?.();
+    stop(); await stopping; clearInterval(retry); releaseLock?.();
     // If EOF occurs during startup, start finishes before its finally reports stopping.
     if (active) await active.catch(() => {});
     await catalog.close();

package/src/system.mjs

@@ -26,7 +26,7 @@ export function verifyBundle() {
   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', 'project-tools.json'];
+  const names = ['control-v2.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) {

package/src/version.mjs

@@ -1 +1 @@
-export const VERSION = '0.1.0-beta.5';
+export const VERSION = '0.1.0-beta.7';