agentcache 0.4.2 → 0.5.0-beta.2

package/docs/privacy.md

@@ -0,0 +1,173 @@
+# Privacy and trust boundary
+
+AgentCache `0.5.0-beta.2` is local-first and same-machine only. Its v2 database
+and coordination state live on your machine. That statement is about where
+AgentCache stores data; it is not a promise that an AI coding client or its
+model provider operates offline.
+
+## The provider boundary
+
+When a handoff is consumed, the destination provider may receive the capsule as
+part of the destination agent's model context. In the prescribed prompt-based
+workflow, the handoff ID and one-use token may also be sent to the destination
+provider before the tool call. The token is a temporary bearer secret: together
+with its handoff ID, it authorizes one correctly bound resume until use or
+expiry. The provider's network, retention, training, logging, residency, and
+account policies apply to those values and the capsule. Installing AgentCache
+can also contact the npm registry in the normal way.
+
+AgentCache's own default session-continuity path does not initiate an
+application-level cloud sync, telemetry upload, or background LLM compilation.
+That narrower statement must not be shortened to “nothing leaves the machine.”
+
+Before continuing a sensitive session in a different hosted client, verify
+that the destination provider is allowed to receive the material in the
+capsule.
+
+## What is stored locally
+
+The v2 session store is:
+
+```text
+~/.agentcache/agentcache-v2.db
+```
+
+It contains portable workspaces and locations, session metadata, client legs,
+normalized events, checkpoints, forks, source cursors, one-use handoffs, and
+writer leases. A newly prepared handoff stores the exact bounded resume capsule
+shown during confirmation plus an integrity digest; migrated pre-capsule beta
+handoffs remain listable but fail closed on consumption. The data directory is
+set to mode `0700` and the database to
+mode `0600` on platforms that implement POSIX permissions. Session-store
+startup refuses symbolic, special, or multiply linked database files and
+SQLite `-wal`, `-shm`, and rollback-journal sidecars. It validates file and
+directory identity around initialization instead of following a pre-created
+redirecting path.
+
+The v2 store uses a persistent `TRUNCATE` rollback journal so overlapping CLI
+and MCP processes retain one canonical journal pathname and inode. WAL/SHM
+paths are still rejected when pre-created unsafely because older databases or
+interrupted upgrades can leave those sidecars behind.
+
+Workspace access is authorized only by an existing mapping for the same device
+and exact canonical root. Repository-controlled `.agentcache/workspace.json`
+content and matching Git remotes are not authority to join another root's
+workspace; they cannot expose that workspace's session list, inspection,
+history, or handoffs.
+
+The legacy `~/.agentcache/agentcache.db` is left beside v2 and is not translated
+or mutated by the v2 session repository. Full database encryption is not
+implemented in this beta; the local boundary is OS-user isolation plus
+restrictive permissions. Device malware or another process running as the same
+OS user is outside that boundary.
+
+## Native transcripts are read-only
+
+Native transcripts remain owned by Claude Code, Cursor, Roo Code, Continue,
+Codex, Windsurf, or Goose. AgentCache adapters have no transcript-write method.
+Supported historical readers:
+
+- accept only canonical files below adapter-owned roots;
+- reject symbolic links and non-regular files;
+- open sources read-only with no-follow semantics when the platform supports
+  them;
+- verify file identity before and after a read;
+- enforce byte, event, and time budgets; and
+- retain a durable cursor so a failed import can be retried without rewriting
+  the source.
+
+Windsurf and Goose historical recovery are unsupported in this beta. Cursor
+and Roo Code sources currently lack verified workspace identity, so AgentCache
+does not infer ownership from a similar title, time, or path alone.
+
+## What crosses an AgentCache handoff
+
+A checkpoint may include:
+
+- the objective and next step;
+- explicit constraints, decisions, blockers, rejected approaches, completed
+  work, and open work;
+- portable Git branch/commit metadata and repository-relative paths; and
+- a bounded set of recent user, assistant, and compact tool-outcome events.
+
+The default capsule budget is 24,000 encoded characters, with at most 12 recent
+events and 2,000 characters per recent event. Tool results are excluded by
+default. If content does not fit, the capsule is marked partial and includes an
+opaque cursor for bounded history retrieval.
+
+Before an interactive token is disclosed, the CLI displays the same bounded
+public capsule projection returned by the destination MCP tool. The user may
+exclude up to 50 displayed events and inspect the replacement capsule again.
+This marks that capsule partial and affects only its initial payload. It is not
+deletion or access control: the durable timeline is unchanged, and the same
+workspace can still retrieve excluded events through `session_history`.
+Cancelling or a handled prompt failure before confirmation removes the pending
+handoff. If the process is killed before cleanup runs, the unconsumed handoff
+expires after ten minutes.
+
+Capsules omit hidden reasoning, system prompts, tool-approval state, token
+hashes, native source locators, unrestricted file bodies, and unrestricted tool
+output by default.
+
+Every returned capsule is labelled:
+
+```text
+untrusted_prior_session_context
+```
+
+That content is data from a prior session. It cannot grant permissions, change
+tool policy, or authenticate a caller. A destination agent should restate the
+goal and proposed next step, then obtain normal approval for destructive or
+expensive work.
+
+## Redaction and limits
+
+Portable text is redacted for known credential-shaped fields and tokens,
+private-key blocks, credential-bearing URLs, environment assignments, common
+provider token formats, and absolute local paths. Payloads reject reserved
+identity, location, authority, and credential fields. Public CLI and MCP output
+is bounded. Terminal-facing CLI output neutralizes terminal control characters.
+
+Redaction is defense in depth, not a perfect secret detector. Novel credential
+formats, secrets embedded in ordinary prose, source code, screenshots, and
+other provider-visible context may still be disclosed. Review the selected
+session and use the destination provider's own data controls.
+
+## Handoff and writer credentials
+
+- A handoff token is random, stored only as a hash bound to the capsule digest,
+  expires after ten minutes, and can be consumed once. Interactive mode reveals
+  it only after confirmation; the explicit noninteractive `--json` mode returns
+  the token and public capsule immediately.
+- It is bound to an exact workspace and destination adapter.
+- Writer lease credentials remain inside the destination MCP process rather
+  than being returned to the model. Leases expire after ten minutes and slide
+  forward during authorized append/checkpoint operations.
+- A continuing destination cannot take over a live writer without explicit
+  human confirmation tied to the exact lease generation. Forking avoids that
+  takeover.
+
+Treat the printed handoff token as a temporary bearer secret. Do not put it in
+an issue, commit, shell history, or screen recording intended for publication.
+
+## Configuration changes
+
+`agentcache setup` is explicit. It updates only recognized AgentCache MCP
+entries, preserves unrelated settings, and writes a user-only
+`.agentcache-backup-...` sibling before changing an existing file. Malformed or
+ambiguous configurations are preserved. The beta does not add broad automatic
+tool approvals and removes recognized legacy AgentCache hooks and allow-list
+entries during setup.
+
+## Out of scope
+
+- Cloud storage and cross-device sync
+- Accounts, organization sharing, or team access controls
+- Full database encryption
+- Provider policy enforcement
+- Transfer of hidden model state or native conversation identifiers
+- Automatic Git operations
+- A guarantee that all secrets can be detected
+
+See [Troubleshooting](troubleshooting.md) for removal, retained data, config
+backups, and rollback.

