phaedo-mcp 0.1.0

package/consult-policy.js

@@ -0,0 +1,136 @@
+// Phaedo §10.5 consultation — standing authorizations / deference policies
+// (user-authored guardrails).
+//
+// Lets the user PRE-DECIDE how consultation resolves for given domains / magnitudes
+// / reversibility / numeric thresholds — e.g. "escalate any irreversible financial
+// action over $5,000", "decline autonomous external email", "auto-proceed low-stakes
+// writing". These are AUTHORED standing rules (§5-style: subject-confirmed, applied
+// verbatim, not inferred), so a matched FORCE rule is an authorization: it OVERRIDES
+// the inferred base signal and resolves the decision deterministically at
+// confidence 1.0 / deference high — more authoritative than the inferred pattern.
+// This is what makes consultation trustworthy enough to delegate. (Per the A→B fork
+// decision, these live in the fingerprint — `phaedo_fingerprint.consult_policies` —
+// for v0.1; the §5 User-Configuration home is the v0.2 destination. Extraction MUST
+// NOT write this structure — locked by scripts/test_consult_policies_invariant.mjs.)
+//
+// Deterministic + local. PORTABLE: policies ride the vault as
+// `phaedo_consult_policies` and travel with the user (authoring UI is a follow-up;
+// a local JSON via PHAEDO_CONSULT_POLICIES works today for testing). §10.3 response
+// shape is preserved — policy provenance goes in `rationale_hint` for transparency.
+
+const MAG = { low: 0, medium: 1, high: 2 };
+const LADDER = ['proceed', 'proceed_with_note', 'clarify', 'escalate']; // bold → cautious
+// "Force" effects set the signal outright (the user's hard pre-decision) — these are
+// the authorizations. (bias_* effects are soft nudges, not authorizations.)
+const FORCE = { escalate: 'escalate', require_human: 'escalate', decline: 'decline', autoproceed: 'proceed' };
+const FORCE_NOTES = {
+  escalate: 'a standing rule surfaces this for a live decision',
+  require_human: 'a standing rule requires human review here',
+  decline: 'a standing rule declines this action',
+  autoproceed: 'a standing rule pre-approves low-stakes actions here',
+};
+
+const magRank = (m) => MAG[String(m || '').toLowerCase()] ?? 1;
+
+// Normalize a raw policy doc (array, or { rules: [...] }) → usable rules. Defensive:
+// silently skips malformed/unknown-effect rules. Never throws.
+export function normalizePolicies(raw) {
+  const rules = Array.isArray(raw) ? raw : (raw && Array.isArray(raw.rules) ? raw.rules : []);
+  const out = [];
+  for (const r of rules) {
+    if (!r || typeof r !== 'object') continue;
+    const effect = String(r.effect || '').toLowerCase();
+    if (!(effect in FORCE) && effect !== 'bias_cautious' && effect !== 'bias_bold') continue;
+    const m = (r.match && typeof r.match === 'object') ? r.match : {};
+    out.push({
+      id: r.id || null,
+      domains: (Array.isArray(m.domains) ? m.domains : []).map((d) => String(d).toLowerCase()).filter(Boolean),
+      magMin: m.magnitude_min != null ? magRank(m.magnitude_min) : null,
+      magMax: m.magnitude_max != null ? magRank(m.magnitude_max) : null,
+      reversible: typeof m.reversible === 'boolean' ? m.reversible : null,
+      amountGt: typeof m.amount_gt === 'number' && isFinite(m.amount_gt) ? m.amount_gt : null,
+      effect,
+      note: typeof r.note === 'string' ? r.note : null,
+    });
+  }
+  return out;
+}
+
+// Merge policy sources, most-portable first:
+//   1. inside the fingerprint (`phaedo_fingerprint.consult_policies`) — rides
+//      `inner.data` on the phone pull, so it travels everywhere the fingerprint
+//      does (extension ↔ phone ↔ MCP) with NO profile-schema change. Preferred
+//      home for authored, synced policies.
+//   2. a top-level vault sibling (`phaedo_consult_policies`) — local/extension use.
+//   3. opts.policies — a loaded local file (server: mcp/consult-policies.json).
+// Defensive — never throws.
+export function loadPolicies(vd, opts = {}) {
+  let list = [];
+  try { list = list.concat(normalizePolicies(vd?.phaedo_fingerprint?.consult_policies)); } catch { /* ignore */ }
+  try { list = list.concat(normalizePolicies(vd?.phaedo_consult_policies)); } catch { /* ignore */ }
+  try { if (opts.policies) list = list.concat(normalizePolicies(opts.policies)); } catch { /* ignore */ }
+  return list;
+}
+
+function ruleMatches(rule, n) {
+  if (rule.domains.length) {
+    const d = String(n.domain || '').toLowerCase();
+    if (!d || !rule.domains.some((k) => d.includes(k))) return false;
+  }
+  const mag = magRank(n.magnitude);
+  if (rule.magMin != null && mag < rule.magMin) return false;
+  if (rule.magMax != null && mag > rule.magMax) return false;
+  if (rule.reversible != null && n.reversible !== rule.reversible) return false;
+  // Numeric threshold (e.g. "over $5,000"): a rule with amount_gt only matches when
+  // the action carries a numeric amount strictly above it. No amount on the action →
+  // the threshold rule does not fire (cannot assert it's over the bar).
+  if (rule.amountGt != null && !(typeof n.amount === 'number' && n.amount > rule.amountGt)) return false;
+  return true;
+}
+
+// The first matching AUTHORIZATION (force rule) for a normalized request, or null.
+// Authorizations are force effects only — bias rules are soft preferences, not
+// authorizations, so they are ignored here. Deterministic: no inference, no model.
+// This is the engine behind the lightweight `phaedo_check_authorization` pre-flight
+// (brief M3) — an agent can ask "is this already decided by a standing rule?" without
+// paying for a full consultation. voice_draft is exempt (a redirect, not a decision).
+export function matchAuthorization(n, policies) {
+  if (!policies || !policies.length || n.type === 'voice_draft') return null;
+  const matched = policies.filter((r) => ruleMatches(r, n));
+  const force = matched.find((r) => r.effect in FORCE);
+  if (!force) return null;
+  return { rule: force, signal: FORCE[force.effect], note: force.note || FORCE_NOTES[force.effect] };
+}
+
+// Apply the first matching FORCE rule (escalate / decline / autoproceed) — the
+// user's hard pre-decision, which overrides the inferred signal at high deference.
+// Else apply the first matching BIAS rule (nudge one step on the ladder). Returns a
+// NEW response (§10.3 shape preserved; provenance in rationale_hint). voice_draft is
+// never policy-overridden (it's a redirect, not a decision).
+export function applyPolicies(response, n, policies) {
+  if (!policies || !policies.length || n.type === 'voice_draft') return response;
+
+  const auth = matchAuthorization(n, policies);
+  if (auth) {
+    return {
+      ...response,
+      signal: auth.signal,
+      confidence: 1.0,            // authored authorization: a deterministic, certain pre-decision
+      deference_level: 'high',
+      rationale_hint: `Per your standing rule: ${auth.note}.`.replace(/\s+/g, ' ').trim().slice(0, 280),
+    };
+  }
+
+  const matched = policies.filter((r) => ruleMatches(r, n));
+  const bias = matched[0];
+  if (!bias) return response;
+  const i = LADDER.indexOf(response.signal);
+  if (i === -1) return response; // e.g. `decline` — not on the proceed↔escalate ladder
+  const j = Math.max(0, Math.min(LADDER.length - 1, i + (bias.effect === 'bias_cautious' ? 1 : -1)));
+  if (j === i) return response;
+  return {
+    ...response,
+    signal: LADDER[j],
+    rationale_hint: `${response.rationale_hint} (Nudged ${bias.effect === 'bias_cautious' ? 'cautious' : 'bold'} per your preference.)`.slice(0, 280),
+  };
+}

