@getmarrow/install 0.1.51 → 0.1.52

package/README.md

@@ -91,9 +91,9 @@ npx @getmarrow/install controller stop
 
 Persistent controller lifecycle is currently Linux-only. On macOS or Windows, activation still writes supported configuration and verifies one server-side install self-test without certifying that hooks continuously ran; run `npx @getmarrow/install sidecar` under an owner-managed service and pass `--no-controller`. The controller does not silently upgrade packages, change governance policy, rotate credentials, or modify unrelated project configuration.
 
-## What's New in v0.1.51
+## What's New in v0.1.52
 
-v0.1.51 keeps MCP `3.9.74` and SDK `3.7.62`, and makes generated passive runtime identity follow the current process: `MARROW_FLEET_AGENT_ID` first, then `MARROW_AGENT_ID`, with the installer-captured identity retained only as a fallback. This prevents a stale installed harness identity from overriding the current Codex, Bob, or other canonical process identity. Managed MCP config does not store an API key or shell-style credential placeholder; the owning harness inherits the key from trusted environment or secret-manager state.
+v0.1.52 keeps MCP `3.9.74` and SDK `3.7.62`, and makes generated passive runtime identity follow the current process: `MARROW_FLEET_AGENT_ID` first, then `MARROW_AGENT_ID`, with the installer-captured identity retained only as a fallback. This prevents a stale installed harness identity from overriding the current Codex, Bob, or other canonical process identity. Managed MCP config does not store an API key or shell-style credential placeholder; the owning harness inherits the key from trusted environment or secret-manager state.
 
 The integration boundary is explicit: native Claude hooks are installed only where supported and remain cooperative/client-reported until authoritative server receipts exist; MCP tools are on demand; Codex, Grok, Gemini, and similar CLIs use the governed wrapper for consequential control; owned Node processes use the SDK passive runtime while installed; and custom hosts require a bounded event adapter. Exact package SHA/integrity can prove artifact provenance, not runtime coverage. Activation-profile delivery is authenticated `client_self_reported` telemetry with `certified_coverage: false`; it acknowledges delivery but cannot attest that a hook, wrapper, or adapter ran.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/install",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "description": "Universal installer and governed runner for Marrow agent fleets.",
   "bin": {
     "marrow-install": "bin/marrow-install.js"

package/src/governed-runner.js

@@ -27,6 +27,7 @@ const {
   buildPlan,
   detectEnvironment,
 } = require('./installer');
+const { createHostUsageCapture } = require('./usage-telemetry');
 
 const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
 const MCP_SETUP_COMMAND = `npx -y --package=${ADAPTER_PROVENANCE.mcp.package}@${ADAPTER_PROVENANCE.mcp.version} marrow-mcp setup`;
@@ -512,11 +513,11 @@ function dataOf(json) {
   return json && typeof json === 'object' && json.data && typeof json.data === 'object' ? json.data : json;
 }
 
-async function requestJson(options, method, route, body) {
+async function requestJson(options, method, route, body, extraHeaders = {}) {
   if (!options.apiKey) throw new Error('MARROW_API_KEY is required. Use --fail-open only for non-production local commands.');
   const response = await fetch(new URL(route, options.baseUrl.replace(/\/$/, '/')), {
     method,
-    headers: headers(options),
+    headers: { ...headers(options), ...extraHeaders },
     body: body === undefined ? undefined : JSON.stringify(body),
   });
   const text = await response.text();
@@ -674,15 +675,48 @@ function printGate(decision, runtime, stream = process.stdout) {
   if (runtime?.value_proof?.owner_summary) stream.write(`Value: ${runtime.value_proof.owner_summary}\n`);
 }
 
-function runChild(command, env = process.env) {
+function runChild(command, env = process.env, stdout = process.stdout) {
   return new Promise((resolve) => {
+    const usageCapture = createHostUsageCapture(command);
     const child = spawn(command[0], command.slice(1), {
-      stdio: 'inherit',
+      stdio: usageCapture.supported ? ['inherit', 'pipe', 'inherit'] : 'inherit',
       shell: false,
       env,
     });
-    child.on('error', (error) => resolve({ exitCode: 127, error }));
-    child.on('close', (code, signal) => resolve({ exitCode: code ?? 1, signal: signal || null }));
+    let closed = null;
+    let pendingWrites = 0;
+    let settled = false;
+    const settle = () => {
+      if (settled || !closed || pendingWrites > 0) return;
+      settled = true;
+      resolve({
+        ...closed,
+        usageCaptureSupported: usageCapture.supported,
+        modelUsage: usageCapture.finish(),
+      });
+    };
+    if (usageCapture.supported && child.stdout) {
+      child.stdout.on('data', (chunk) => {
+        usageCapture.write(chunk);
+        pendingWrites += 1;
+        const ready = stdout.write(chunk, () => {
+          pendingWrites -= 1;
+          settle();
+        });
+        if (!ready) {
+          child.stdout.pause();
+          stdout.once('drain', () => child.stdout?.resume());
+        }
+      });
+    }
+    child.on('error', (error) => {
+      closed = { exitCode: 127, error };
+      settle();
+    });
+    child.on('close', (code, signal) => {
+      closed = { exitCode: code ?? 1, signal: signal || null };
+      settle();
+    });
   });
 }
 
@@ -718,7 +752,7 @@ async function createDecision(options, action, type, target, surfaces) {
   });
 }
 
-async function commitOutcome(options, decisionId, success, outcome, proof, gateReceiptId) {
+async function commitOutcome(options, decisionId, success, outcome, proof, gateReceiptId, modelUsage = null) {
   const body = {
     decision_id: decisionId,
     success,
@@ -727,10 +761,16 @@ async function commitOutcome(options, decisionId, success, outcome, proof, gateR
     source_meta: sourceMeta(options, 'commit', { action: outcome }),
   };
   if (gateReceiptId) body.gate_receipt_id = gateReceiptId;
-  return requestJson(options, 'POST', '/v1/agent/commit', body);
+  if (modelUsage) body.model_usage = modelUsage;
+  const commitHeaders = modelUsage
+    ? { 'Idempotency-Key': `marrow-run-${crypto.createHash('sha256')
+      .update(`${options.agentId}\u0000${options.sessionId}\u0000${decisionId}`)
+      .digest('hex')}` }
+    : {};
+  return requestJson(options, 'POST', '/v1/agent/commit', body, commitHeaders);
 }
 
-async function runGoverned(parsed) {
+async function runGoverned(parsed, execution = {}) {
   const { options, childCommand } = parsed;
   const commandText = redactedCommand(childCommand);
   const action = options.action ? redact(options.action) : commandText;
@@ -816,7 +856,7 @@ async function runGoverned(parsed) {
   }
 
   const childEnv = scopedExecutionEnv(permitVerified ? actionPermit : null);
-  const child = await runChild(childCommand, childEnv);
+  const child = await runChild(childCommand, childEnv, execution.stdout || process.stdout);
   const success = child.exitCode === 0;
   const proof = defaultProof({ options, action, childCommand, exitCode: child.exitCode, success });
   const outcome = success
@@ -826,7 +866,15 @@ async function runGoverned(parsed) {
   let commit = null;
   if (decisionId) {
     try {
-      commit = await commitOutcome(options, decisionId, success, outcome, proof, decision?.receiptId || '');
+      commit = await commitOutcome(
+        options,
+        decisionId,
+        success,
+        outcome,
+        proof,
+        decision?.receiptId || '',
+        child.modelUsage,
+      );
     } catch (error) {
       process.stderr.write(`Marrow outcome commit failed: ${error.message}\n`);
     }
@@ -861,6 +909,16 @@ async function runGoverned(parsed) {
     permit_id: actionPermit?.permit_id || null,
     permit_verified: permitVerified,
     permit_closed: Boolean(permitClosed),
+    usage_capture: {
+      supported: child.usageCaptureSupported === true,
+      observed: Boolean(child.modelUsage),
+      source: child.modelUsage?.source || null,
+      evidence: child.modelUsage
+        ? 'accepted_host_reported_usage'
+        : child.usageCaptureSupported
+        ? 'no_valid_host_reported_usage'
+        : 'unsupported_child_command',
+    },
   };
 }
 

package/src/usage-telemetry.js

@@ -0,0 +1,235 @@
+const path = require('node:path');
+const { StringDecoder } = require('node:string_decoder');
+
+const MAX_TOKEN_COUNT = 1_000_000_000;
+const MAX_USAGE_EVENT_BYTES = 4_096;
+const CODEX_USAGE_KEYS = new Set([
+  'cached_input_tokens',
+  'input_tokens',
+  'output_tokens',
+]);
+
+function isBoundedTokenCount(value) {
+  return Number.isSafeInteger(value) && value >= 0 && value <= MAX_TOKEN_COUNT;
+}
+
+function exactKeys(value, allowed) {
+  const keys = Object.keys(value);
+  return keys.length === allowed.size && keys.every((key) => allowed.has(key));
+}
+
+function normalizeCodexTurnUsage(event) {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) return null;
+  if (!exactKeys(event, new Set(['type', 'usage'])) || event.type !== 'turn.completed') return null;
+
+  const usage = event.usage;
+  if (!usage || typeof usage !== 'object' || Array.isArray(usage)) return null;
+  if (!exactKeys(usage, CODEX_USAGE_KEYS)) return null;
+
+  const inputTokens = usage.input_tokens;
+  const outputTokens = usage.output_tokens;
+  const cachedTokens = usage.cached_input_tokens;
+  if (![inputTokens, outputTokens, cachedTokens].every(isBoundedTokenCount)) return null;
+  if (cachedTokens > inputTokens) return null;
+
+  const totalTokens = inputTokens + outputTokens;
+  if (!Number.isSafeInteger(totalTokens) || totalTokens > MAX_TOKEN_COUNT) return null;
+
+  return {
+    provider: 'openai',
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cached_tokens: cachedTokens,
+    total_tokens: totalTokens,
+    source: 'codex_exec_jsonl',
+    marrow_intervention: 'governed_runner_usage_capture',
+  };
+}
+
+function isCodexJsonExecution(command) {
+  if (!Array.isArray(command) || command.length < 3) return false;
+  const executable = path.basename(String(command[0] || '')).toLowerCase().replace(/\.exe$/, '');
+  const execArgs = command.slice(2);
+  const terminatorIndex = execArgs.indexOf('--');
+  const optionArgs = terminatorIndex === -1 ? execArgs : execArgs.slice(0, terminatorIndex);
+  return executable === 'codex'
+    && command[1] === 'exec'
+    && optionArgs.includes('--json');
+}
+
+function createCompletedTypeScanner() {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let role = 'other';
+  let token = '';
+  let tokenInvalid = false;
+  let lastSignificant = '';
+  let expectTypeColon = false;
+  let expectTypeValue = false;
+  let completed = false;
+
+  return {
+    write(character) {
+      if (inString) {
+        if (escaped) {
+          escaped = false;
+          tokenInvalid = role !== 'other';
+        } else if (character === '\\') {
+          escaped = true;
+        } else if (character === '"') {
+          inString = false;
+          if (role === 'root_key') {
+            expectTypeColon = !tokenInvalid && token === 'type';
+          } else if (role === 'type_value') {
+            if (!tokenInvalid && token === 'turn.completed') completed = true;
+            expectTypeValue = false;
+          }
+          role = 'other';
+          token = '';
+          tokenInvalid = false;
+          lastSignificant = '"';
+        } else if (role !== 'other') {
+          if (token.length < 32) token += character;
+          else tokenInvalid = true;
+        }
+        return;
+      }
+
+      if (/\s/.test(character)) return;
+      if (character === '"') {
+        role = depth === 1 && (lastSignificant === '{' || lastSignificant === ',')
+          ? 'root_key'
+          : depth === 1 && expectTypeValue
+          ? 'type_value'
+          : 'other';
+        token = '';
+        tokenInvalid = false;
+        inString = true;
+        return;
+      }
+      if (character === '{' || character === '[') {
+        depth += 1;
+        lastSignificant = character;
+        return;
+      }
+      if (character === '}' || character === ']') {
+        depth = Math.max(0, depth - 1);
+        lastSignificant = character;
+        return;
+      }
+      if (depth === 1 && expectTypeColon) {
+        expectTypeColon = false;
+        expectTypeValue = character === ':';
+      } else if (depth === 1 && expectTypeValue) {
+        expectTypeValue = false;
+      }
+      if (depth === 1 && character === ',') {
+        expectTypeColon = false;
+        expectTypeValue = false;
+      }
+      lastSignificant = character;
+    },
+    completed() {
+      return completed;
+    },
+  };
+}
+
+function createCodexJsonlUsageCollector() {
+  const decoder = new StringDecoder('utf8');
+  let line = '';
+  let discardLine = false;
+  let acceptedUsage = null;
+  let usageEventCount = 0;
+  let invalidUsageEvent = false;
+  let typeScanner = createCompletedTypeScanner();
+
+  const resetLine = () => {
+    line = '';
+    discardLine = false;
+    typeScanner = createCompletedTypeScanner();
+  };
+
+  const finishLine = () => {
+    if (discardLine || !line.trim()) {
+      if (discardLine && typeScanner.completed()) invalidUsageEvent = true;
+      resetLine();
+      return;
+    }
+    let parsed = null;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      if (typeScanner.completed()) invalidUsageEvent = true;
+      resetLine();
+      return;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || parsed.type !== 'turn.completed') {
+      resetLine();
+      return;
+    }
+
+    usageEventCount += 1;
+    const normalized = normalizeCodexTurnUsage(parsed);
+    if (!normalized || usageEventCount !== 1) invalidUsageEvent = true;
+    else acceptedUsage = normalized;
+    resetLine();
+  };
+
+  const consume = (text) => {
+    for (const character of text) {
+      if (character === '\n') {
+        finishLine();
+        continue;
+      }
+      typeScanner.write(character);
+      if (discardLine) continue;
+      if (line.length >= MAX_USAGE_EVENT_BYTES) {
+        discardLine = true;
+        line = '';
+        continue;
+      }
+      line += character;
+    }
+  };
+
+  return {
+    write(chunk) {
+      consume(decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    },
+    finish() {
+      consume(decoder.end());
+      if (line || discardLine) finishLine();
+      return invalidUsageEvent || usageEventCount !== 1 ? null : acceptedUsage;
+    },
+    bufferedBytes() {
+      return Buffer.byteLength(line, 'utf8');
+    },
+  };
+}
+
+function createHostUsageCapture(command) {
+  if (!isCodexJsonExecution(command)) {
+    return {
+      supported: false,
+      write() {},
+      finish() { return null; },
+    };
+  }
+  const collector = createCodexJsonlUsageCollector();
+  return {
+    supported: true,
+    write: (chunk) => collector.write(chunk),
+    finish: () => collector.finish(),
+  };
+}
+
+module.exports = {
+  MAX_TOKEN_COUNT,
+  MAX_USAGE_EVENT_BYTES,
+  createCodexJsonlUsageCollector,
+  createHostUsageCapture,
+  isCodexJsonExecution,
+  normalizeCodexTurnUsage,
+};