@animalabs/connectome-host 0.3.1

package/scripts/lib/line-reader.ts

@@ -0,0 +1,53 @@
+/**
+ * Stdin line reader using readline's 'line' event. Robust to piped input
+ * (Bun 1.3's readline.question / readline/promises.question hang at 99% CPU
+ * on subsequent calls when stdin is a pipe). Keep one reader instance alive
+ * for the whole script's main() — close/re-open per question is also flaky.
+ *
+ * Shared between scripts/evacuator.ts and scripts/import-claudeai-export.ts;
+ * if the upstream Bun bug ever gets fixed there is exactly one place to
+ * revert.
+ */
+import { createInterface } from 'node:readline';
+
+export interface LineReader {
+  nextLine(prompt?: string): Promise<string | null>;
+  close(): void;
+}
+
+export function createLineReader(): LineReader {
+  const buf: string[] = [];
+  let resolveNext: ((s: string | null) => void) | null = null;
+  let closed = false;
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  rl.on('line', (line: string) => {
+    if (resolveNext) {
+      const r = resolveNext;
+      resolveNext = null;
+      r(line);
+    } else {
+      buf.push(line);
+    }
+  });
+  rl.on('close', () => {
+    closed = true;
+    if (resolveNext) {
+      const r = resolveNext;
+      resolveNext = null;
+      r(null);
+    }
+  });
+  return {
+    nextLine(prompt?: string) {
+      if (prompt) process.stdout.write(prompt);
+      return new Promise<string | null>((resolve) => {
+        if (buf.length > 0) resolve(buf.shift()!);
+        else if (closed) resolve(null);
+        else resolveNext = resolve;
+      });
+    },
+    close() {
+      rl.close();
+    },
+  };
+}

