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

package/src/worker-runtime.mjs

@@ -0,0 +1,190 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { createWorkController } from '../runtime/work-controller.mjs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createProvider, CLAUDE_ALLOWED_TOOLS } from '../runtime/providers.mjs';
+import { VERSION } from './version.mjs';
+import { canonicalPath, connectionDir, digest, ensureHome, lstatExists, readPrivate, writePrivate, assertStateOutsideWorkspace } from './state.mjs';
+import { sessionHome } from './session.mjs';
+import { verifyBundle } from './system.mjs';
+
+const workerBridges = new WeakMap();
+function workerBridge(bridge) {
+  let listening = workerBridges.get(bridge);
+  if (!listening) {
+    listening = Promise.resolve().then(() => bridge.listen());
+    workerBridges.set(bridge, listening);
+    listening.catch(() => { if (workerBridges.get(bridge) === listening) workerBridges.delete(bridge); });
+  }
+  return listening;
+}
+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();
+};
+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.'); }
+  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.');
+  return cwd;
+}
+
+export function createLocalWorkerAdapter({ client, folder, stateDir, bridge, scope, providerFactory = createProvider, spawnModel = spawn }) {
+  verifyBundle(); ensureHome(stateDir);
+  const configuredEndpoint = client === 'claude' ? process.env.ANTHROPIC_BASE_URL : process.env.OPENAI_BASE_URL;
+  if (configuredEndpoint && (() => { try { const endpoint = new URL(configuredEndpoint); return endpoint.protocol !== 'https:' || endpoint.origin !== (client === 'claude' ? 'https://api.anthropic.com' : 'https://api.openai.com'); } catch { return true; } })()) throw new Error('This worker adapter cannot preserve your custom API endpoint. Use the current-chat MCP mode rather than silently switching your model backend.');
+  const runtime = fileURLToPath(new URL('../runtime/', import.meta.url));
+  const settings = { claude: 'claude', codex: 'codex', repoDir: folder, permissionMode: 'acceptEdits', allowedTools: CLAUDE_ALLOWED_TOOLS, passEnv: '', turnBudgetUsd: 0 };
+  const provider = providerFactory(client, settings);
+  provider.preflight();
+  const instructions = readPrivate(join(stateDir, 'instructions.md'));
+  const promptHash = digest(instructions);
+  const sessionFile = join(stateDir, 'model-session.json');
+  let session = lstatExists(sessionFile) ? readPrivate(sessionFile, true) : null;
+  if (session && (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(session.id ?? '') || session.provider !== client || session.repoDir !== folder || session.promptHash !== promptHash)) throw new Error('Saved worker model session belongs to different approved work. Use a fresh work session.');
+  return {
+    async run({ prompt, signal, onActivity, recovering = false }) {
+      if (signal.aborted) return Promise.resolve({ interrupted: true });
+      const resuming = provider.canResume(session);
+      session ??= provider.newSession(promptHash, folder);
+      const save = () => writePrivate(sessionFile, { ...session, provider: client, promptHash, repoDir: folder });
+      save();
+      const invocation = provider.invocation({ prompt, instructionsFile: join(stateDir, 'instructions.md'), settingsFile: join(runtime, 'claude-settings.json'), mcpConfig: join(stateDir, 'mcp.json'), bridge, session, resuming, repoDir: folder, clientVersion: VERSION });
+      const result = await new Promise(resolve => {
+        const child = spawnModel(invocation.command, invocation.args, { cwd: folder, env: provider.environment(invocation.env), stdio: [invocation.rpc ? 'pipe' : 'ignore', 'pipe', 'pipe'], windowsHide: true });
+        let done = false, interrupted = false, persistenceFault = false, killTimer, forceTimer, stderr = '';
+        const stream = provider.collector({ rpc: invocation.rpc, log: () => {}, action: onActivity, session: id => { session.id = id; try { save(); } catch { persistenceFault = true; child.kill('SIGTERM'); } } });
+        const interrupt = () => { interrupted = true; if (invocation.rpc) stream.interrupt(); else child.kill('SIGINT'); killTimer = setTimeout(() => child.kill('SIGTERM'), 3000); forceTimer = setTimeout(() => child.kill('SIGKILL'), 8000); };
+        signal.addEventListener('abort', interrupt, { once: true });
+        const finish = code => {
+          if (done) return; done = true; stream.end(); stream.cleanup?.(); clearTimeout(killTimer); clearTimeout(forceTimer); signal.removeEventListener('abort', interrupt);
+          if (stream.sessionId) session.id = stream.sessionId;
+          if (stream.tokenTotals) session.tokenTotals = stream.tokenTotals;
+          try { save(); } catch { persistenceFault = true; }
+          const diagnostics = `${stderr} ${stream.report?.errors?.join(' ') ?? ''} ${stream.report?.result ?? ''}`;
+          const failureCode = persistenceFault ? 'private_state_failure' : /(?:not logged in|authentication|unauthorized|login required|invalid api key)/i.test(diagnostics) ? 'authentication_required' : /(?:permission denied|not permitted|approval required|tool.*refused)/i.test(diagnostics) ? 'permission_required' : 'local_execution_failure';
+          resolve({ missingSession: !interrupted && !persistenceFault && Boolean(provider.missingSession?.(stderr)), failureCode, retryable: failureCode === 'local_execution_failure', interrupted, failed: !interrupted && (persistenceFault || (invocation.rpc && stream.closed && stream.report ? 0 : code) !== 0 || stream.report?.is_error || !stream.report), text: stream.report?.result ?? stream.finalText ?? '', usage: provider.usage(stream.report, stream.init) });
+        };
+        child.stdout.setEncoding('utf8'); child.stdout.on('data', chunk => { try { stream.feed(chunk); } catch { persistenceFault = true; child.kill('SIGTERM'); } });
+        child.stderr.setEncoding('utf8'); child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-16384); }); child.once('error', () => finish(1)); child.once('close', finish);
+        if (invocation.rpc) { child.stdin.on('error', () => {}); stream.attach(child); }
+        if (signal.aborted) interrupt();
+      });
+      if (result.missingSession && !recovering && !signal.aborted) { session = null; rmSync(sessionFile, { force: true }); return this.run({ prompt, signal, onActivity, recovering: true }); }
+      if (result.missingSession) { result.failed = true; result.retryable = false; result.failureCode = 'session_recovery_failed'; }
+      delete result.missingSession; return result;
+    },
+  };
+}
+
+// A lightweight in-process supervisor, owned by the existing MCP transport and run.
+// Waiting never holds a coding model open. No token or model process is detached.
+export function createProjectWorker({ control, bridge, record, stateDir = connectionDir(sessionHome(), record.id), onState = () => {}, now = Date.now, setTimer = setInterval, clearTimer = clearInterval, adapterFactory = createLocalWorkerAdapter, validateWorkspace = validateWorkerWorkspace, pollMs = 1000, quietIntervalMs = 15 * 60000, random = Math.random, instructionsText } = {}) {
+  let phase = 'idle', deadline = null, startedAt = null, adapter, folder, client, scope, turn, abort, timer, stopRequested = false, scheduler, sendDeferred = false, lastResult = '', error = null, sequence = 0, workerConnection, activity = null;
+  const steering = [];
+  const snapshot = () => ({ state: phase, active: phase === 'starting' || Boolean(turn) || (deadline !== null && !stopRequested), activity, client: client ?? null, folder: folder ?? null, scope: scope ?? null, started_at: startedAt, deadline_at: deadline, remaining_seconds: deadline ? Math.max(0, Math.ceil((deadline - now()) / 1000)) : 0, current_turn: Boolean(turn), last_result: lastResult, error, steering: steering.map(({ id, state }) => ({ id, state })) });
+  const notify = () => { try { onState(snapshot()); } catch {} };
+  const allowed = () => !control.fatal && !control.closed && control.news?.project?.started === true && control.news.project.paused !== true;
+  const journal = () => bridge.journal;
+  const previousDeferred = bridge.onDeferred;
+  const onDeferred = () => { previousDeferred?.(); if (turn && !stopRequested) { sendDeferred = true; abort?.abort(); } };
+  bridge.onDeferred = onDeferred;
+  async function launch() {
+    if (turn || stopRequested || phase === 'paused' || !allowed() || now() >= deadline) return;
+    phase = 'working'; scheduler.beginTurn(control.news); sendDeferred = false; abort = new AbortController();
+    const applied = steering.filter(item => item.state === 'received');
+    const notices = journal()?.notices?.() ?? []; notify();
+    const prompt = `Work only within the human-approved scope: ${scope}.\nRead get_project and get_updates; respect current project state and rules. Reconcile previous work before repeating any external action.\n${applied.length ? 'Operator steering for this turn:\n' + applied.map(item => item.message).join('\n') : 'Continue the saved work session.'}\n${notices.length ? 'Runner deferred-send results (already processed; do not republish): ' + JSON.stringify(notices) + '\n' : ''}The work session ends at ${new Date(deadline).toISOString()}. End with WORK_NEXT: runnable when there is concrete work you can do next, otherwise WORK_NEXT: waiting. Do not create another agent or background process.`;
+    const signal = abort.signal;
+    turn = (async () => {
+      await control.setPhase?.('turn');
+      if (signal.aborted || stopRequested || !allowed() || now() >= deadline) return { interrupted: true };
+      for (const item of applied) item.state = 'applied';
+      notify();
+      return adapter.run({ prompt, signal, onActivity: tool => { if (typeof tool === 'string' && /^[A-Za-z0-9_:.-]{1,150}$/.test(tool)) { activity = { tool, at: now() }; control.activity = activity; notify(); } } });
+    })();
+    try {
+      const result = await turn;
+      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) {
+        scheduler.recordOutcome({ kind: 'failed', news: control.news, now: now(), retryable: result.retryable !== false });
+        phase = scheduler.status().blocked ? 'blocked' : 'waiting';
+        const messages = { authentication_required: 'Sign in to the local model client before resuming.', permission_required: 'The model needs an approved permission before this work can continue.', private_state_failure: 'Private worker state could not be saved. Check local storage before resuming.', session_recovery_failed: 'The saved model session could not be recovered. Start a fresh approved work session.' };
+        error = messages[result.failureCode] ?? 'The local model turn failed. Bounded retries stop after three failures.';
+      }
+      else {
+        lastResult = String(result?.text ?? '').slice(0, 2000); error = null;
+        scheduler.recordOutcome({ kind: 'ok', news: control.news, now: now(), continuation: /(?:^|\n)WORK_NEXT: runnable\s*$/.test(result?.text ?? '') });
+        if (notices.length) journal()?.acknowledge?.(notices);
+        if (!stopRequested && phase !== 'paused') phase = 'waiting';
+      }
+      await control.setPhase?.('idle');
+    } catch { if (!stopRequested) { scheduler.recordOutcome({ kind: 'failed', news: control.news, now: now(), retryable: false }); phase = 'blocked'; error = 'The worker stopped on a local execution failure.'; } }
+    finally { turn = null; abort = null; notify(); }
+  }
+  async function tick() {
+    if (stopRequested || deadline === null) return;
+    if (now() >= deadline) { await stop('completed'); return; }
+    if (control.fatal || control.closed) { await stop('stopped'); return; }
+    // Control polling briefly clears news before its HTTP reply. Unknown contact blocks
+    // new turns, but is not evidence that the project was paused or authorization revoked.
+    const observed = control.news?.project;
+    if (!observed || typeof observed.started !== 'boolean' || typeof observed.paused !== 'boolean') return;
+    if (!observed.started || observed.paused) {
+      // Preserve only work that was actually interrupted. A successful waiting result
+      // remains waiting; project resume must not invent a reason to start another turn.
+      if (turn) abort?.abort();
+      if (phase !== 'paused' && phase !== 'blocked') phase = 'waiting';
+      notify(); return;
+    }
+    if (phase === 'paused' || phase === 'blocked' || turn) return;
+    if (bridge.fault) { phase = 'blocked'; error = 'Project delivery state requires attention before work can continue.'; notify(); return; }
+    const decision = scheduler.decide({ news: control.news, pendingDeliveries: journal()?.data?.pending?.length ?? 0, notices: journal()?.data?.notices?.length ?? 0, steering: steering.some(item => item.state === 'received'), now: now() });
+    if (decision.action === 'stop') { phase = 'blocked'; error ??= decision.reason === 'unacknowledged_inbox' ? 'Three turns left project updates unacknowledged. Review the worker before resuming.' : 'Repeated local model failures require review before resuming.'; notify(); return; }
+    if (decision.action === 'run') await launch();
+  }
+  async function stop(finalPhase = 'stopped') {
+    stopRequested = true; phase = turn ? 'stopping' : finalPhase; clearTimer(timer); abort?.abort(); notify();
+    if (turn) await turn.catch(() => {});
+    phase = finalPhase; if (bridge.onDeferred === onDeferred) bridge.onDeferred = previousDeferred; notify(); return snapshot();
+  }
+  return {
+    status: snapshot,
+    async start(options) {
+      if (options.approved !== true) throw new Error('Explicit human approval is required for the worker client, scope, folder and duration.');
+      if (phase !== 'idle') throw new Error('This work session already started. Pause, resume or stop it; starting cannot extend its deadline.');
+      if (!allowed()) throw new Error('Start the project and resume it before starting a worker. The verified connection must still be authorized and available.');
+      client = options.client;
+      if (!['claude', 'codex'].includes(client)) throw new Error('Supervised workers currently support local Claude Code or Codex CLI. Other models can use the current-chat MCP mode.');
+      const minutes = options.minutes ?? 60;
+      if (!Number.isInteger(minutes) || minutes < 15 || minutes > 240 || minutes % 15 !== 0) throw new Error('Choose a work duration from 15 to 240 minutes in 15-minute steps.');
+      scope = bounded(options.scope, 'approved work scope', 4000); folder = validateWorkspace(options.folder, record);
+      phase = 'starting'; notify();
+      try {
+      assertStateOutsideWorkspace(stateDir, folder); ensureHome(stateDir);
+      const workerHome = join(stateDir, 'worker'); ensureHome(workerHome);
+      const workerDir = join(workerHome, randomUUID()); ensureHome(workerDir);
+      const source = instructionsText ?? verifyBundle().files['AGENT_PROMPT_V2.md'].toString('utf8');
+      writePrivate(join(workerDir, 'instructions.md'), `${source}\n\n## Human-approved local work session\nWork only on: ${scope}. Use only this project's supplied MCP connection. Do not start other agents. Your session has a finite deadline; pauses do not extend it. Stop at the deadline or operator cancellation. Native guarded permissions apply; never enable bypass.\nThis approval covers the mission, not just one issue. After completing one task, choose the next useful task within the approved scope without asking what to do next. The mission is done only when its entire approved scope is complete. If a task is blocked, record its concrete blocker and choose another useful authorized task. Wait when all useful authorized work is blocked or there is no actionable work; do not invent work or repeatedly rediscover it. Notify the human of a concrete blocker when their action is needed. End each turn with exactly one line: WORK_NEXT: runnable when concrete authorized work remains, WORK_NEXT: waiting when no authorized action is available, or WORK_NEXT: done only when the entire approved mission is complete.\nDo not create or change CI/CD, deployment, infrastructure, credentials, repository permissions or branch protection unless the approved work scope explicitly authorizes it. If that prevents a task, record the blocker and choose another authorized task. A failing check does not authorize weakening or bypassing it. These instructions constrain your approved scope; they are not an operating-system sandbox.\n`);
+      const connection = {};
+      adapter = adapterFactory({ client, folder, stateDir: workerDir, bridge: connection, scope });
+      workerConnection ??= await workerBridge(bridge);
+      if (stopRequested) throw new Error('The MCP session closed before the worker could start.');
+      Object.assign(connection, workerConnection);
+      writePrivate(join(workerDir, 'mcp.json'), { mcpServers: { pilot: connection } });
+      startedAt = now(); deadline = startedAt + minutes * 60000; phase = 'waiting'; scheduler = createWorkController({ quietIntervalMs, now, random, deadline }); notify();
+      timer = setTimer(() => { void tick().catch(() => { void stop('stopped'); }); }, pollMs);
+      void tick(); return snapshot();
+      } catch (failure) { phase = stopRequested ? 'stopped' : 'idle'; adapter = null; notify(); throw failure; }
+    },
+    async pause() { if (!deadline || stopRequested) throw new Error('There is no active work session.'); phase = 'paused'; abort?.abort(); notify(); if (turn) await turn.catch(() => {}); return snapshot(); },
+    async resume() { if (phase !== 'paused' && phase !== 'blocked') throw new Error('Only paused or blocked work can resume.'); if (now() >= deadline) return stop('completed'); error = null; phase = 'waiting'; scheduler.requestContinuation(); notify(); void tick(); return snapshot(); },
+    steer({ message }) { if (!deadline || stopRequested) throw new Error('There is no active work session.'); if (steering.length >= 64) throw new Error('Too many steering instructions in this work session.'); steering.push({ id: ++sequence, state: 'received', message: bounded(message, 'steering instruction', 2000) }); notify(); return { id: sequence, state: 'received', note: 'Queued for the next model turn; not applied yet.' }; },
+    stop: () => stop('stopped'), close: () => stop('stopped'), tick,
+  };
+}