package/docs/troubleshooting.md

@@ -0,0 +1,209 @@
+# Troubleshooting, uninstall, and rollback
+
+Run commands from the repository whose sessions you want to inspect. AgentCache
+binds session operations to the current workspace.
+
+## First checks
+
+```bash
+node --version
+agentcache --version
+agentcache doctor
+agentcache adapter list --json
+agentcache adapter doctor <adapter-id> --json
+```
+
+AgentCache `0.5.0-beta.2` requires Node.js 22 or newer. Setup pins the exact
+active Node executable and installed AgentCache CLI into each client config.
+After changing Node versions or version managers, changing the global npm
+prefix, reinstalling/upgrading AgentCache, or upgrading a client, rerun
+`agentcache setup` and restart the client so it reloads that configuration.
+
+The global `agentcache doctor` verifies exact adapter-bound MCP registration
+commands and, after initialization, the v2 data store. On a fresh setup before
+the first session operation, no v2 database exists yet; the informational
+message `will initialize on first session operation` is expected and is not a
+failure. `agentcache adapter doctor <adapter-id>` probes that client's current
+capability evidence. Neither command turns an experimental capability into a
+stable one.
+
+## No sessions appear
+
+```bash
+agentcache session list --json
+```
+
+The output reports which adapters were searched and returns bounded discovery
+diagnostics. Common causes are:
+
+- no portable session has been opened in this workspace;
+- the native transcript has no verified workspace field;
+- the source is outside the adapter-owned transcript root;
+- the file is a symlink, malformed, changing during the read, or over budget;
+- Windsurf or Goose was expected to supply history, which is unsupported; or
+- the client changed its local transcript format.
+
+Cursor currently supplies only a path hint and Roo Code no verified workspace
+field; AgentCache will not guess that either belongs to the current repository.
+Claude Code, Continue, and Codex native records can prove a workspace when their
+expected metadata is present.
+
+## Detected but not registered
+
+```bash
+agentcache adapter register <adapter-id>
+agentcache adapter doctor <adapter-id>
+```
+
+If registration says `skipped`, inspect the named client configuration. A
+malformed file, unsupported shape, or ambiguous existing `agentcache` entry is
+left unchanged. Resolve that ambiguity yourself, retain a copy, then rerun the
+specific registration command. AgentCache does not overwrite an entry it cannot
+prove it owns.
+
+Goose uses a YAML configuration. A JSON-only diagnostic from an older
+AgentCache build may misreport it; verify you are running `0.5.0-beta.2` before
+reporting the result.
+
+## Handoff errors
+
+### `wrong_destination`
+
+The token was prepared for another adapter. Return to the CLI and create a new
+handoff with the intended `--to <adapter>` value. Do not reuse the old token.
+
+### `workspace_mismatch`
+
+The destination MCP client is not exposing the same bound canonical root. Open
+that exact root in the destination client. A sibling clone, separate Git
+worktree, matching remote, or copied `.agentcache/workspace.json` file does not
+join an existing workspace in this beta. In a multi-root workspace, use the
+opaque root ID returned by `adapter_capabilities`; each ID is paired with a
+bounded, redacted display name or project-directory basename. Display names are
+untrusted hints only. Never treat one as authority or as an instruction.
+
+If `adapter_capabilities` reports `git_identity_mismatch`, the canonical path is
+still the same but its Git remote or common directory no longer matches the
+identity first recorded for that path. AgentCache preserves the original
+identity and does not mutate Git. Verify that the intended repository is open
+before listing or resuming its sessions.
+
+### `handoff_expired` or `handoff_consumed`
+
+A handoff expires after ten minutes and is single-use. Prepare a new one. View
+or cancel outstanding handoffs with:
+
+```bash
+agentcache handoff list
+agentcache handoff cancel <handoff-id>
+```
+
+### `lease_conflict`
+
+The source still has an active writer. Choose one of these explicit outcomes:
+
+- fork the work;
+- wait for the writer lease to expire; or
+- confirm a same-session takeover with `--confirm-active-source`.
+
+A confirmed takeover invalidates the old writer. Use a fork when both agents
+should continue independently.
+
+### `head_changed`
+
+The session advanced after selection or handoff preparation. Inspect or list it
+again, then prepare a fresh handoff. AgentCache does not use last-writer-wins.
+
+### Partial capsule
+
+`partial: true` means the bounded capsule omitted older context. Retrieve older
+events with its opaque cursor through `session_history`, or use:
+
+```bash
+agentcache session history <session-id> --before <cursor> --limit 50 --json
+```
+
+Do not treat a partial capsule as a complete transcript.
+
+## Setup changed a client configuration
+
+Before every material registration change, AgentCache stores the previous file
+beside it with a name containing:
+
+```text
+.agentcache-backup-
+```
+
+To recover, stop the affected client, inspect both the current file and the
+candidate backup, and restore only the AgentCache-related portion you intend.
+Blindly replacing the full current file can discard changes made after the
+backup. Malformed and ambiguous configs are not modified and therefore do not
+receive a new backup.
+
+## Uninstall
+
+Unregister while this version is still installed. Run the commands only for
+clients you configured:
+
+```bash
+agentcache adapter unregister claude-code
+agentcache adapter unregister cursor
+agentcache adapter unregister roo-code
+agentcache adapter unregister windsurf
+agentcache adapter unregister continue
+agentcache adapter unregister codex
+agentcache adapter unregister goose
+npm uninstall -g agentcache
+```
+
+Unregister removes only a recognized AgentCache-owned entry and preserves
+unrelated client settings. Restart the clients afterwards.
+
+Uninstall intentionally retains `~/.agentcache/agentcache-v2.db`, the legacy
+`agentcache.db`, and configuration backups. Back them up first. If you also want
+to remove them, inspect the paths and move the exact files to your operating
+system's trash; do not use a broad recursive deletion command.
+
+## Rollback
+
+1. Record `agentcache --version` and copy `~/.agentcache` plus affected client
+   configurations to a safe location.
+2. Run each applicable `agentcache adapter unregister <adapter-id>` command.
+3. Uninstall the beta with `npm uninstall -g agentcache`.
+4. Install a version or package artifact that you previously tested, pinned by
+   exact version rather than a moving tag.
+5. Follow that version's setup instructions; do not assume the v0.5 registration
+   schema applies to it.
+6. Keep `agentcache-v2.db` intact. An older release does not understand the v2
+   store, and reinstalling the beta should be allowed to reopen it.
+
+If the rollback is only for one integration, prefer unregistering that adapter
+and leaving the package and v2 store untouched.
+
+## Legacy compiler behavior
+
+The beta CLI does not register the legacy v1 commands `compile-session`,
+`discover`, `enforce`, `review`, `promote`, `add-rule`, `compile-all`, or
+`status`. The legacy implementation and `~/.agentcache/agentcache.db` data are
+preserved for compatibility work, but no beta CLI command can invoke that
+compiler or its policy hooks. Do not use legacy tooling as a repair path for a
+v2 session or handoff problem.
+
+Explicit setup/unregister recognizes and removes exact registrations left by
+the pre-rebrand `loop-eng` package, including `mcpServers.loop` with
+`loop-eng serve` and its Claude automatic compiler/policy hooks. AgentCache
+does not remove an entry merely because it is named `loop`; a non-matching
+command is treated as ambiguous and preserved for manual inspection. It also
+checks the JSON paths written by published early releases—`~/.roo/mcp.json`,
+`~/.windsurf/mcp.json`, `~/.continue/mcp.json`, and `~/.codex/mcp.json`—before
+installing at current client paths. Cleanup is deliberately a separate safe
+pass, so rerun registration when the command reports that an obsolete entry
+was removed.
+
+## Safe beta reports
+
+Use the repository's **AgentCache beta feedback** issue form. Include client
+versions, source and destination adapter IDs, command shape, expected result,
+actual result, and sanitized diagnostics. Remove handoff tokens, lease tokens,
+absolute paths, transcript content, environment variables, credentials, and
+proprietary code before posting.