package/scripts/test-historical-thinking.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+/**
+ * Probe whether Anthropic's API accepts historical thinking blocks without
+ * cryptographic signatures, when the current request has extended thinking
+ * enabled.
+ *
+ * Context: claude.ai web export contains thinking text but no signatures
+ * (claude.ai never plumbed signatures into the export pipeline). To resume
+ * those conversations via API with extended thinking on — preserving the
+ * model's cognitive mode — we need to know which of these the API tolerates:
+ *
+ *   case A: signature field omitted
+ *   case B: signature field empty string ""
+ *   case C: thinking wrapped as <recovered_thinking> text (control — must work)
+ *   case D: redacted_thinking block (alt encoding the API natively supports)
+ *
+ * Cases that succeed unlock the corresponding import strategy.
+ *
+ * Last run: 2026-05-13 against claude-sonnet-4-5-20250929. Results:
+ *   A_no_signature     → 400 invalid_request_error "signature: Field required"
+ *   B_empty_signature  → 400 invalid_request_error "Invalid `signature` in `thinking` block"
+ *   C_wrapped_text     → 200 OK; response itself contained native thinking
+ *   D_redacted_thinking → 400 invalid_request_error "Invalid `data` in `redacted_thinking`"
+ * Conclusion: signatures are server-generated HMACs, cryptographically validated,
+ * cannot be forged or stripped. Wrapped text is the only path that round-trips.
+ * Re-run if Anthropic loosens this in future API versions.
+ *
+ * Run: ANTHROPIC_API_KEY=sk-... bun scripts/test-historical-thinking.ts
+ */
+
+const API_KEY = process.env.ANTHROPIC_API_KEY;
+if (!API_KEY) {
+  console.error('Set ANTHROPIC_API_KEY');
+  process.exit(1);
+}
+
+const MODEL = process.env.MODEL ?? 'claude-sonnet-4-5-20250929';
+const ENDPOINT = 'https://api.anthropic.com/v1/messages';
+
+// A fabricated past turn: user asked something, assistant thought, then spoke.
+// This mirrors the shape of an exported claude.ai assistant message.
+const FAKE_PAST_THINKING =
+  'The user is asking about prime numbers. The smallest prime is 2 — sometimes ' +
+  'people forget 1 is not prime by convention. I should give the answer plainly.';
+const FAKE_PAST_TEXT = 'The smallest prime number is 2.';
+
+interface Case {
+  name: string;
+  description: string;
+  assistantBlocks: unknown[];
+}
+
+const CASES: Case[] = [
+  {
+    name: 'A_no_signature',
+    description: 'thinking block with signature field omitted entirely',
+    assistantBlocks: [
+      { type: 'thinking', thinking: FAKE_PAST_THINKING },
+      { type: 'text', text: FAKE_PAST_TEXT },
+    ],
+  },
+  {
+    name: 'B_empty_signature',
+    description: 'thinking block with signature: ""',
+    assistantBlocks: [
+      { type: 'thinking', thinking: FAKE_PAST_THINKING, signature: '' },
+      { type: 'text', text: FAKE_PAST_TEXT },
+    ],
+  },
+  {
+    name: 'C_wrapped_text_control',
+    description: 'recovered_thinking as wrapped text (must succeed)',
+    assistantBlocks: [
+      {
+        type: 'text',
+        text: `<recovered_thinking>${FAKE_PAST_THINKING}</recovered_thinking>\n\n${FAKE_PAST_TEXT}`,
+      },
+    ],
+  },
+  {
+    name: 'D_redacted_thinking',
+    description: 'redacted_thinking block (data field is base64-ish placeholder)',
+    assistantBlocks: [
+      { type: 'redacted_thinking', data: Buffer.from('unrecoverable').toString('base64') },
+      { type: 'text', text: FAKE_PAST_TEXT },
+    ],
+  },
+];
+
+async function runCase(c: Case): Promise<{ ok: boolean; status: number; body: string }> {
+  const body = {
+    model: MODEL,
+    max_tokens: 4096,
+    temperature: 1,
+    thinking: { type: 'enabled', budget_tokens: 1024 },
+    messages: [
+      { role: 'user', content: 'What is the smallest prime number?' },
+      { role: 'assistant', content: c.assistantBlocks },
+      { role: 'user', content: 'And what is the next one after that?' },
+    ],
+  };
+  const res = await fetch(ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'x-api-key': API_KEY!,
+      'anthropic-version': '2023-06-01',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  return { ok: res.ok, status: res.status, body: text };
+}
+
+function summarize(body: string, ok: boolean): string {
+  try {
+    const parsed = JSON.parse(body);
+    if (ok) {
+      const blocks = (parsed.content ?? []) as Array<{ type: string; text?: string }>;
+      const reply = blocks.find((b) => b.type === 'text')?.text ?? '<no text>';
+      const hadThinking = blocks.some((b) => b.type === 'thinking');
+      return `OK; reply=${JSON.stringify(reply.slice(0, 80))}; thinking_in_response=${hadThinking}`;
+    }
+    return `${parsed.error?.type ?? 'error'}: ${parsed.error?.message ?? body.slice(0, 200)}`;
+  } catch {
+    return body.slice(0, 200);
+  }
+}
+
+async function main() {
+  console.log(`Model: ${MODEL}\n`);
+  for (const c of CASES) {
+    process.stdout.write(`[${c.name}] ${c.description} ... `);
+    try {
+      const { ok, status, body } = await runCase(c);
+      console.log(`${ok ? 'PASS' : 'FAIL'} (${status}) — ${summarize(body, ok)}\n`);
+    } catch (err) {
+      console.log(`THROW — ${(err as Error).message}\n`);
+    }
+  }
+}
+
+if (import.meta.main) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}