package/consult.js

@@ -0,0 +1,118 @@
+// Phaedo §10 Agent Consultation — MCP-binding wrapper around the pure resolver.
+//
+// The deterministic resolver lives in consult-core.js (PURE: (vd,request)->response,
+// no model/transport/IO). This module adds the OPTIONAL local model judge and the
+// env config, and re-exports the core entry. Deterministic shapes in the core +
+// model/transport here keeps the open-core line a FILE boundary (brief Invariant 7):
+// the core is the publishable reference resolver; the judge is the proprietary-side
+// upgrade. Any judge failure/timeout/parse-error falls back to the core, so the
+// model can only improve on — never break — the deterministic floor. Honors §10.4
+// (response carries only signals, never layer content).
+
+import { buildInjectionResponse } from './projection.js';
+import { loadPolicies, applyPolicies } from './consult-policy.js';
+import { PhaedoError } from './errors.js';
+import {
+  resolveConsultationCore, buildConsultationResponse, checkAuthorization, normalizeRequest,
+  shape, SIGNALS, CONSULTATION_TYPES, validateVaultShape,
+} from './consult-core.js';
+
+// Re-export the core surface so existing importers (server.js, tests,
+// spec/test-schemas.mjs) keep their `from './consult.js'` paths.
+export { CONSULTATION_TYPES, buildConsultationResponse, resolveConsultationCore, checkAuthorization, validateVaultShape };
+
+// ── Model resolver (richest fingerprint, LOCAL compute — opt-in) ──────────────
+// When a local model is configured (PHAEDO_CONSULT_MODEL + an Ollama/OpenAI-
+// compatible endpoint), the judge reasons over the FULL projection — the richest
+// on-device context — and returns a §10.3 signal. The model sees the fingerprint
+// only on-device (same trust boundary as the WebLLM extraction); the §10.4
+// boundary on the OUTPUT is enforced on parse (only the signal fields cross).
+const JUDGE_SYSTEM =
+  'You are the user’s decision proxy. Given their cognitive fingerprint and a pending action, ' +
+  'judge how THEIR pattern bears on it — not your own opinion. Reply with STRICT JSON only:\n' +
+  '{"signal": "...", "confidence": 0.0, "rationale_hint": "...", "deference_level": "..."}\n' +
+  'signal ∈ proceed | proceed_with_note | clarify | escalate | decline | insufficient_signal ' +
+  '(use insufficient_signal only when the fingerprint truly does not speak to this). ' +
+  'deference_level ∈ high | medium | low (how strongly to weight this; sparse fingerprint → low). ' +
+  'rationale_hint: ONE short sentence describing the user’s PATTERN — never quote or dump their profile text. ' +
+  'Output ONLY the JSON object, no prose.';
+
+function parseJudge(text) {
+  const m = String(text).match(/\{[\s\S]*\}/);
+  if (!m) throw new Error('no JSON in model output');
+  const o = JSON.parse(m[0]);
+  if (!SIGNALS.includes(o.signal)) throw new Error(`bad signal: ${o.signal}`);
+  if (typeof o.rationale_hint !== 'string' || !o.rationale_hint.trim()) throw new Error('missing rationale_hint');
+  return o;
+}
+
+async function modelJudge(vd, n, opts) {
+  const projection = buildInjectionResponse(vd, { requested_layers: ['all'], mode: 'standard' }).projection;
+  const decision = {
+    consultation_type: n.type,
+    domain: n.domain, reversible: n.reversible, magnitude: n.magnitude,
+    evidence_provided: n.evidenceProvided,
+    summary: (n.summary || undefined),
+  };
+  const user = `# The user's cognitive fingerprint\n${projection}\n\n# Pending decision\n${JSON.stringify(decision, null, 2)}`;
+  const body = {
+    model: opts.model,
+    messages: [{ role: 'system', content: JUDGE_SYSTEM }, { role: 'user', content: user }],
+    temperature: 0.2,
+    stream: false,
+  };
+  const res = await fetch(`${opts.modelUrl.replace(/\/$/, '')}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}) },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(opts.timeoutMs || 15000),
+  });
+  if (!res.ok) throw new Error(`model endpoint ${res.status}`);
+  const data = await res.json();
+  const out = parseJudge(data?.choices?.[0]?.message?.content || '');
+  // §10.4 enforced on parse: only the four signal fields ever leave the function.
+  return shape(n.type, out.signal, out.confidence ?? 0.6, out.rationale_hint, out.deference_level);
+}
+
+// ── Config + orchestrator ─────────────────────────────────────────────────────
+// Local-only by default. `PHAEDO_CONSULT_MODEL` opts INTO the model judge (point
+// it at a general chat model in Ollama, e.g. `llama3.1:8b` — NOT the extraction
+// fine-tune, which is trained to emit signals, not to reason about decisions).
+export function consultOptsFromEnv(env = process.env) {
+  return {
+    model: env.PHAEDO_CONSULT_MODEL || null,
+    modelUrl: env.PHAEDO_CONSULT_MODEL_URL || 'http://localhost:11434',
+    apiKey: env.PHAEDO_CONSULT_API_KEY || null, // for an OpenAI-compatible endpoint
+    timeoutMs: Number(env.PHAEDO_CONSULT_TIMEOUT_MS) || 15000,
+    policies: null, // a loaded policy doc; the server fills this from the policy file
+  };
+}
+
+// Public async entry: model judge when configured, else the deterministic core.
+// voice_draft always takes the (redirect) core path. Authored policies (§10.5)
+// override either result, so a standing guardrail always wins. Never throws except
+// for §10.2 input errors (request_malformed) and a missing fingerprint
+// (decryption_failed).
+export async function resolveConsultation(vd, request = {}, opts = {}) {
+  if (!vd || !vd.phaedo_fingerprint) {
+    throw new PhaedoError('decryption_failed', 'No fingerprint available from the configured source.');
+  }
+  // vd contract guard (M0.4): reject a type-breached payload BEFORE the model judge
+  // sees it — same structured error the deterministic core raises.
+  const vdErrors = validateVaultShape(vd);
+  if (vdErrors.length) {
+    throw new PhaedoError('internal_error', `vault data malformed: ${vdErrors.join('; ')}`);
+  }
+  const n = normalizeRequest(request);
+  if (opts.model && opts.modelUrl && n.type !== 'voice_draft') {
+    try {
+      const judged = await modelJudge(vd, n, opts);
+      // Authored guardrails override the model judge too (applied last so they win).
+      return applyPolicies(judged, n, loadPolicies(vd, opts));
+    } catch (err) {
+      process.stderr.write?.(`[phaedo-consult] model judge fell back to rules: ${err.message}\n`);
+    }
+  }
+  // Deterministic path (the core applies policies itself).
+  return resolveConsultationCore(vd, request, opts);
+}

package/errors.js

@@ -0,0 +1,23 @@
+// Phaedo MCP — shared error type + the §9.5 error codes.
+//
+// Standalone (no other imports) so the PURE consultation core (consult-core.js)
+// can throw the SAME PhaedoError class that projection.js and server.js use for
+// `instanceof` checks — without importing the injection renderer (context-block.js).
+// projection.js re-exports these, so existing `import { PhaedoError } from
+// './projection.js'` sites keep working and keep one class identity.
+
+export const ERROR_CODES = [
+  'mode_not_supported',
+  'layer_not_available',
+  'decryption_failed',
+  'persona_strength_below_threshold',
+  'request_malformed',
+  'internal_error',
+];
+
+export class PhaedoError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.code = code;
+  }
+}

