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

package/README.md

@@ -1,13 +1,13 @@
 # Karma42 MCP connector
 
-`0.1.0-beta.10` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
+`0.1.0-beta.11` is a **beta release**. It connects an existing MCP-capable AI client to a Karma42 project. Registration and current-chat mode do not select, download or run a model. An explicitly approved local worker is a separate work mode. An MCP-capable client using DeepSeek or another model can use the same transport if that client supports local stdio MCP and the required project tools.
 
 ## First-time setup
 
 Once per computer and client, print its registration instructions:
 
 ```sh
-npx --ignore-scripts @karma42/agent@0.1.0-beta.10 mcp-config --client claude
+npx --ignore-scripts @karma42/agent@0.1.0-beta.11 mcp-config --client claude
 ```
 
 Use `--client codex` for Codex, or `--client other` for the generic stdio configuration. **Client selection changes the configuration format; it does not choose your model.**
@@ -106,6 +106,6 @@ CLI equivalents: `project-agents --project PROJECT_ID` and `agents-register --pr
 
 ## Bundled orchestration skill
 
-`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.10 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
+`skills/karma42/SKILL.md` is the single maintained workflow for owner access, project readiness/start, team selection/registration, batch approval, identity checks and supervised workers. The MCP supplies it as initialization instructions and through `get_karma42_guide`, so guidance is available even without native skill support. `npx --ignore-scripts @karma42/agent@0.1.0-beta.11 skill` prints the same file; it never edits settings. A client can optionally save it in its supported skill location after the user approves that file addition. Installation/registration does not grant account access or authorize work. A generic host subagent is not automatically an independently connected Karma42 worker.
 
 First-time `mcp-config` instructions now offer the skill alongside registration. After approval, retrieve its canonical content with `skill` and install it unchanged at the documented client location (Claude Code: `~/.claude/skills/karma42/SKILL.md`; Codex: `~/.agents/skills/karma42/SKILL.md`). Existing different skills require separate replacement approval. Other clients use their documented skill support or `get_karma42_guide`. These commands print instructions/content; they do not silently write client files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karma42/agent",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.11",
   "description": "Model-independent Karma42 MCP connector for project agents",
   "license": "UNLICENSED",
   "type": "module",

package/runtime/control-v2.mjs

@@ -1,9 +1,13 @@
 // Runtime control stays outside model turns. One request at a time; fatal refusals stop the model.
 import { setTimeout as sleep } from 'node:timers/promises';