package/scripts/warmup-session.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env bun
+/**
+ * Warmup a conhost session: drive its AutobiographicalStrategy to convergence
+ * before the session is opened for real continuation.
+ *
+ * Bulk-imported sessions (from claude.ai exports, etc.) land in Chronicle with
+ * thousands of raw messages and no L1/L2/L3 summaries. At runtime, autobio's
+ * uncompressed-fallback would emit everything raw at first compile, blowing
+ * the context window. This script pre-computes all summaries so the session
+ * is openable.
+ *
+ * Compression is driven by the same model used at conversation time
+ * (Sonnet 4.5 by default) — autobio's prompts are explicitly first-person
+ * ("describe it as you would to yourself"), so the summarizer is literally
+ * writing the friend's-Claude's own diary. Haiku here would be a different
+ * voice wearing the same name.
+ *
+ * Resumable: autobio persists its compression and merge queues to Chronicle.
+ * If interrupted, re-running this script picks up where it left off.
+ *
+ * Run:
+ *   bun scripts/warmup-session.ts <session-name-or-id>
+ *
+ * Options:
+ *   --data-dir <dir>   Conhost data dir (default: ./data)
+ *   --model <id>       Compression model (default: claude-sonnet-4-5-20250929)
+ *   --agent <name>     Participant name for assistant turns. If omitted,
+ *                      read from the import-source sidecar written by
+ *                      `import-claudeai-export.ts`; falls back to "Claude"
+ *                      if neither is available. MUST match the value the
+ *                      session was imported with — Membrane formats the
+ *                      assistant role by string-comparing message
+ *                      participants against this name.
+ *   --max-spend <usd>  Soft cap; halt gracefully if cost exceeds this
+ *   --l1-budget <n>    L1 budget tokens (passed to autobio)
+ *   --l2-budget <n>    Likewise L2
+ *   --l3-budget <n>    Likewise L3
+ *   --merge-threshold <n>  L1→L2 / L2→L3 merge threshold (default: 6)
+ */
+
+import { resolve } from 'node:path';
+import { JsStore } from '@animalabs/chronicle';
+import { ContextManager } from '@animalabs/context-manager';
+import { AutobiographicalStrategy } from '@animalabs/agent-framework';
+import { Membrane, AnthropicAdapter, type NormalizedResponse } from '@animalabs/membrane';
+import { SessionManager } from '../src/session-manager.js';
+import { resolveAgentName } from '../src/agent-name.js';
+
+// ---------------------------------------------------------------------------
+// Pricing (approximate, USD per 1M tokens). Used for the --max-spend gate
+// and the on-screen running cost.
+// Keep in sync with any canonical billing source if/when one is consolidated
+// (per memory: project_billing_tracker.md). Stale entries here only affect
+// the cost displayed during warmup; the actual spend is whatever Anthropic
+// charges.
+// ---------------------------------------------------------------------------
+
+const PRICING: Record<string, { input: number; output: number }> = {
+  'claude-sonnet-4-5-20250929': { input: 3.0, output: 15.0 },
+  'claude-opus-4-7': { input: 15.0, output: 75.0 },
+  'claude-haiku-4-5-20251001': { input: 0.8, output: 4.0 },
+};
+
+function priceOf(model: string): { input: number; output: number } {
+  return PRICING[model] ?? { input: 3.0, output: 15.0 };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+interface Opts {
+  sessionRef: string;
+  dataDir: string;
+  model: string;
+  /**
+   * Explicit `--agent <name>` from the CLI. When absent (undefined), the
+   * runner falls back to the session's import-source sidecar, then to
+   * "Claude". Distinguishing "not given" from "given as 'agent'" lets the
+   * sidecar (the durable record of what the importer wrote) override a
+   * stale default without overriding a deliberate operator choice.
+   */
+  agentName?: string;
+  maxSpend: number | null;
+  l1Budget?: number;
+  l2Budget?: number;
+  l3Budget?: number;
+  mergeThreshold?: number;
+}
+
+function parseArgs(argv: string[]): Opts {
+  const args = argv.slice(2);
+  if (args.length === 0 || args[0]?.startsWith('-')) {
+    console.error(
+      'Usage: bun scripts/warmup-session.ts <session-name-or-id> [--data-dir <dir>] [--model <id>] [--agent <name>] [--max-spend <usd>] [--l1-budget <n>] [--l2-budget <n>] [--l3-budget <n>] [--merge-threshold <n>]',
+    );
+    process.exit(1);
+  }
+  const opts: Opts = {
+    sessionRef: args[0]!,
+    dataDir: resolve(process.cwd(), 'data'),
+    model: 'claude-sonnet-4-5-20250929',
+    maxSpend: null,
+  };
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === '--data-dir') opts.dataDir = resolve(args[++i]!);
+    else if (a === '--model') opts.model = args[++i]!;
+    else if (a === '--agent') opts.agentName = args[++i]!;
+    else if (a === '--max-spend') opts.maxSpend = parseFloat(args[++i]!);
+    else if (a === '--l1-budget') opts.l1Budget = parseInt(args[++i]!);
+    else if (a === '--l2-budget') opts.l2Budget = parseInt(args[++i]!);
+    else if (a === '--l3-budget') opts.l3Budget = parseInt(args[++i]!);
+    else if (a === '--merge-threshold') opts.mergeThreshold = parseInt(args[++i]!);
+    else {
+      console.error(`Unknown arg: ${a}`);
+      process.exit(1);
+    }
+  }
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Progress renderer
+// ---------------------------------------------------------------------------
+
+interface Spend {
+  inputTokens: number;
+  outputTokens: number;
+  cost: number;
+}
+
+function renderProgress(
+  strategy: AutobiographicalStrategy,
+  startedAt: number,
+  initialL1Queue: number,
+  spend: Spend,
+  isTty: boolean,
+): void {
+  const s = strategy.getProgressSnapshot();
+  const elapsedMs = Date.now() - startedAt;
+  const elapsedSec = elapsedMs / 1000;
+
+  // Throughput: L1 chunks processed per second since start
+  const l1Done = initialL1Queue - s.l1QueueLength;
+  const l1Pct = initialL1Queue > 0 ? (l1Done / initialL1Queue) * 100 : 100;
+  const throughput = l1Done > 0 ? l1Done / elapsedSec : 0;
+  const remainingL1 = s.l1QueueLength;
+  const etaSec = throughput > 0 ? remainingL1 / throughput : 0;
+
+  const phase = s.l1QueueLength > 0 ? 'L1' : s.mergeQueueLength > 0 ? 'merges' : 'done';
+  const line =
+    `[${phase}] L1 ${l1Done}/${initialL1Queue} (${l1Pct.toFixed(1)}%) │ ` +
+    `merges ${s.mergeQueueLength} queued │ ` +
+    `L1/L2/L3 ${s.summaryCounts.l1}/${s.summaryCounts.l2}/${s.summaryCounts.l3} │ ` +
+    `tok ${(spend.inputTokens / 1000).toFixed(0)}k in / ${(spend.outputTokens / 1000).toFixed(0)}k out │ ` +
+    `$${spend.cost.toFixed(2)} │ ` +
+    `${formatDuration(elapsedSec)} elapsed │ ` +
+    `ETA ${formatDuration(etaSec)}`;
+
+  if (isTty) {
+    process.stderr.write(`\r\x1b[2K${line}`);
+  } else {
+    process.stderr.write(`${line}\n`);
+  }
+}
+
+function formatDuration(sec: number): string {
+  if (!isFinite(sec) || sec < 0) return '?';
+  const h = Math.floor(sec / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  const s = Math.floor(sec % 60);
+  if (h > 0) return `${h}h${m.toString().padStart(2, '0')}m`;
+  if (m > 0) return `${m}m${s.toString().padStart(2, '0')}s`;
+  return `${s}s`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs(process.argv);
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.error('Set ANTHROPIC_API_KEY');
+    process.exit(1);
+  }
+
+  const sessionMgr = new SessionManager(opts.dataDir);
+  const session = sessionMgr.findSession(opts.sessionRef);
+  if (!session) {
+    console.error(`No session matching "${opts.sessionRef}" in ${opts.dataDir}`);
+    process.exit(1);
+  }
+  const storePath = sessionMgr.getStorePath(session.id);
+
+  const importSource = sessionMgr.getImportSource(session.id);
+  const resolved = resolveAgentName({
+    explicit: opts.agentName,
+    sidecar: importSource?.agentName,
+    default: 'Claude',
+  });
+
+  console.error(`Warming up session "${session.name}" (${session.id})`);
+  console.error(`Store: ${storePath}`);
+  console.error(`Agent: ${resolved.name} (${resolved.source})`);
+  if (resolved.mismatch) {
+    console.error(
+      `WARNING: --agent "${resolved.mismatch.explicit}" overrides sidecar ` +
+      `"${resolved.mismatch.sidecar}". Any summaries previously written under ` +
+      `the sidecar name will be orphaned at agents/${resolved.mismatch.sidecar}/...`,
+    );
+  }
+  const agentName = resolved.name;
+  console.error(`Model: ${opts.model}`);
+  if (opts.maxSpend !== null) console.error(`Max spend: $${opts.maxSpend.toFixed(2)}`);
+
+  // -- Membrane with token-spend hook --
+  const price = priceOf(opts.model);
+  const spend: Spend = { inputTokens: 0, outputTokens: 0, cost: 0 };
+  const adapter = new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY });
+  const membrane = new Membrane(adapter, {
+    // Imported sessions store assistant turns under participant `agentName`.
+    // Membrane's default assistantParticipant is 'Claude'; if that disagrees
+    // with the stored participant every assistant message maps to role
+    // 'user' and the API rejects tool_use blocks.
+    assistantParticipant: agentName,
+    hooks: {
+      afterResponse: (response: NormalizedResponse) => {
+        const u = response.usage;
+        if (u) {
+          spend.inputTokens += u.inputTokens ?? 0;
+          spend.outputTokens += u.outputTokens ?? 0;
+          spend.cost =
+            (spend.inputTokens * price.input + spend.outputTokens * price.output) / 1_000_000;
+        }
+        return response;
+      },
+    },
+  });
+
+  // -- Store + strategy + context manager --
+  const store = JsStore.openOrCreate({ path: storePath });
+  const strategy = new AutobiographicalStrategy({
+    compressionModel: opts.model,
+    // Autobio uses summaryParticipant for the synthetic summary messages it
+    // writes back; aligning with the imported agent name keeps the whole
+    // conversation under a single participant.
+    summaryParticipant: agentName,
+    autoTickOnNewMessage: false, // we drive ticks manually
+    ...(opts.l1Budget !== undefined && { l1BudgetTokens: opts.l1Budget }),
+    ...(opts.l2Budget !== undefined && { l2BudgetTokens: opts.l2Budget }),
+    ...(opts.l3Budget !== undefined && { l3BudgetTokens: opts.l3Budget }),
+    ...(opts.mergeThreshold !== undefined && { mergeThreshold: opts.mergeThreshold }),
+  });
+
+  // Match AgentFramework.createAgent's namespace (`agents/${config.name}`)
+  // so warmup writes summaries where the live agent reads them.
+  const cm = await ContextManager.open({
+    store,
+    strategy,
+    membrane,
+    namespace: `agents/${agentName}`,
+  });
+
+  // -- Inspect initial state --
+  const initialStats = strategy.getProgressSnapshot();
+  const totalMessages = cm.getAllMessages().length;
+  console.error(
+    `\nInitial state: ${totalMessages} messages, ${initialStats.totalChunks} chunks total ` +
+      `(${initialStats.chunksCompressed} already compressed, ${initialStats.l1QueueLength} pending L1, ` +
+      `${initialStats.mergeQueueLength} merges pending).`,
+  );
+  if (initialStats.l1QueueLength === 0 && initialStats.mergeQueueLength === 0) {
+    console.error('Nothing to do — already converged.\n');
+    store.close?.();
+    return;
+  }
+  console.error('');
+
+  // -- Drive to convergence --
+  const isTty = process.stderr.isTTY ?? false;
+  const startedAt = Date.now();
+  const initialL1Queue = initialStats.l1QueueLength;
+
+  // Periodic progress refresh (handles long Sonnet calls so the bar doesn't
+  // freeze between ticks).
+  const renderTimer = setInterval(
+    () => renderProgress(strategy, startedAt, initialL1Queue, spend, isTty),
+    isTty ? 1000 : 30_000,
+  );
+
+  let aborted = false;
+  try {
+    while (true) {
+      const stats = strategy.getProgressSnapshot();
+      if (stats.l1QueueLength === 0 && stats.mergeQueueLength === 0) break;
+      if (opts.maxSpend !== null && spend.cost >= opts.maxSpend) {
+        aborted = true;
+        break;
+      }
+      await cm.tick();
+    }
+  } finally {
+    clearInterval(renderTimer);
+    renderProgress(strategy, startedAt, initialL1Queue, spend, isTty);
+    if (isTty) process.stderr.write('\n');
+  }
+
+  const finalStats = strategy.getProgressSnapshot();
+  console.error('');
+  if (aborted) {
+    console.error(
+      `Halted at $${spend.cost.toFixed(2)} (--max-spend $${opts.maxSpend?.toFixed(2)}). ` +
+        `Re-run to resume — autobio state persists in Chronicle.`,
+    );
+  } else if (finalStats.l1QueueLength === 0 && finalStats.mergeQueueLength === 0) {
+    console.error(
+      `Converged. ${finalStats.summaryCounts.l1} L1 + ${finalStats.summaryCounts.l2} L2 + ${finalStats.summaryCounts.l3} L3 summaries. ` +
+        `Total: ${spend.inputTokens.toLocaleString()} in / ${spend.outputTokens.toLocaleString()} out, $${spend.cost.toFixed(2)}.`,
+    );
+  } else {
+    console.error(
+      `Stopped with work remaining (L1=${finalStats.l1QueueLength}, merges=${finalStats.mergeQueueLength}). Re-run to continue.`,
+    );
+  }
+
+  store.close?.();
+}
+
+if (import.meta.main) {
+  main().catch((e) => {
+    console.error('\n', e);
+    process.exit(1);
+  });
+}

