agentcache 0.4.2 → 0.5.0-beta.1

package/dist/{paths-5LZRKNYY.js → paths-NTZ2357O.js}

@@ -6,10 +6,10 @@ import {
   getDbPath,
   getProjectDisplayName,
   getProjectId,
+  getSessionDbPath,
   isInitialized,
   migrateFromLegacy
-} from "./chunk-T4COG3XD.js";
-import "./chunk-KFQGP6VL.js";
+} from "./chunk-R5I6WWSD.js";
 export {
   findProjectRoot,
   getClaudeTranscriptsDir,
@@ -18,6 +18,7 @@ export {
   getDbPath,
   getProjectDisplayName,
   getProjectId,
+  getSessionDbPath,
   isInitialized,
   migrateFromLegacy
 };

package/dist/postinstall.js

@@ -1,66 +1,2 @@
-import {
-  spawnCompileAll
-} from "./chunk-JUDLOBOC.js";
-import {
-  registerClaudeHooks,
-  registerMcpServer
-} from "./chunk-SLRKWMSE.js";
-import {
-  SqliteKnowledgeRepository
-} from "./chunk-PSASDZQE.js";
-import {
-  detectInstalledIdes
-} from "./chunk-5UO7NJPQ.js";
-import {
-  getDataDir,
-  getDbPath,
-  migrateFromLegacy
-} from "./chunk-T4COG3XD.js";
-import "./chunk-KFQGP6VL.js";
-
 // src/postinstall.ts
-import { mkdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import { spawnSync } from "child_process";
-if (process.env.CI) {
-  process.exit(0);
-}
-try {
-  migrateFromLegacy();
-  mkdirSync(getDataDir(), { recursive: true });
-  const repo = new SqliteKnowledgeRepository(getDbPath());
-  repo.close();
-  const ides = detectInstalledIdes().filter((i) => i.detected);
-  const registered = [];
-  for (const ide of ides) {
-    if (registerMcpServer(ide)) {
-      registered.push(ide.name);
-    }
-  }
-  mkdirSync(join(homedir(), ".claude"), { recursive: true });
-  registerClaudeHooks();
-  if (registered.length > 0) {
-    console.log(`agentcache: registered with ${registered.join(", ")}`);
-  }
-  console.log("agentcache: ready. Knowledge compiles automatically across all sessions.");
-  const hasBackend = ["claude", "codex", "gemini", "copilot", "aider", "goose"].some((cmd) => {
-    try {
-      return spawnSync("which", [cmd], { encoding: "utf-8", timeout: 3e3 }).status === 0;
-    } catch {
-      return false;
-    }
-  }) || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
-  if (hasBackend) {
-    const spawned = spawnCompileAll();
-    if (spawned) {
-      console.log("agentcache: background compilation started for existing transcripts.");
-    }
-  } else {
-    console.log("agentcache: no LLM backend detected for batch compilation.");
-    console.log("  Install one of: claude, codex, gemini, copilot, aider, goose");
-    console.log("  Or set ANTHROPIC_API_KEY / OPENAI_API_KEY. Knowledge compiles via MCP in the meantime.");
-  }
-} catch (err) {
-  console.log(`agentcache postinstall: ${err.message}. Run 'agentcache setup' manually.`);
-}
+console.log("agentcache: installed. Run 'agentcache setup' to configure it explicitly.");

package/dist/setup-CXZFERQE.js

@@ -0,0 +1,48 @@
+import {
+  registerClaudeHooks,
+  registerMcpServer
+} from "./chunk-ECMT4ANK.js";
+import {
+  detectInstalledIdes
+} from "./chunk-RXGW4Q3G.js";
+import {
+  getDataDir
+} from "./chunk-R5I6WWSD.js";
+
+// src/setup.ts
+import { mkdirSync } from "fs";
+async function runSetup() {
+  mkdirSync(getDataDir(), { recursive: true, mode: 448 });
+  const ides = detectInstalledIdes();
+  const detected = ides.filter((i) => i.detected);
+  console.log(`
+AgentCache setup complete.`);
+  console.log(`  Data directory: ${getDataDir()}
+`);
+  if (detected.length === 0) {
+    console.log(`  No supported IDEs detected. No MCP registration was changed.
+`);
+    return;
+  }
+  console.log(`IDEs:`);
+  for (const ide of detected) {
+    const result = registerMcpServer(ide);
+    if (result.status === "registered") {
+      console.log(`  ${ide.name}: MCP registered`);
+    } else if (result.status === "unchanged") {
+      console.log(`  ${ide.name}: already registered`);
+    } else {
+      console.log(`  ${ide.name}: skipped${result.reason ? ` (${result.reason})` : ""}`);
+    }
+  }
+  const legacyHooksRemoved = registerClaudeHooks();
+  if (legacyHooksRemoved) {
+    console.log(`
+  Claude Code hooks: removed legacy automatic hooks`);
+  }
+  console.log(`
+Done. Use AgentCache commands explicitly to import or resume a session.`);
+}
+export {
+  runSetup
+};

package/docs/compatibility.md

@@ -0,0 +1,146 @@
+# AgentCache beta compatibility
+
+This document describes the runtime registry shipped in AgentCache
+`0.5.0-beta.1`. The CLI remains the source of truth on an installed machine:
+
+```bash
+agentcache adapter list --json
+agentcache adapter doctor <adapter-id> --json
+```
+
+## Reading capability levels
+
+- `stable` requires dated, client-specific integration evidence in the runtime
+  registry. No adapter currently meets that bar.
+- `experimental` means AgentCache has fixture or schema evidence but still
+  needs a dated live-client verification run.
+- `unsupported` is a deliberate fail-closed boundary. AgentCache reports the
+  missing capability and does not emulate or guess it.
+
+The mode is equally important:
+
+- `mcp-cooperative` means the client starts an AgentCache stdio MCP process.
+- `local-snapshot` means AgentCache reads an allowed native transcript source
+  without writing to it.
+- `none` means that adapter capability is not offered.
+
+This matrix was checked against the runtime registry on 2026-09-07. The
+experimental entries have no `verifiedAt` value in the registry, so this date is
+not presented as live-client verification evidence.
+
+## Runtime capability matrix
+
+| Client | Adapter ID | Registration | Historical recovery | Native resume | Native append/checkpoint/fork/launch |
+|---|---|---|---|---|---|
+| Claude Code | `claude-code` | experimental / mcp-cooperative | experimental / local-snapshot JSONL | unsupported / none | unsupported / none |
+| Cursor | `cursor` | experimental / mcp-cooperative | experimental / local-snapshot JSONL | unsupported / none | unsupported / none |
+| Roo Code | `roo-code` | experimental / mcp-cooperative | experimental / local-snapshot task JSON | unsupported / none | unsupported / none |
+| Windsurf | `windsurf` | experimental / mcp-cooperative | unsupported / none | unsupported / none | unsupported / none |
+| Continue | `continue` | experimental / mcp-cooperative | experimental / local-snapshot session JSON | unsupported / none | unsupported / none |
+| Codex | `codex` | experimental / mcp-cooperative | experimental / local-snapshot JSONL | unsupported / none | unsupported / none |
+| Goose | `goose` | experimental / mcp-cooperative | unsupported / none | unsupported / none | unsupported / none |
+
+The longer table in the README is mechanically checked against all seven
+capability fields in the runtime registry.
+
+## Portable operations versus native operations
+
+AgentCache's shared MCP surface provides portable `session_open`,
+`session_resume`, `session_append`, `session_checkpoint`, `session_fork`, and
+`session_history` operations. Those write to AgentCache's v2 store, not to a
+client's native conversation database.
+
+Resume-capsule source provenance names the client leg that owns the checkpoint
+boundary event. A human CLI may create the immutable checkpoint and handoff,
+but that administrative writer is not presented as the conversation source.
+An explicit historical checkpoint keeps the historical event's source, and a
+fork keeps the parent boundary's source. If AgentCache cannot prove that event
+and leg relationship, it rejects the capsule instead of guessing.
+
+The runtime registry marks native resume, append, checkpoint, fork, and launch
+unsupported for all seven adapters. In practical terms:
+
+1. You explicitly prepare a handoff with the AgentCache CLI.
+2. You open the destination client and the same repository yourself.
+3. The destination consumes the handoff through its registered AgentCache MCP
+   server.
+4. AgentCache creates a new portable client leg. It does not import or launch a
+   provider-private conversation object.
+
+## Registration formats
+
+Setup writes an adapter-bound command, never a bare untrusted identity:
+
+```text
+agentcache serve --adapter <adapter-id>
+```
+
+The supported configuration families are Claude Code JSON, Cursor/Windsurf/Roo
+Code MCP JSON, Continue's MCP JSON directory, Codex TOML, and Goose YAML.
+Existing files are updated atomically with a restrictive backup. Malformed or
+ambiguous configurations are preserved and reported as skipped. Setup removes
+recognized legacy AgentCache hooks and allow-list entries; it does not add
+blanket tool approval. It also recognizes the exact pre-rebrand Loop
+Engineering registration (`mcpServers.loop` running `loop-eng serve`) and its
+Claude `compile-session`, `discover`, and `enforce` hooks. Those known entries
+are removed during migration, while similarly named or otherwise ambiguous
+user configuration is left untouched. Published early-release JSON targets at
+`~/.roo/mcp.json`, `~/.windsurf/mcp.json`, `~/.continue/mcp.json`, and
+`~/.codex/mcp.json` are checked and cleaned in a separate safe pass before the
+current target is registered.
+
+Goose registration is experimental. It targets the documented Goose 1.39
+`extensions.<name>` stdio YAML shape. Goose historical recovery is unsupported
+because a safe immutable snapshot of its SQLite database and WAL has not been
+verified.
+
+## Historical recovery evidence
+
+| Client | Source evidence available to workspace binding | Consequence |
+|---|---|---|
+| Claude Code | Explicit `cwd` in JSONL | A matching source can be imported for the active workspace. |
+| Cursor | Encoded path hint only | The hint is not trusted as workspace ownership; automatic import may require a future explicit attach flow. |
+| Roo Code | No verified workspace field | The unverified source is reported in diagnostics, but AgentCache does not expose it as a selectable session or guess the workspace. |
+| Windsurf | No verified historical transcript source | Historical recovery is unsupported; prospective MCP sessions can still participate. |
+| Continue | Explicit `workspaceDirectory` in session JSON | A matching source can be imported for the active workspace. |
+| Codex | Explicit `session_meta.cwd` in JSONL | A matching source can be imported for the active workspace. |
+| Goose | SQLite source lacks the required safe snapshot implementation | Historical recovery is unsupported; prospective MCP sessions can still participate. |
+
+Discovery is bounded by the adapter's runtime limits: at most 16 MiB, 10,000
+normalized events, and two seconds per read budget. Sources outside canonical
+adapter-owned roots, symbolic links, changed files, malformed input, and
+unproven workspace matches fail closed.
+
+## Known beta limitations
+
+- All adapter registration is experimental pending dated live-client runs.
+- Windsurf historical recovery is unsupported.
+- Goose historical recovery is unsupported, and Goose registration remains
+  experimental.
+- Cursor and Roo Code history can be parsed, but their current native sources
+  do not provide enough evidence for automatic workspace binding.
+- Workspace continuity requires the same device and exact canonical root;
+  sibling clones and separate worktrees remain isolated even when Git metadata
+  matches. An explicit attach flow is deferred. Multi-root MCP clients receive
+  an opaque root ID paired with a bounded, redacted display label; the label is
+  untrusted and display-only. A changed Git identity at the same canonical path
+  is reported as a warning without exposing the stored remote or Git path.
+- Native launch and provider-native resume are unsupported for every adapter.
+- Multi-device sync is not implemented.
+- Client updates can change undocumented transcript formats or configuration
+  behavior. Run `adapter doctor` after an update and report the exact client
+  version with beta feedback.
+
+## Reporting compatibility evidence
+
+Include these outputs, after checking them for sensitive data:
+
+```bash
+node --version
+agentcache --version
+agentcache adapter doctor <adapter-id> --json
+```
+
+Also include the client version, operating system, source and destination
+adapter IDs, whether the operation was `continue` or `fork`, and whether the
+client was restarted after registration.

package/docs/demo-script.md

@@ -0,0 +1,121 @@
+# AgentCache in 60–90 seconds: an uncut demo
+
+## Goal
+
+Show one unfinished Claude Code leg, an explicit session selection, Codex
+consuming the exact handoff and recalling the next step, then an explicit fork
+consumed in Cursor. Keep the terminal, clients, repository, and clock visible.
+Do not cut around an error or replace real output with a mock.
+
+## Preflight, off camera
+
+- Install `agentcache@0.5.0-beta.1`, run `agentcache setup`, and restart Claude
+  Code, Codex, and Cursor.
+- Open the same small demo repository in all three clients.
+- Run the global `agentcache doctor` to verify exact adapter-bound MCP
+  registrations. Before the first session operation, its informational
+  `will initialize on first session operation` message is expected and is not
+  a failure. After `session_open`, rerun global doctor if you want to verify the
+  initialized v2 store. Run `agentcache adapter doctor <adapter-id>` for each
+  client to capture capability evidence. Keep the diagnostic output available
+  after the recording.
+- In Claude Code, use the AgentCache `session_open` tool to open a portable
+  session, then use `session_append` and `session_checkpoint` to make a short
+  checkpoint whose
+  state says:
+    - objective: add an input validator;
+    - completed work: failing test added;
+    - open work: implement the validator;
+    - constraint: do not change the public error shape; and
+    - next step: run the focused test, then implement the smallest fix.
+- Leave the implementation unfinished. Record the session ID, but do not
+  preselect it in the terminal picker.
+- Use disposable demo text. Never place a real credential or private path in a
+  handoff token, prompt, terminal title, or screen recording.
+
+## Recording script
+
+### 0–10 seconds — unfinished Claude Code leg
+
+Show Claude Code in the demo repository. Say:
+
+> “This session has a failing validator test and a specific next step. I am
+> stopping here and moving the work to another agent.”
+
+Briefly show the AgentCache checkpoint receipt. Do not show hidden chain of
+thought or a provider's internal state.
+
+### 10–30 seconds — explicit selection and takeover confirmation
+
+In a terminal at the repository root, run:
+
+```bash
+agentcache session resume --to codex
+```
+
+Type a short search term, show more than one row if possible, and select the
+Claude Code session by number. After inspecting its source/project/state, type
+`continue` at the action prompt. Because the Claude writer is still active, the
+CLI asks for takeover confirmation; type the second, literal `continue`. Say:
+
+> “There is no automatic latest-session choice. I pick the source and name
+> Codex as the destination. This confirmation authorizes takeover; when Codex
+> consumes the handoff, it invalidates Claude's writer lease.”
+
+The CLI prints a handoff ID and a one-time token. Blur the token in any published
+recording. The prompt-based flow may send both the handoff ID and token to the
+destination provider. Treat the token as a temporary bearer secret; for a live
+demo, paste it directly into the next prompt and do not save terminal history.
+
+### 30–52 seconds — Codex consumes and recalls
+
+Switch to Codex with the same repository open. Prompt:
+
+```text
+Use AgentCache session_resume with handoff ID <handoff-id> and token <token>.
+Before editing, state the objective, constraint, completed work, and next step.
+```
+
+Show Codex reporting the expected validator objective, unchanged-error-shape
+constraint, existing failing test, and focused-test next step. Then let it make
+or describe one small continuation and checkpoint it. Say:
+
+> “Codex received a bounded, labelled capsule—not Claude's private session
+> object and not a hand-written Markdown handoff.”
+
+### 52–72 seconds — explicit fork to Cursor
+
+Back in the terminal, use the visible session ID:
+
+```bash
+agentcache session fork <session-id> --from latest --to cursor --title "Alternative validator fix" --json
+```
+
+Point out the explicit parent session, checkpoint, destination, and `fork` mode.
+Open Cursor on the same repository and ask its AgentCache `session_resume` tool
+to consume that output's handoff ID and token.
+
+### 72–90 seconds — verify independence
+
+Ask Cursor:
+
+```text
+Inspect the resumed AgentCache session. Tell me which parent checkpoint this
+fork came from and what the next step is. Do not edit yet.
+```
+
+Show the child session ID and parent reference. End with:
+
+> “One local timeline, explicit handoffs, and an independent fork across three
+> agents. This beta is same-machine only.”
+
+## Evidence to retain with the recording
+
+- Exact AgentCache, Node.js, Claude Code, Codex, and Cursor versions
+- Sanitized `adapter doctor --json` output for the three adapters
+- Recording date and operating system
+- A note confirming that native transcript file hashes were unchanged
+- Whether the capsule was partial
+
+If any of those facts are unavailable, describe the demo as a local development
+run rather than a verified compatibility result.

package/docs/launch-copy.md

@@ -0,0 +1,127 @@
+# AgentCache 0.5 beta launch copy
+
+All variants below deliberately describe the same-machine beta and distinguish
+portable AgentCache state from provider-native session state.
+
+## Release gate
+
+This is staged launch copy, not evidence that the release is available. The
+`0.5.0-beta.1` npm version remains unpublished and the GitHub repository remains
+private until the final human-controlled release step. Before using any copy
+below, verify that the exact npm artifact is published, its checksum matches the
+release candidate, and the GitHub repository plus beta issue form are accessible
+to the intended audience. Do not publish the package or change repository
+visibility without explicit release approval.
+
+## One line
+
+AgentCache lets you pick a coding session and continue its bounded working
+context in another registered agent on the same machine.
+
+## Short post
+
+AgentCache `0.5.0-beta.1` is available for testing.
+
+Pick a coding session, choose a destination agent, and continue with a bounded
+checkpoint of the goal, decisions, completed work, blockers, constraints, and
+next step. The handoff travels through a local AgentCache timeline and a
+single-use, destination-bound MCP handoff—without maintaining a Markdown
+handoff file.
+
+The beta includes adapter wiring for Claude Code, Cursor, Roo Code, Windsurf,
+Continue, Codex, and Goose. Capability levels differ by client: all current
+registrations are experimental, and Windsurf and Goose historical recovery are
+unsupported. Check the runtime evidence with `agentcache adapter doctor`.
+
+This release is same-machine only. Cloud sync and team sharing are deferred.
+In the prescribed prompt-based consumption flow, the destination provider may
+receive the resume capsule, handoff ID, and one-use token under its terms.
+Treat that token as a temporary bearer secret.
+
+Install the pinned beta:
+
+```bash
+npm install -g agentcache@0.5.0-beta.1
+agentcache setup
+```
+
+Then run `agentcache session resume --to <adapter>` from your repository and
+choose the session explicitly. Please report results through the structured
+AgentCache beta feedback issue form.
+
+## GitHub release summary
+
+### AgentCache 0.5.0-beta.1 — explicit cross-agent session continuity
+
+This beta changes AgentCache's default product path from automatic knowledge
+compilation to explicit portable sessions.
+
+Highlights:
+
+- local v2 session timeline stored beside legacy v1 data;
+- interactive session search, inspection, and selection;
+- one-use resume handoffs bound to a workspace and destination adapter;
+- append, checkpoint, bounded history, continuation, and independent forks;
+- adapter registration for Claude Code, Cursor, Roo Code, Windsurf, Continue,
+  Codex, and Goose;
+- read-only, bounded native transcript ingestion where workspace identity can
+  be verified;
+- restrictive local permissions, atomic configuration backups, redacted
+  portable text, and untrusted-context labelling; and
+- no postinstall setup, background legacy compilation, silent update, generated
+  instruction injection, or blanket AgentCache tool approval in the beta path.
+
+Known limits:
+
+- same-machine only;
+- adapter capabilities remain experimental until dated live-client evidence is
+  recorded;
+- Windsurf and Goose historical recovery are unsupported;
+- Cursor and Roo Code historical sources cannot yet prove workspace ownership;
+- clients must already be open on the intended workspace; and
+- AgentCache does not transfer hidden reasoning, native conversation state, or
+  provider approval state.
+
+Privacy note: AgentCache stores its portable timeline locally, but in the
+prescribed prompt-based consumption flow the destination provider may receive
+the resume capsule, handoff ID, and one-use token. Treat that token as a
+temporary bearer secret.
+
+## Hacker News / forum text
+
+I built AgentCache because I wanted an explicit `/resume`-style choice across
+coding agents. The 0.5 beta keeps a portable session timeline in local SQLite.
+From a repository, you select a session and a destination; the destination MCP
+connection consumes a short-lived handoff and receives a bounded checkpoint.
+
+The handoff contains practical work state, not provider-private session state:
+goal, constraints, decisions, completed/open work, next step, Git metadata, and
+a limited recent-event window. Forks get an independent child timeline.
+
+The current adapter set is Claude Code, Cursor, Roo Code, Windsurf, Continue,
+Codex, and Goose, with capability levels reported at runtime. It is a
+same-machine beta: there is no cloud sync, and Windsurf/Goose historical
+recovery is currently unsupported.
+
+I would value reports that include the exact source client, destination client,
+versions, operating system, command shape, and sanitized diagnostics—especially
+failed handoffs and format changes.
+
+## Demo caption
+
+Claude Code → explicit picker → Codex continuation → explicit Cursor fork. The
+destination recalls the next step from a bounded AgentCache checkpoint, while
+the parent and fork remain separate. AgentCache 0.5 is a same-machine beta;
+capabilities vary by adapter.
+
+## Claims to avoid until evidence changes
+
+- Identical support across clients
+- Compatibility with an unlisted client or version
+- Automatic native-session migration
+- Complete transcript transfer
+- Guaranteed secret removal
+- Offline behavior of hosted AI clients
+- Cross-device continuity
+- Quantified productivity or cost improvement
+- Stable adapter status without a dated live-client run