+import { TurnReportJournal } from './turn-report-journal.mjs';
 
 export class ControlV2 {
-  constructor(url, token, { pollSeconds = 20, takeover = false, runtime, requestSignal, onFatal = () => {}, log = () => {} } = {}) {
+  constructor(url, token, { pollSeconds = 20, takeover = false, runtime, requestSignal, stateDir, agentId, onFatal = () => {}, log = () => {} } = {}) {
     Object.assign(this, { url, token, pollSeconds: Math.max(10, pollSeconds), takeover, runtime, requestSignal, onFatal, log });
+    this.turnReports = stateDir ? new TurnReportJournal(stateDir, { url, token, agentId }) : null;
+    this.reportFailure = null;
+    this.reportStorageFailure = null;
     this.phase = 'idle';
     this.lastPhaseAt = 0;
     this.lastTurn = undefined;
@@ -35,9 +39,12 @@ export class ControlV2 {
   }
 
   async start() {
+    await this.flushTurnReports();
     const run = await this.request('/runs', { runner_version: this.runtime ? `kit-${this.runtime.kitHash.slice(0, 12)}` : 'kit-v2', takeover: this.takeover, ...(this.runtime ? { runtime: this.runtime } : {}) });
     if (run.protocol !== 2) throw new Error('Protocol mismatch: this runner needs protocol 2.');
     this.runId = run.run_id;
+    this.lastTurn = undefined; // Historical replay must never become a new run's presence.
+    this.turnReports?.activateRun(this.runId);
     this.pollSeconds = Math.max(this.pollSeconds, run.poll_seconds);
     while (!this.closed && !this.news) {
       const delay = await this.observe();
@@ -52,13 +59,63 @@ export class ControlV2 {
     return task;
   }
 
+  reportDeliveryStatus() {
+    let capacityFailure;
+    try { this.turnReports?.assertCapacity(this.runId); } catch (error) { capacityFailure = error; }
+    return { pending: this.turnReports?.data.pending.length ?? 0, blocked: Boolean(this.reportStorageFailure || this.reportFailure?.fatal || capacityFailure),
+      error: this.reportStorageFailure?.message ?? this.reportFailure?.message ?? capacityFailure?.message ?? null };
+  }
+
+  assertReportCapacity() {
+    if (this.reportStorageFailure) throw this.reportStorageFailure;
+    if (this.reportFailure?.fatal) throw this.reportFailure;
+    this.turnReports?.assertCapacity(this.runId);
+  }
+
+  recordTurn(lastTurn) {
+    if (this.reportStorageFailure) throw this.reportStorageFailure;
+    try {
+      this.lastTurn = this.turnReports ? this.turnReports.add(this.runId, lastTurn) : lastTurn;
+      return this.lastTurn;
+    } catch (error) { this.reportStorageFailure = error; throw error; }
+  }
+
+  async deliverTurnReports() {
+    if (!this.turnReports || this.reportStorageFailure) return;
+    for (const entry of [...this.turnReports.data.pending]) {
+      try {
+        const receipt = await this.request('/turn-reports', { run_id: entry.run_id, last_turn: entry.last_turn });
+        if (receipt.ok !== true || typeof receipt.report_id !== 'string' || !receipt.report_id) throw new Error('Completion report acknowledgement is missing.');
+        try { this.turnReports.acknowledge(entry); }
+        catch (error) { this.reportStorageFailure = error; throw error; }
+        this.reportFailure = null;
+      } catch (error) {
+        this.reportFailure = error;
+        this.log(`Completed turn report retained locally: ${error.message}`);
+        break;
+      }
+    }
+  }
+
+  flushTurnReports() { return this.serialize(() => this.deliverTurnReports()); }
+
+  liveLastTurn() {
+    // Historical delivery never changes live presence. Publish the latest observation
+    // only after its journal acknowledgement, so phase reporting cannot bypass a refusal.
+    if (!this.lastTurn) return undefined;
+    const pending = this.turnReports?.data.pending.some(entry => entry.run_id === this.runId
+      && entry.last_turn.usage.sequence === this.lastTurn.usage?.sequence);
+    return pending ? undefined : this.lastTurn;
+  }
+
   async cycle() {
     return this.serialize(async () => {
+      await this.deliverTurnReports();
       this.news = null; // Fail closed while contact is uncertain: no new model turn.
       const reportDue = Date.now() - this.lastPhaseAt >= 60_000;
       const news = await this.request('/wait', {
         run_id: this.runId,
-        ...(reportDue ? { report: { phase: this.phase, ...(this.lastTurn ? { last_turn: this.lastTurn } : {}),
+        ...(reportDue ? { report: { phase: this.phase, ...(this.liveLastTurn() ? { last_turn: this.liveLastTurn() } : {}),
           ...(this.activity ? { activity: this.activity } : {}) } } : {}),
       });
       // Advance only after the combined request succeeds. A lost response retries the report;
@@ -106,12 +163,13 @@ export class ControlV2 {
   }
 
   async setPhase(phase, lastTurn, reportRuntime = false) {
-    if (lastTurn) this.lastTurn = lastTurn;
+    if (lastTurn && lastTurn !== this.lastTurn) this.recordTurn(lastTurn);
     if (this.fatal) throw this.fatal;
     this.phase = phase;
     return this.serialize(async () => {
+      await this.deliverTurnReports();
       await this.request(`/runs/${this.runId}/phase`, {
-        phase, ...(this.lastTurn ? { last_turn: this.lastTurn } : {}), ...(this.activity ? { activity: this.activity } : {}), ...(reportRuntime && this.runtime ? { runtime: this.runtime } : {}),
+        phase, ...(this.liveLastTurn() ? { last_turn: this.liveLastTurn() } : {}), ...(this.activity ? { activity: this.activity } : {}), ...(reportRuntime && this.runtime ? { runtime: this.runtime } : {}),
       });
       this.lastPhaseAt = Date.now();
     });
@@ -124,7 +182,7 @@ export class ControlV2 {
     this.abort.abort();
     if (this.runId && (!this.fatal || this.fatal.code === 'runtime_update_required')) {
       try {
-        await this.serialize(() => this.request(`/runs/${this.runId}/phase`, { phase: 'stopping', ...(reason ? { reason } : {}), ...(this.lastTurn ? { last_turn: this.lastTurn } : {}) }));
+        await this.serialize(async () => { await this.deliverTurnReports(); return this.request(`/runs/${this.runId}/phase`, { phase: 'stopping', ...(reason ? { reason } : {}), ...(this.liveLastTurn() ? { last_turn: this.liveLastTurn() } : {}) }); });
       } catch (error) { this.log(`Final stop report could not be saved: ${error.message}`); }
     }
     await this.loop;

package/runtime/manifest.json

@@ -1,7 +1,8 @@
 {
   "source": "pilot/agent-kit",
   "files": {
-    "control-v2.mjs": "02e325b642669b8f29c7b25582b1afaf4b74cbc63d2b463c11bf02abac90ca12",
+    "control-v2.mjs": "1140995d6869287026c38b763e160741ab08520749f8b2eb9b7cb3f931583ab1",
+    "turn-report-journal.mjs": "cdb64fe7ffea9e441e0e1a4572b128195740340c08d9501436e42244fbef8e3c",
     "work-controller.mjs": "ca1b6c7ad62d23ee90012e37c0218303bdd4e6b67c26714996b14c7f64e4269c",
     "providers.mjs": "bb411985eb7e6936856b6905f6efa7b9bdd48f9a08e0de8e4ceb785945cd69f2",
     "claude-settings.json": "bf3bfaaf38de37cda60a7dc48cb8c186c1864df61bd5ff500715ee2d1db4333e",

package/runtime/turn-report-journal.mjs

@@ -0,0 +1,81 @@
+// Completed telemetry is independent of model/session recovery. Single foreground writer.
+import { createHash, randomBytes } from 'node:crypto';
+import { constants, fstatSync, mkdirSync, lstatSync, readdirSync, readFileSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, rmSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+const hash = value => createHash('sha256').update(value).digest('hex');
+const MAX_BYTES = 2 * 1024 * 1024, MAX_PENDING = 128, MAX_RUNS = 128;
+const invalid = () => new Error('Completion report journal is invalid or belongs to another connection; inspect private state before continuing.');
+export class TurnReportJournal {
+  constructor(stateDir, { url, token, agentId = '' }) {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    const directoryStat = lstatSync(stateDir);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) throw invalid();
+    this.identity = hash(JSON.stringify([url, agentId, token]));
+    this.file = join(stateDir, `turn-reports-${this.identity}.json`);
+    this.data = { version: 1, identity: this.identity, revision: 0, sequences: {}, pending: [] };
+    // Recover a completely flushed draft from a crash before rename. Never erase corrupt state.
+    const candidates = readdirSync(stateDir).filter(name => name === basename(this.file) || name.startsWith(`${basename(this.file)}.`) && name.endsWith('.tmp'));
+    for (const name of candidates) {
+      const path = join(stateDir, name);
+      let data, fd;
+      try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_BYTES || (stat.mode & 0o077)) throw invalid();
+        data = JSON.parse(readFileSync(fd, 'utf8'));
+      } catch { throw invalid(); } finally { if (fd !== undefined) closeSync(fd); }
+      this.validate(data);
+      if (data.revision === this.data.revision && JSON.stringify(data) !== JSON.stringify(this.data)) throw invalid();
+      if (data.revision > this.data.revision) this.data = data;
+    }
+    if (candidates.length) { this.save(); for (const name of candidates) if (name !== basename(this.file)) rmSync(join(stateDir, name)); this.syncDirectory(); }
+  }
+  validate(data) {
+    if (data?.version !== 1 || data.identity !== this.identity || !Number.isSafeInteger(data.revision) || data.revision < 0 || !data.sequences || Array.isArray(data.sequences) || !Array.isArray(data.pending) || data.pending.length > MAX_PENDING || Object.keys(data.sequences).length > MAX_RUNS) throw invalid();
+    for (const [run, seq] of Object.entries(data.sequences)) if (!run || !Number.isSafeInteger(seq) || seq < 1) throw invalid();
+    const ids = new Set();
+    for (const entry of data.pending) {
+      if (typeof entry.run_id !== 'string' || !entry.run_id || !Object.hasOwn(data.sequences, entry.run_id) || !Number.isSafeInteger(entry.last_turn?.usage?.sequence) || entry.last_turn.usage.sequence < 1 || entry.last_turn.usage.sequence > data.sequences[entry.run_id] || entry.fingerprint !== hash(JSON.stringify(entry.last_turn)) || ids.has(`${entry.run_id}:${entry.last_turn.usage.sequence}`)) throw invalid();
+      ids.add(`${entry.run_id}:${entry.last_turn.usage.sequence}`);
+    }
+  }
+  syncDirectory() { const fd = openSync(dirname(this.file), 'r'); try { fsyncSync(fd); } finally { closeSync(fd); } }
+  save() {
+    const serialized = JSON.stringify(this.data);
+    if (Buffer.byteLength(serialized) > MAX_BYTES) throw new Error('Completion report journal is full; deliver pending reports before more work.');
+    const draft = `${this.file}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    const fd = openSync(draft, 'wx', 0o600);
+    try { writeFileSync(fd, serialized); fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(draft, this.file); this.syncDirectory();
+  }
+  activateRun(runId) {
+    // Production only starts freshly issued runs. Completed older runs cannot allocate
+    // another sequence; retain every run that still owns an undelivered report.
+    const pendingRuns = new Set(this.data.pending.map(entry => entry.run_id));
+    const next = structuredClone(this.data);
+    for (const run of Object.keys(next.sequences)) if (run !== runId && !pendingRuns.has(run)) delete next.sequences[run];
+    if (JSON.stringify(next.sequences) === JSON.stringify(this.data.sequences)) return;
+    next.revision++; const previous = this.data; this.data = next;
+    try { this.save(); } catch (error) { this.data = previous; throw error; }
+  }
+  assertCapacity(runId) {
+    if (this.data.pending.length >= MAX_PENDING || !this.data.sequences[runId] && Object.keys(this.data.sequences).length >= MAX_RUNS || Buffer.byteLength(JSON.stringify(this.data)) > MAX_BYTES - 32 * 1024) throw new Error('Completion report journal is full; deliver pending reports before more work.');
+  }
+  add(runId, lastTurn) {
+    this.assertCapacity(runId);
+    const turn = structuredClone(lastTurn);
+    if (!turn.usage || typeof runId !== 'string' || !runId) throw new Error('A completion report needs an issued run and usage.');
+    turn.usage.sequence = (this.data.sequences[runId] ?? 0) + 1;
+    const next = structuredClone(this.data); next.revision++; next.sequences[runId] = turn.usage.sequence;
+    next.pending.push({ run_id: runId, last_turn: turn, fingerprint: hash(JSON.stringify(turn)) });
+    const previous = this.data; this.data = next;
+    try { this.save(); } catch (error) { this.data = previous; throw error; }
+    return structuredClone(turn); // Caller observations cannot mutate the durable upload payload.
+  }
+  acknowledge(entry) {
+    const next = structuredClone(this.data); next.revision++;
+    next.pending = next.pending.filter(item => !(item.run_id === entry.run_id && item.last_turn.usage.sequence === entry.last_turn.usage.sequence));
+    const previous = this.data; this.data = next;
+    try { this.save(); } catch (error) { this.data = previous; throw error; }
+  }
+}

package/src/reusable-stdio.mjs

@@ -260,7 +260,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.');

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

@@ -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', '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) {

package/src/version.mjs

@@ -1 +1 @@
-export const VERSION = '0.1.0-beta.10';
+export const VERSION = '0.1.0-beta.11';

package/src/worker-runtime.mjs

@@ -118,7 +118,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 +172,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 +185,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 +198,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 +222,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.');
       }