phaedo-mcp 0.2.1 → 0.3.0

package/receipts-sync.js

@@ -0,0 +1,197 @@
+// §10.6 receipts audit channel — MCP ↔ phone transport (G1+G2).
+//
+// Closes the act-as-me learning loop: today receipts written by `phaedo_consult` /
+// `phaedo_escalate` sit at `user_action: null` until the subject runs `node receipts.js
+// mark` — a dev CLI only. This module puts the audit on the subject's PHONE so they can
+// mark outcomes in the flow, which then feeds delegation learning (consult-core.js
+// `deriveDelegationSignals`).
+//
+// Two directions over the existing fp-mailbox transport (relay/mailbox.js):
+//
+//   agent_to_phone  — MCP deposits a digest of the latest UNMARKED receipts (a single
+//                     payload with at most N entries, last-write-wins idempotent: the
+//                     phone always sees the latest snapshot). §10.4-safe: only the
+//                     fields the phone needs to render — receipt_id, created_at, via,
+//                     agent_id, action_descriptor, response.signal — never `drivers`
+//                     (local provenance) and never layer content.
+//   phone_to_agent  — phone deposits a BATCH of `{ receipt_id, outcome }`; this module
+//                     drains and calls `markOutcome` per mark. Idempotent on the MCP
+//                     side (re-marking the same outcome is a no-op), so re-draining is
+//                     safe and the phone need not track per-mark ACKs — the next
+//                     receipts digest reflects applied marks (`user_action` set).
+//
+// Crypto: fp_sync_key derived from this server's pair_key. Drained by the PHONE, whose
+// multi-client loop tries each verified client's key — so independent pairing is fine
+// here (unlike agent_to_ext, see delegation-sync.js). The relay only ever sees
+// ciphertext. Best-effort and isolated:
+// a deposit/drain failure must NEVER break the tool that triggered it.
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+import { readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
+import { agreementDigest } from './agreement.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+const DIGEST_CAP    = 50;   // phone shows recent N — enough for the latest sittings, bounded payload
+
+export function relayBaseFromEnv(env = process.env) {
+  return env.PHAEDO_RELAY || DEFAULT_RELAY;
+}
+
+// Strip a receipt down to the §10.4-safe fields the phone renders. NEVER includes
+// `drivers` (local provenance cues that would expose Decision&Risk reasoning to the
+// subject device — fine on this device, but the audit UI doesn't need them and not
+// shipping them keeps the digest small + the boundary tight).
+function digestFields(r) {
+  if (!r || typeof r !== 'object') return null;
+  return {
+    receipt_id:  r.receipt_id,
+    created_at:  r.created_at,
+    via:         r.via,
+    agent_id:    r.agent_id || null,
+    // The paired client that actually SERVED the call, beside the vendor string it
+    // claimed. §10.4-safe (an opaque id the subject's own phone issued, not persona
+    // content) and the phone is the one surface that can render it usefully: it holds
+    // the client registry, so it can show the friendly NAME where the receipt holds
+    // only the id. Without it the Activity screen can only report what the agent said
+    // it was — which is precisely the claim §10.5 stopped trusting.
+    client_id:   r.client_id || null,
+    request: {
+      consultation_type: r?.request?.consultation_type || null,
+      action_descriptor: {
+        domain:     r?.request?.action_descriptor?.domain     ?? null,
+        reversible: r?.request?.action_descriptor?.reversible ?? null,
+        magnitude:  r?.request?.action_descriptor?.magnitude  ?? null,
+        amount:     r?.request?.action_descriptor?.amount     ?? null,
+        summary:    r?.request?.action_descriptor?.summary    ?? null,
+      },
+    },
+    response: {
+      signal:          r?.response?.signal          ?? null,
+      deference_level: r?.response?.deference_level ?? null,
+    },
+    user_action: r.user_action ?? null,   // already-marked entries stay visible (phone shows status)
+  };
+}
+
+// Pure-crypto: take the local receipts list, build a §10.4-safe digest of the most
+// recent `cap` entries, and seal it under fp_sync_key. Returns `{ envelope }` — the
+// same shape `agent_to_ext` (delegation-sync) uses, so the relay's mailbox accepts it.
+export async function buildReceiptsDeposit(pairKeyB64u, receipts, { cap = DIGEST_CAP, now = () => new Date().toISOString() } = {}) {
+  const list = Array.isArray(receipts) ? receipts : [];
+  // Most-recent N (receipts are append-only, ordered by creation in the store).
+  const head = list.slice(-cap).map(digestFields).filter(Boolean);
+  // Agreement rides the SAME digest, but is computed over the WHOLE store, not the
+  // capped head — the rate is a 30-day property of the subject's history, and slicing
+  // it to the last 50 entries would silently redefine the metric.
+  const generatedAt = now();
+  const agreementAt = Date.parse(generatedAt);
+  const agreement = agreementDigest(list, { now: Number.isFinite(agreementAt) ? agreementAt : Date.now() });
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: 'receipts_digest', data: { receipts: head, agreement, generated_at: generatedAt } };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'receipts_digest', created_at: now() });
+    plaintext.fill(0);
+    return { envelope };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Decrypt a phone-deposited marks payload. Returns `{ marks: [{receipt_id, outcome}, ...] }`
+// or null on a malformed/wrong-key envelope. Pure (no I/O) so it's testable.
+export async function parseMarksDeposit(pairKeyB64u, envelope) {
+  if (!envelope) return null;
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try { fpSyncKey = await Kdf.deriveFpSyncKey(pairKey); }
+  finally { pairKey.fill(0); }
+  try {
+    const plaintext = await Envelope.unwrap(envelope, fpSyncKey);
+    let inner;
+    try { inner = JSON.parse(new TextDecoder().decode(plaintext)); }
+    finally { if (plaintext.fill) plaintext.fill(0); }
+    if (!inner || inner.kind !== 'receipt_marks' || !inner.data) return null;
+    const arr = Array.isArray(inner.data.marks) ? inner.data.marks : [];
+    return {
+      marks: arr
+        .map((m) => ({
+          receipt_id: typeof m?.receipt_id === 'string' ? m.receipt_id : null,
+          outcome:    typeof m?.outcome    === 'string' ? m.outcome    : null,
+        }))
+        .filter((m) => m.receipt_id && USER_ACTIONS.includes(m.outcome)),
+    };
+  } catch {
+    return null;
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Deposit a receipts digest to the relay's agent_to_phone slot. Best-effort; mirrors
+// `depositDelegationSuggestions` exactly (same auth, same timeout, same isolation —
+// a failure NEVER throws out into the consult/escalate path that called us).
+export async function depositReceiptsDigest(pairing, receipts, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const list = Array.isArray(receipts) ? receipts : [];
+  if (!list.length) return { deposited: false, reason: 'no-receipts' };
+  if (!pairing || !pairing.pair_key) return { deposited: false, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { deposited: false, reason: 'no-relay-device-id' };
+  try {
+    const body = await buildReceiptsDeposit(pairing.pair_key, list, deps);
+    const url = `${deps.relayBase || relayBaseFromEnv()}/fp-mailbox/${encodeURIComponent(pairing.relay_device_id)}/agent_to_phone`;
+    const authHeader = pairing.relay_device_secret
+      ? { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` }
+      : {};
+    const res = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...authHeader },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.timeoutMs || 8000),
+    });
+    return { deposited: !!(res && res.ok), status: res && res.status, count: list.length };
+  } catch (e) {
+    return { deposited: false, reason: String(e && e.message || e) };
+  }
+}
+
+// Drain phone-deposited outcome marks from the phone_to_agent slot and apply each via
+// markOutcome (idempotent). Returns `{ applied, skipped }`. Best-effort; a transport
+// failure returns `{ applied: 0, skipped: 0, reason }` instead of throwing.
+export async function drainAndApplyMarks(pairing, stateDir, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key) return { applied: 0, skipped: 0, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { applied: 0, skipped: 0, reason: 'no-relay-device-id' };
+  try {
+    const url = `${deps.relayBase || relayBaseFromEnv()}/fp-mailbox/${encodeURIComponent(pairing.relay_device_id)}/phone_to_agent`;
+    const authHeader = pairing.relay_device_secret
+      ? { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` }
+      : {};
+    const res = await fetchFn(url, {
+      method: 'GET',
+      headers: authHeader,
+      signal: AbortSignal.timeout(deps.timeoutMs || 8000),
+    });
+    if (!res || !res.ok) return { applied: 0, skipped: 0, status: res && res.status };
+    const body = await res.json().catch(() => null);
+    const parsed = await parseMarksDeposit(pairing.pair_key, body && body.envelope);
+    if (!parsed) return { applied: 0, skipped: 0, reason: 'no-marks' };
+    let applied = 0, skipped = 0;
+    for (const m of parsed.marks) {
+      try {
+        const r = await markOutcome(stateDir, m.receipt_id, m.outcome);
+        if (r.matched) applied++; else skipped++;
+      } catch { skipped++; }
+    }
+    return { applied, skipped, total: parsed.marks.length };
+  } catch (e) {
+    return { applied: 0, skipped: 0, reason: String(e && e.message || e) };
+  }
+}

package/receipts.js

@@ -21,11 +21,13 @@
 // resolver core stays pure (no I/O). Receipt-write failure must never break the
 // consultation itself (the server warns on stderr and still answers).
 
-import { mkdir, readFile, writeFile, chmod } from 'fs/promises';
+import { mkdir, readFile, writeFile, chmod, rename } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { Phaedo, b64uEnc, b64uDec } from './lib/phaedo-crypto.js';
+import { canonicalDomain } from './lib/domain.js';
 import { getOrCreateCacheKey, defaultStateDir } from './cache.js';
+import { normalizeActionBinding } from './action-binding.js';
 
 const { Envelope } = Phaedo;
 
@@ -78,8 +80,26 @@ async function writeStore(stateDir, store, now) {
   });
   plaintext.fill(0);
   const p = storePath(stateDir);
-  await writeFile(p, JSON.stringify({ envelope }), { mode: 0o600 });
-  await chmod(p, 0o600);
+  // Atomic replace: write a temp file then rename over the live store. Receipts are
+  // the ONLY copy (readStore throws on a corrupt store) — a crash mid-write must not
+  // truncate/corrupt receipts.enc and brick the audit trail + every markOutcome.
+  const tmp = `${p}.tmp`;
+  await writeFile(tmp, JSON.stringify({ envelope }), { mode: 0o600 });
+  await chmod(tmp, 0o600);
+  await rename(tmp, p);   // atomic on POSIX
+}
+
+// Serialize store mutations per state dir. MCP tool handlers are async and NOT
+// serialized by the SDK, so a concurrent appendReceipt (phaedo_consult) and
+// markOutcome (phaedo_record_outcome/escalation_status) both read the same snapshot
+// and the second write clobbers the first — a lost receipt or lost outcome mark.
+// A per-stateDir promise chain forces read-modify-write to run one at a time.
+const _storeLocks = new Map();
+function withStoreLock(stateDir, fn) {
+  const prev = _storeLocks.get(stateDir) || Promise.resolve();
+  const next = prev.then(fn, fn);                 // run regardless of the prior result
+  _storeLocks.set(stateDir, next.then(() => {}, () => {}));  // a rejection must not break the chain
+  return next;
 }
 
 // Build the §10.6 receipt object from a resolved consultation. Pure. Captures the
@@ -87,11 +107,17 @@ async function writeStore(stateDir, store, now) {
 // never the projection (§10.4 holds inside the vault too). `via` records which
 // tool resolved it (phaedo_consult | phaedo_check_authorization) so M5 can weigh
 // full consultations and pre-flight matches separately.
-export function buildReceipt({ via, agentId, request, response, drivers, now = Date.now() }) {
+export function buildReceipt({ via, agentId, clientId, request, response, drivers, now = Date.now() }) {
   const ad = (request && typeof request.action_descriptor === 'object' && request.action_descriptor) || {};
   // Provenance (optional, §10.4-safe — LOCAL audit only): the Decision&Risk cues that
   // drove an inferred consult, each {cue, lean?/value?, confidence, basis}. No layer
   // text; coerced to the known shape; absent for deterministic pre-flights.
+  // Defensive: a malformed binding must not fail the receipt write (a receipt-write
+  // failure must never break the consultation — §10.6). The resolver has already
+  // rejected structurally-bad bindings with `request_malformed`, so anything that
+  // throws here is a caller bypassing it; record nothing rather than half of it.
+  let bnd = null;
+  try { bnd = normalizeActionBinding(request?.action_binding); } catch { bnd = null; }
   const drv = Array.isArray(drivers) ? drivers.slice(0, 16).map((d) => ({
     cue: typeof d?.cue === 'string' ? d.cue : null,
     ...(typeof d?.lean === 'number' ? { lean: d.lean } : {}),
@@ -103,16 +129,33 @@ export function buildReceipt({ via, agentId, request, response, drivers, now = D
     receipt_id: crypto.randomUUID(),
     created_at: new Date(now).toISOString(),
     via: via || 'phaedo_consult',
+    // WHO CLAIMED to be calling. Self-asserted, unverified, and never a gate — the
+    // same standing `action_descriptor` was given in v0.1.48. Audit label only.
     agent_id: typeof agentId === 'string' ? agentId : null,
+    // WHO ACTUALLY SERVED the call: this server's own paired-client id, established
+    // out-of-band with the phone under a user-verified SAS. This is the identity
+    // §10.5 `agents` scoping matches on, so the audit can distinguish which paired
+    // client acted from whichever vendor string it chose to claim. Null = unpaired.
+    client_id: typeof clientId === 'string' && clientId ? clientId : null,
     request: {
       consultation_type: request?.consultation_type || 'action_approval',
       action_descriptor: {
-        domain: typeof ad.domain === 'string' ? ad.domain : null,
+        // Canonical form, matching what the resolver reasoned about (lib/domain.js).
+        // The receipt is the evidence store the promotion tallies key on, so a raw
+        // `"Finance"` here would be a class of its own and split the subject's
+        // approvals away from `"finance"`.
+        domain: typeof ad.domain === 'string' ? (canonicalDomain(ad.domain) || null) : null,
         reversible: typeof ad.reversible === 'boolean' ? ad.reversible : null,
         magnitude: typeof ad.magnitude === 'string' ? ad.magnitude : null,
         amount: typeof ad.amount === 'number' ? ad.amount : null,
         summary: typeof ad.summary === 'string' ? ad.summary.slice(0, 500) : null,
       },
+      // §10.2 binding: the concrete call the descriptor above CLAIMS to describe.
+      // This is the field that makes a descriptor/action mismatch provable later —
+      // the descriptor is the agent's story, this is what it said it would run.
+      // Never the arguments themselves: a digest, the tool name, and at most a
+      // short human preview.
+      ...(bnd ? { action_binding: bnd } : {}),
     },
     response: {
       signal: response?.signal ?? null,
@@ -126,11 +169,13 @@ export function buildReceipt({ via, agentId, request, response, drivers, now = D
 
 // Append one receipt; evict oldest beyond the cap. Returns the stored receipt.
 export async function appendReceipt(stateDir, receipt, { cap = DEFAULT_CAP, now = Date.now() } = {}) {
-  const store = await readStore(stateDir);
-  store.receipts.push(receipt);
-  if (store.receipts.length > cap) store.receipts.splice(0, store.receipts.length - cap);
-  await writeStore(stateDir, store, now);
-  return receipt;
+  return withStoreLock(stateDir, async () => {
+    const store = await readStore(stateDir);
+    store.receipts.push(receipt);
+    if (store.receipts.length > cap) store.receipts.splice(0, store.receipts.length - cap);
+    await writeStore(stateDir, store, now);
+    return receipt;
+  });
 }
 
 // The ONE permitted mutation (§10.6): set user_action on an existing receipt.
@@ -139,12 +184,20 @@ export async function updateUserAction(stateDir, receiptId, action, { now = Date
   if (!USER_ACTIONS.includes(action)) {
     throw new Error(`user_action must be one of: ${USER_ACTIONS.join(', ')}`);
   }
-  const store = await readStore(stateDir);
-  const r = store.receipts.find((x) => x.receipt_id === receiptId);
-  if (!r) return false;
-  r.user_action = action;
-  await writeStore(stateDir, store, now);
-  return true;
+  return withStoreLock(stateDir, async () => {
+    const store = await readStore(stateDir);
+    const r = store.receipts.find((x) => x.receipt_id === receiptId);
+    if (!r) return false;
+    r.user_action = action;
+    // WHEN the outcome was recorded, alongside WHAT it was. Not decision latency —
+    // the subject may mark in a later sitting — but it does reveal a screenful of
+    // receipts stamped in one pass, which §10.7 autonomy promotion treats as
+    // bookkeeping rather than deliberate consent. Mutable with `user_action`, and
+    // only with it (§10.6: user_action is the sole mutable field; this is part of it).
+    r.user_action_at = new Date(now).toISOString();
+    await writeStore(stateDir, store, now);
+    return true;
+  });
 }
 
 // Decrypt and return all receipts (oldest first). The dev/harness read path — and