package/src/agent-name.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolve which participant name an agent should use when several sources
+ * (CLI flag, import-source sidecar, hard-coded default) disagree.
+ *
+ * Centralising this priority is load-bearing: warmup and conhost agree on
+ * the name → strategy state lives at the same Chronicle namespace → the
+ * live agent reads what warmup wrote. The original bug
+ * (`agents/agent/autobio:summaries` empty vs `default/autobio:summaries`
+ * populated) was caused by exactly this resolution drifting between two
+ * scripts that defaulted differently and never compared notes.
+ */
+
+/** Which input the chosen name came from, for log lines and warnings. */
+export type AgentNameSource = 'explicit' | 'sidecar' | 'default';
+
+export interface ResolvedAgentName {
+  name: string;
+  source: AgentNameSource;
+  /**
+   * Set when both `explicit` and `sidecar` were provided and disagree.
+   * Callers should warn on this — the agent will use `explicit` (because
+   * an operator override beats a stored record) but the disagreement
+   * means some other consumer (e.g. warmup that wrote summaries under
+   * `sidecar`) has produced artifacts the live agent can't reach.
+   */
+  mismatch?: { explicit: string; sidecar: string };
+}
+
+/**
+ * Priority: `explicit` (CLI flag or non-default recipe field) > `sidecar`
+ * (per-session record written by the importer) > `default` (caller's
+ * context-specific fallback — `"Claude"` for the claudeai-revival
+ * scripts, `"agent"` for native conhost sessions).
+ *
+ * Empty strings on `explicit` or `sidecar` are treated as absent so an
+ * accidental `--agent ""` or a sidecar with `"agentName": ""` doesn't
+ * silently override the chain.
+ */
+export function resolveAgentName(inputs: {
+  explicit?: string;
+  sidecar?: string;
+  default: string;
+}): ResolvedAgentName {
+  const explicit = nonEmpty(inputs.explicit);
+  const sidecar = nonEmpty(inputs.sidecar);
+
+  const mismatch = explicit && sidecar && explicit !== sidecar
+    ? { explicit, sidecar }
+    : undefined;
+
+  if (explicit) return { name: explicit, source: 'explicit', ...(mismatch && { mismatch }) };
+  if (sidecar) return { name: sidecar, source: 'sidecar' };
+  return { name: inputs.default, source: 'default' };
+}
+
+function nonEmpty(s: string | undefined): string | undefined {
+  return typeof s === 'string' && s.length > 0 ? s : undefined;
+}