package/package.json

@@ -1,49 +1,66 @@
 {
   "name": "agentcache",
-  "version": "0.4.2",
-  "description": "Knowledge cache for AI agents — learns how you work, remembers across sessions, works everywhere",
+  "version": "0.5.0-beta.2",
+  "description": "Same-machine cross-agent session continuity with explicit user-selected handoffs",
   "type": "module",
   "license": "MIT",
   "author": "a21.ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/raghav-a21ai/agentcache"
+    "url": "git+https://github.com/raghav-a21ai/agentcache.git"
   },
   "homepage": "https://github.com/raghav-a21ai/agentcache#readme",
   "keywords": [
     "ai",
     "mcp",
-    "knowledge",
-    "compiler",
-    "engineering",
+    "session-continuity",
+    "cross-agent",
+    "handoff",
     "claude",
     "cursor",
     "codex",
     "ide",
-    "llm",
     "developer-tools"
   ],
   "engines": {
-    "node": ">=20.12.0"
+    "node": ">=22"
   },
   "bin": {
     "agentcache": "dist/cli.js"
   },
+  "exports": {
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
-    "dist"
+    "dist",
+    "docs/compatibility.md",
+    "docs/demo-script.md",
+    "docs/launch-copy.md",
+    "docs/privacy.md",
+    "docs/troubleshooting.md"
   ],
   "scripts": {
     "build": "tsup",
-    "prepare": "tsup",
-    "postinstall": "node dist/postinstall.js",
+    "prepack": "npm run build",
     "test": "vitest run",
+    "test:package": "vitest run tests/integration/package-smoke.test.ts",
+    "typecheck": "tsc --noEmit",
     "test:watch": "vitest",
     "dev": "tsx src/cli.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "better-sqlite3": "^11.0.0",
-    "commander": "^12.0.0"
+    "better-sqlite3": "12.11.1",
+    "commander": "^12.0.0",
+    "smol-toml": "^1.8.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",
@@ -51,6 +68,7 @@
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
+    "vite": "^6.4.3",
+    "vitest": "^3.2.7"
   }
 }