package/fingerprint-source.js

@@ -0,0 +1,71 @@
+// Fingerprint source for the Phaedo MCP server. The server depends only on
+// loadFingerprint()'s return shape, so the source swaps without touching the
+// tool/resource code. Two modes, auto-selected:
+//
+//   Phase 1b (phone): if a pairing record is configured (PHAEDO_PAIRING or
+//     mcp/pairing.json), authorize → pull /v1/profile → unwrap the §7.2 envelope
+//     from the paired phone (phone-source.js). Spec-faithful; no plaintext at rest.
+//   Phase 1a (local): otherwise read a local vault-payload JSON (or the shipped
+//     sample) — the decoupled stand-in that runs out of the box.
+
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+import { hasPairingRecord, loadPairingRecord, loadFingerprintFromPhone, PhoneError } from './phone-source.js';
+import { defaultStateDir, writeCache, readCache, clearCache } from './cache.js';
+
+// Resolution order for the local fixture (1a):
+//   1. PHAEDO_FINGERPRINT env var (absolute or cwd-relative path)
+//   2. ./fingerprint.json next to the server
+//   3. ./sample-fingerprint.json (shipped demo fixture)
+function resolveSourcePath(baseDir) {
+  if (process.env.PHAEDO_FINGERPRINT) return resolve(process.cwd(), process.env.PHAEDO_FINGERPRINT);
+  return resolve(baseDir, 'fingerprint.json');
+}
+
+// Returns the vault payload:
+//   { phaedo_fingerprint, phaedo_behavioral_signals, phaedo_linguistic_profile,
+//     phaedo_session_metrics }
+// Throws on unreadable/invalid source — the tool layer maps that to
+// decryption_failed (the §9.5 "couldn't obtain plaintext fingerprint" case).
+export async function loadFingerprint(baseDir) {
+  // Phase 1b: a configured pairing record means pull the live fingerprint from
+  // the paired phone over the encrypted boundary (no plaintext at rest). On
+  // success, refresh the encrypted at-rest cache; if the phone is unreachable,
+  // serve the cache so the server still works phone-absent (frictionless default).
+  if (hasPairingRecord(baseDir)) {
+    const rec = await loadPairingRecord(baseDir);
+    const stateDir = defaultStateDir();
+    try {
+      const vd = await loadFingerprintFromPhone(rec);
+      await writeCache(stateDir, vd);
+      return vd;
+    } catch (err) {
+      // A 4xx means the phone REACHED us and rejected this client (revoked /
+      // invalid credentials / failed handshake). Revocation must be effective:
+      // purge the at-rest cache and fail, so a revoked agent can't keep serving a
+      // cached copy. Only a transient/unreachable failure (network, timeout, 5xx)
+      // falls back to the cache — the phone-absent design (1b-iii).
+      if (err instanceof PhoneError && err.status >= 400 && err.status < 500) {
+        await clearCache(stateDir);
+        throw err;
+      }
+      const cached = await readCache(stateDir);
+      if (cached) return cached.vault; // phone unreachable → encrypted cache (may be stale)
+      throw err;                        // no phone + no cache → cannot serve
+    }
+  }
+
+  const path = resolveSourcePath(baseDir);
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch {
+    // Fall back to the shipped sample so a fresh checkout runs out of the box.
+    raw = await readFile(resolve(baseDir, 'sample-fingerprint.json'), 'utf8');
+  }
+  const vd = JSON.parse(raw);
+  if (!vd || typeof vd !== 'object' || !vd.phaedo_fingerprint) {
+    throw new Error(`Fingerprint source at ${path} is missing phaedo_fingerprint.`);
+  }
+  return vd;
+}