package/dist/3-canonicalizer-HIN2F7SZ.js

@@ -1,11 +0,0 @@
-import {
-  canonicalize,
-  computeCanonicalHash,
-  computeCanonicalKey
-} from "./chunk-GGAATZKM.js";
-import "./chunk-KFQGP6VL.js";
-export {
-  canonicalize,
-  computeCanonicalHash,
-  computeCanonicalKey
-};

package/dist/chunk-5UO7NJPQ.js

@@ -1,71 +0,0 @@
-// src/utils/ide-detector.ts
-import { existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-function getRooConfigPath() {
-  const home = homedir();
-  if (process.platform === "darwin") {
-    return join(home, "Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json");
-  }
-  if (process.platform === "win32") {
-    return join(process.env.APPDATA || join(home, "AppData/Roaming"), "Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json");
-  }
-  return join(home, ".config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json");
-}
-function getWindsurfConfigPath() {
-  const home = homedir();
-  return join(home, ".codeium", "windsurf", "mcp_config.json");
-}
-function getContinueConfigPath() {
-  const home = homedir();
-  return join(home, ".continue", "mcpServers", "agentcache.json");
-}
-function getCodexConfigPath() {
-  const home = homedir();
-  return join(home, ".codex", "config.toml");
-}
-function detectInstalledIdes() {
-  const home = homedir();
-  return [
-    {
-      name: "Claude Code",
-      detected: existsSync(join(home, ".claude")),
-      mcpConfigPath: join(home, ".claude.json"),
-      mcpConfigFormat: "claude-settings"
-    },
-    {
-      name: "Cursor",
-      detected: existsSync(join(home, ".cursor")),
-      mcpConfigPath: join(home, ".cursor", "mcp.json"),
-      mcpConfigFormat: "mcp-json"
-    },
-    {
-      name: "Roo Code",
-      detected: existsSync(getRooConfigPath()),
-      mcpConfigPath: getRooConfigPath(),
-      mcpConfigFormat: "mcp-json"
-    },
-    {
-      name: "Windsurf",
-      detected: existsSync(join(home, ".codeium", "windsurf")) || existsSync(join(home, ".windsurf")),
-      mcpConfigPath: getWindsurfConfigPath(),
-      mcpConfigFormat: "mcp-json"
-    },
-    {
-      name: "Continue",
-      detected: existsSync(join(home, ".continue")),
-      mcpConfigPath: getContinueConfigPath(),
-      mcpConfigFormat: "continue-dir"
-    },
-    {
-      name: "Codex",
-      detected: existsSync(join(home, ".codex")),
-      mcpConfigPath: getCodexConfigPath(),
-      mcpConfigFormat: "codex-toml"
-    }
-  ];
-}
-
-export {
-  detectInstalledIdes
-};