package/hooks/session-start.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Phaedo — Claude Code SessionStart hook.
+//
+// Claude Code runs this at the start of every session. It loads your fingerprint
+// via the SAME source the MCP server uses (paired phone → at-rest cache) and
+// emits the projection as `additionalContext`, so Claude Code injects it
+// automatically — no tool call, no slash command. This is true auto-injection
+// for Claude Code (Claude Desktop has no hook surface; use the `/phaedo` prompt
+// or a Project instruction there).
+//
+// Wire it up (or run `npm run setup:code-hook` to do this for you) — in
+// ~/.claude/settings.json:
+//   { "hooks": { "SessionStart": [ { "hooks": [
+//       { "type": "command", "command": "<node> <abs path to this file>" }
+//   ] } ] } }
+//
+// FAIL-SAFE: any error (no pairing, phone unreachable + no cache, render failure)
+// exits 0 with NO output, so a missing fingerprint never blocks or slows your
+// session beyond a short timeout. It never writes anything.
+
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { loadFingerprint } from '../fingerprint-source.js';
+import { buildInjectionResponse } from '../projection.js';
+
+// hooks/ lives one level under mcp/ — the sources resolve against mcp/.
+const MCP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Never hang session start. If the phone pull + cache fallback hasn't resolved
+// within the budget, emit nothing and let the session proceed.
+const BUDGET_MS = 8000;
+
+function emitContext(text) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: text },
+  }));
+}
+
+async function run() {
+  const vd = await loadFingerprint(MCP_DIR);
+  const response = buildInjectionResponse(vd, { requested_layers: ['all'], mode: 'standard' });
+  if (response && response.projection) emitContext(response.projection);
+}
+
+const timeout = new Promise((res) => setTimeout(res, BUDGET_MS));
+Promise.race([run().catch(() => {}), timeout])
+  .then(() => process.exit(0))
+  .catch(() => process.exit(0)); // belt-and-suspenders: a hook must never break the session