supracortex 0.0.0-stage → 0.2.0

package/COMPATIBILITY.md

@@ -0,0 +1,171 @@
+# Compatibility
+
+This document records the environment SupraCortex was built against, the hosts
+that have actually been exercised, and the API assumptions the adapters depend
+on. Status is as of **2026-10-17**. If a host or dependency changes, the
+compatibility suite is the first place a break should surface.
+
+Verification levels used below:
+
+- **Live-tested**: a real host session was run against this repository's build.
+- **Wiring live-verified**: the real host binary accepted, listed, and removed
+  the server against this repository's build in an isolated config directory,
+  but a full model-driven session was not exercised.
+- **Fixture/tarball-verified only**: config generation/merge/uninstall and the
+  packed MCP stdio server are covered by tests, but no live session of that host
+  was run.
+- **Documented only**: wiring is documented and may have config fixtures; there
+  is no live-session verification claim.
+- **Untested**: no verification claim.
+
+## Verified environment
+
+| Component | Version | Notes |
+|---|---|---|
+| OpenCode | 1.18.32 | V1 plugin host (`opencode --version`) |
+| `@opencode-ai/plugin` | 1.18.32 | V1 plugin + tool API (pinned in `package.json`) |
+| `@opencode/plugin` | 2.0.16 | V2 plugin API (pinned in `package.json`) |
+| `@opencode-ai/sdk` | 1.18.32 | Client used for git/MCP discovery (transitive) |
+| Node.js | 22.23.1 | Built CLI + stdio MCP server; declared minimum is 22.6 |
+| pnpm | 11.9.0 | Workspace manager; npm also works |
+| MCP SDK | 1.29.0 | `@modelcontextprotocol/sdk` (pinned) |
+| CI platforms | Ubuntu, macOS, Windows | Workflow matrix for typecheck, tests, and the tarball gate |
+
+## MCP toolset
+
+MCP hosts receive the tools documented in [MCP_PROTOCOL.md](./MCP_PROTOCOL.md):
+the stable `cortex_*` set plus the experimental graph, Jev, and capability
+tools. The native OpenCode adapter is a **superset**: it adds lifecycle hooks and
+orchestration tools (planning, file claims, cache validation, compaction, sweep,
+metrics, SupraSpace sync, graph export).
+
+Host capabilities are not identical. MCP is tools-only here: automatic context
+injection, lifecycle hooks, usage observation, and other host-side integration
+are available only where the adapter is supported. Do not assume equivalent
+behavior across hosts.
+
+## Host status
+
+| Host | Wiring | Status |
+|---|---|---|
+| OpenCode 1.18.32 (V1) | Native V1 plugin via `supracortex init` | **Live-tested on this machine** |
+| OpenCode 2.0.16 (V2) | Native V2 plugin | **Fixture/tarball-verified only**; no separate live V2 session recorded here |
+| Claude Code 2.1.283 | `supracortex connect claude` (user scope) or project `init` | **Wiring live-verified**: add/list/remove in an isolated `CLAUDE_CONFIG_DIR` reported `Connected`; full model session not exercised |
+| Codex CLI 0.162.1 | `supracortex connect codex` (`~/.codex/config.toml`) or project `init` | **Wiring live-verified**: add/list/remove in an isolated `HOME`; `mcp list` does not health-check, so liveness is covered by the stdio handshake test |
+| Pi | Bundled extension; adapter is experimental | **Fixture/tarball-verified only**; no live session here; the pinned upstream patch is not shipped |
+| Cursor | `mcpServers` config fixture / custom target | **Documented only**; no live session |
+| Gemini CLI | `mcpServers` config fixture (bare style) | **Documented only**; no live session |
+| DeepSeek Harness | MCP stdio via custom target or `connect generic` snippet | **Untested** |
+| Other MCP stdio clients | `connect generic` snippet or `--target name=path[:bare]` | **Documented only**; verify in your client |
+| ChatGPT web | Local stdio server | **Unsupported**; a browser session cannot launch a local stdio MCP server |
+
+"Fixture/tarball-verified" means the generated configuration is tested for
+create/merge/uninstall and the MCP server is tested over real stdio from the
+packed artifact. It does not assert that the vendor's current client was run
+against it.
+
+## OpenCode version matrix
+
+| OpenCode | Status | Notes |
+|---|---|---|
+| 1.18.x | Yes (verified 1.18.32) | Target. `dispose`, `tool`, and `experimental.chat.system.transform` are present. |
+| 1.17.x and earlier | Untested | Plugin API may differ; `doctor` reports mismatches. |
+| 1.19+ | Expected | Uses hooks present in 1.18; re-run compatibility tests after upgrading. |
+
+## Node.js matrix
+
+| Node | Status | Notes |
+|---|---|---|
+| >= 22.6 | Yes | Built CLI and stdio MCP server (`node:sqlite`). Running `.ts` sources directly needs Node's default type-stripping, enabled by default only on newer 22.x; 22.6–22.17 need `--experimental-strip-types` (the MCP source fallback passes it). |
+| 22.0–22.5 | Partial | `node:sqlite` may need a flag. The JSONL driver is unaffected. |
+| < 22 | No | Required built-ins are unavailable. |
+
+## Windows and shell support
+
+The core, CLI, and stdio MCP server run on Node.js and are designed for macOS,
+Linux, and Windows. The compatibility CI matrix runs typecheck and tests on
+Ubuntu, macOS, and Windows, and the packed-tarball gate exercises the Node MCP
+entrypoint on all three.
+
+The `supracortex-mcp` launcher is a **POSIX bash script** and is not supported
+on Windows. On Windows, invoke the Node entrypoint:
+
+```powershell
+node C:\path\to\supracortex\dist\cli.js mcp
+node C:\path\to\supracortex\dist\cli.js init --yes
+node C:\path\to\supracortex\dist\cli.js doctor
+```
+
+For an installed package use
+`node node_modules\supracortex\dist\cli.js ...`. Bash, Zsh, Fish, PowerShell,
+and CMD can invoke the Node CLI; unusual shells are not claimed as verified.
+Host applications remain responsible for their own platform support.
+
+## Recorded API assumptions
+
+These were verified by inspecting installed type definitions and docs.
+
+### Plugin API (`@opencode-ai/plugin`)
+
+- A plugin is `(input, options?) => Promise<Hooks>`, exported as a named export.
+  `PluginInput = { client, project, directory, worktree, serverUrl, $,
+  experimental_workspace }`.
+- `Hooks` includes `dispose()`, `event`, `config`, `tool`, `chat.message`,
+  `chat.params`, `chat.headers`, `permission.ask`, `command.execute.before`,
+  `tool.execute.before`, `tool.execute.after`, `shell.env`, and experimental
+  hooks including `experimental.chat.system.transform`.
+- `dispose()` exists and is used to flush metrics. There is no documented
+  hot-unload; full module unload requires a new session.
+- Tools use `tool()` with zod argument shapes. `ToolContext` supplies
+  `sessionID`, `messageID`, `agent`, `directory`, `worktree`, `abort`,
+  `metadata()`, and `ask()`.
+
+### Commands
+
+OpenCode does not support plugin-registered commands. Commands are markdown
+files in `.opencode/commands/` (project) or
+`~/.config/opencode/commands/` (global), with frontmatter and template features.
+This project installs its slash commands as markdown files that shell out to the
+CLI.
+
+### Plugin load locations
+
+- Project: `.opencode/plugins/`. Global: `~/.config/opencode/plugins/`.
+- `supracortex init` writes its project loader to
+  `.opencode/plugins/supracortex.ts`; it does not modify unrelated plugin or
+  agent files.
+
+### SDK client (`@opencode-ai/sdk`)
+
+- Namespaces used: `find.{text,files,symbols}`, `file.{list,read,status}`,
+  `mcp.status`, `vcs.*`, `config`, `session`, `project`, `command.list`.
+- MCP discovery uses `client.mcp.status()`; the response shape is normalized
+  defensively (array, `{servers:[]}`, or a name→server map).
+
+## Behaviors that depend on optional runtime support
+
+| Behavior | Requires | Fallback |
+|---|---|---|
+| Git-changed-file bias in context | `$` shell + git available | Omitted; retrieval still works. |
+| MCP recommendations | `client.mcp.status()` present | Empty recommendation set. |
+| Automatic prompt injection | OpenCode experimental message/system transform hooks and `integration.automaticContextPreparation` | No automatic packet; tools remain callable. |
+| SQLite driver | `node:sqlite` (or `bun:sqlite` on Bun) | JSONL is the default. A configured SQLite store that cannot open surfaces an error instead of switching drivers. |
+| Full module unload on disable | Not available in OpenCode 1.18.x | Feature gate makes it inert; a new session fully unloads. |
+| Code-graph automatic hints | Explicit graph rebuild + `graph.automaticContext: true` | Graph tools still work explicitly; retrieval uses file/memory ranking. |
+
+## Not implemented and not claimed
+
+- **Provider-level prompt caching** (for example Anthropic cache-control) is not
+  implemented. Only local summary/context caching exists, and it is never
+  labelled as a provider cache hit.
+- **Exact provider billing amounts.** The host does not surface per-request
+  billed usage to the adapter, so token figures are local estimates.
+- **True hot-unload** of the OpenCode plugin module from a running process is not
+  supported by the 1.18.x lifecycle.
+- **Periodic/timer sweeps.** OpenCode exposes no timer hook, so the staleness
+  sweep runs opportunistically (engine init, `session.idle`, `session.deleted`)
+  and on demand. It is idempotent.
+- **ChatGPT web or any browser-only MCP client.** Local stdio cannot be launched
+  from a web session.
+- **Unverified host parity.** Supported hosts and their verification level are
+  the table above; anything not listed is documented-only or untested.

package/INSTALL.md

@@ -0,0 +1,229 @@
+# SupraCortex — Install tutorial
+
+A short, copy-paste guide for installing SupraCortex as an MCP server and CLI.
+For architecture, host status, and the full tool contract see
+[README.md](./README.md), [COMPATIBILITY.md](./COMPATIBILITY.md), and
+[MCP_PROTOCOL.md](./MCP_PROTOCOL.md).
+
+SupraCortex is designed for **MCP stdio clients**; verified and unverified hosts
+are listed in the README support matrix. You do **not** need OpenCode to use the
+MCP server. The OpenCode adapter is an optional extra that adds native tools and
+lifecycle hooks.
+
+---
+
+## 0. Prerequisites
+
+- **Node.js >= 22.6** (declared in `package.json`) for the CLI and stdio MCP
+  server. Check with:
+  ```bash
+  node --version
+  ```
+- **npm** (bundled with Node) for the packaged install. `pnpm` is only needed
+  when working from a source checkout.
+
+---
+
+## 1. Install the CLI
+
+Global install (recommended if you want `supracortex` on your PATH):
+
+```bash
+npm install -g supracortex
+supracortex --version
+```
+
+Local install (use `npx` or `node_modules/.bin`):
+
+```bash
+npm install supracortex
+npx supracortex --version
+```
+
+From a source checkout, build once and use the Node entrypoint:
+
+```bash
+cd /path/to/supracortex
+pnpm install
+pnpm run build
+node dist/cli.js --version
+```
+
+The package ships two entry points: the `supracortex` CLI
+(`dist/cli.js`) and the `supracortex-mcp` stdio shim. They resolve the project
+root the same way, so hosts can use either.
+
+---
+
+## 2. Wire the project
+
+Run this inside each project you want SupraCortex to remember:
+
+```bash
+cd /path/to/your/project
+supracortex init --yes
+```
+
+- Without `--yes`, `init` prints a **plan only** and changes no files.
+- With `--yes`, it wires the project and detected hosts, writes the guidance it
+  owns, enables the project, and backfills the project index.
+- Limit detection with `--agent claude` (repeatable; known values: `claude`,
+  `codex`, `cursor`, `gemini`, `opencode`, `pi`).
+- Wire another CLI on the standard `mcpServers` convention with
+  `--target name=relative/path.json[:bare]`. The `:bare` suffix omits the `type`
+  field for clients that reject it.
+
+Runtime state is created lazily under `<project>/.supracortex/`. The generated
+`.supracortex/.gitignore` keeps runtime memory, tasks, and cache out of Git
+while leaving `config.jsonc`, `config.schema.json`, and `.supracortexignore`
+visible. Settings stay central in `~/.config/supracortex/config.jsonc`; a
+project file holds only store identity and a per-project kill switch.
+
+---
+
+## 3. Register the host
+
+`init` handles project-local wiring. `connect` additionally registers the server
+for a host once, at user/global scope:
+
+```bash
+supracortex connect claude     # Claude Code user scope
+supracortex connect codex      # Codex ~/.codex/config.toml marker block
+supracortex connect generic    # print an mcpServers JSON snippet
+supracortex connect all        # claude + codex
+```
+
+Then **restart the host** so it loads the server. The server entry point is:
+
+```bash
+supracortex mcp
+```
+
+For a local install use `npx supracortex mcp` or the `supracortex-mcp` shim; on
+Windows use the Node entrypoint. The server resolves its project root as
+`SUPRACORTEX_ROOT ?? process.cwd()`, so the host must launch it with its working
+directory set to the project root (or export `SUPRACORTEX_ROOT`). Launching it
+elsewhere creates or reads a different `.supracortex/`.
+
+For a host with no built-in adapter, paste the `connect generic` snippet into
+its MCP configuration. This documents the wiring convention; it is not a claim
+that the host has been live-tested.
+
+| Host | Recommended wiring | Verification level |
+|---|---|---|
+| Claude Code | `supracortex connect claude` or project `init` | Wiring live-verified |
+| Codex CLI | `supracortex connect codex` or project `init` | Wiring live-verified |
+| OpenCode V1 | Project `init` installs the native V1 plugin | Live-tested |
+| OpenCode V2 | Project `init` installs the native V2 plugin | Fixture/tarball-verified only |
+| Cursor | `init` detection or a custom `--target` | Documented only |
+| Gemini CLI | `init` detection or a bare `--target` | Documented only |
+| Pi | Bundled experimental extension | Fixture/tarball-verified only |
+| Other MCP stdio clients | `connect generic` snippet | Documented only |
+
+See [COMPATIBILITY.md](./COMPATIBILITY.md) for the full status definitions and
+recorded versions.
+
+Disconnect with `supracortex disconnect claude`, `disconnect codex`, or
+`disconnect all`.
+
+---
+
+## 4. Verify
+
+From the project directory:
+
+```bash
+supracortex doctor                  # health checks; exit 1 if a check fails
+supracortex status                  # enabled state, storage, counts, last error
+supracortex status --json           # machine-readable
+supracortex inspect "fix login"     # preview the context packet, no model call
+```
+
+Inside OpenCode, the equivalent slash commands are `/cortex-status`,
+`/cortex-doctor`, and `/cortex-inspect <query>`. Other hosts call the MCP tools
+directly (`cortex_status`, `cortex_context`, ...).
+
+If `doctor` fails, read its first failing check; it names the file or setting it
+could not validate. `supracortex doctor --fix` can repair the loader wiring.
+
+---
+
+## 5. Everyday commands
+
+| Task | Command |
+|---|---|
+| Status | `supracortex status` |
+| Health check | `supracortex doctor` |
+| Enable this project | `supracortex enable` |
+| Disable this project | `supracortex disable` |
+| Preview context | `supracortex inspect "task"` |
+| Compact memory | `supracortex compact` |
+| Rebuild the experimental code graph | `supracortex code-graph rebuild --yes` |
+| Clear generated data (keeps memory) | `supracortex reset all-generated --yes` |
+
+Emergency kill switch (overrides configuration):
+
+```bash
+export SUPRACORTEX_DISABLE=1        # macOS/Linux
+$env:SUPRACORTEX_DISABLE = "1"      # Windows PowerShell
+```
+
+`SUPRACORTEX_ENABLE=1` is also honoured, but disable wins.
+
+---
+
+## 6. Uninstall
+
+Uninstall is mutating, so it requires `--yes`. Data is kept by default:
+
+```bash
+# Remove wiring, keep memory and configuration:
+supracortex uninstall --yes
+
+# Remove runtime data as well:
+supracortex uninstall --yes --remove-data
+
+# Global install:
+supracortex uninstall --global --yes
+```
+
+Uninstall removes only files it owns and reverts only its own marker block in
+shared files. It does not touch your source files.
+
+---
+
+## 7. Windows
+
+The `supracortex-mcp` launcher is a POSIX bash script and is **not supported on
+Windows**. Use the Node entrypoint instead:
+
+```powershell
+node C:\path\to\supracortex\dist\cli.js init --yes
+node C:\path\to\supracortex\dist\cli.js connect generic
+node C:\path\to\supracortex\dist\cli.js doctor
+node C:\path\to\supracortex\dist\cli.js mcp
+```
+
+For an installed package, replace the path with
+`node_modules\supracortex\dist\cli.js`. The compatibility CI matrix exercises
+the Node CLI and MCP transport on Windows.
+
+---
+
+## Gotchas
+
+1. **Restart the host** after install, connect, or enable/disable. A running
+   OpenCode session needs a new session to fully reload the plugin module.
+2. **Paths matter.** `supracortex init` records absolute paths for a source
+   checkout. If you move or rename the checkout, re-run `init --yes`.
+3. **One project root.** Every host that should share memory must launch
+   `supracortex mcp` with the same working directory (or the same
+   `SUPRACORTEX_ROOT`).
+4. **Global install is enabled everywhere by default.** Opt one project out
+   with `supracortex disable` inside it; `enable` removes the opt-out. Settings
+   themselves stay central.
+5. **SQLite is opt-in.** JSONL is the default. If `storage.driver` is set to
+   `"sqlite"` and the database cannot open, the engine reports an error rather
+   than silently switching stores.
+6. **No hot unload.** Disabling makes the adapter inert immediately; a new host
+   session completes the unload.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 supracortex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MCP_PROTOCOL.md

@@ -0,0 +1,100 @@
+# SupraCortex MCP tool contract
+
+The stdio adapter (`supracortex mcp` or the `supracortex-mcp` shim) exposes the
+tools below. Protocol JSON is written to stdout; diagnostics are written only to
+stderr. The toolset API version is `2.0.0`; it is distinct from the date-based
+MCP protocol version negotiated by the SDK.
+
+## Stability tiers
+
+| Tier | Tools |
+|---|---|
+| **STABLE** | `cortex_context`, `cortex_search`, `cortex_record`, `cortex_status`, `cortex_timeline`, `cortex_detail`, `cortex_handoff`, `cortex_resume`, `cortex_review`, `cortex_safety` |
+| **EXPERIMENTAL** | `cortex_graph_status`, `cortex_graph_rebuild`, `cortex_graph_query`, `cortex_graph_path`, `cortex_graph_explain`, `cortex_graph_impact`, `cortex_jev_status`, `cortex_jev_review`, `cortex_capabilities` |
+
+Stable tools are the supported contract. Experimental tools may change in shape
+or behavior between releases; consumers should tolerate additive fields and pin
+any integration that depends on their exact output.
+
+The code-graph tools are experimental local navigation: they require an explicit
+`cortex_graph_rebuild` before queries return a generation. Automatic graph hints
+are off by default and require both a built generation and
+`graph.automaticContext: true`.
+
+## Stable tools
+
+| Tool | Purpose |
+|---|---|
+| `cortex_context` | Prepare a bounded, explained context packet for a task. Read-only and deterministic. |
+| `cortex_search` | Search persistent memory for relevant entries. Read-only. |
+| `cortex_record` | Record a verified memory entry or task outcome. Durable kinds require source references; secret-shaped content is redacted. |
+| `cortex_status` | Report enabled state, storage, counts, and the last error. Read-only. |
+| `cortex_timeline` | Return a bounded chronological window of structural events. Read-only. |
+| `cortex_detail` | Show one structural event by id. Read-only. |
+| `cortex_handoff` | Create a bounded handoff capsule with goal, work, risks, and next actions. |
+| `cortex_resume` | Read a previously created handoff capsule. Read-only. |
+| `cortex_review` | List candidates or move an entry through the review actions below. |
+| `cortex_safety` | Report observed local evidence for changed files. It never runs git, tests, shells, or scanners. |
+
+## Inputs and output shape
+
+- Inputs use strict schemas and are bounded per field and as a complete JSON
+  argument payload (**32,000 UTF-8 bytes**).
+- `content[0]` is always a JSON text block containing the tool result. If an
+  advisory is present (for example the untrusted-data notice on
+  `cortex_context` / `cortex_search`), it is a separate trailing text item and
+  is never merged into the validated JSON payload.
+- `structuredContent` carries the same JSON object as `content[0]`. A non-object
+  result is wrapped as `{ "value": ... }`.
+- Text and `structuredContent` are each bounded to **48,000 UTF-8 bytes**. An
+  oversized result returns a small, valid truncation envelope
+  (`truncated`, `limitBytes`, `result`) rather than half-serialized JSON.
+- Tool listings include strict input and output JSON schemas plus
+  read-only/destructive annotations where applicable. Output schemas are
+  advertised permissively so a host validating `structuredContent` cannot reject
+  a committed result; the server still validates strictly before returning.
+- Disabled projects return `{ "disabled": true, "noop": true }` successfully and
+  perform no writes. Invalid input is a model-visible tool error.
+- An abort signal observed before a mutating commit returns an error and does not
+  mutate storage.
+
+The server advertises tools only: no resource, prompt, or completion capability
+is exposed until it has a stable, bounded implementation.
+
+## `cortex_review` actions
+
+| Action | Semantics |
+|---|---|
+| `list` | List entries by status (default `candidate`). Read-only. |
+| `approve` | Verify every hashed file reference against the current index, then set the entry `active`. This is the activation step. |
+| `edit` | Update content, confidence, or tags. Does not re-verify evidence. |
+| `dispute` | Mark the entry `disputed` for contradiction review. |
+| `invalidate` | Mark the entry `stale` explicitly because its evidence is no longer trusted. |
+| `pin` | Add the `pinned` tag so retrieval keeps the entry prominent. |
+| `suppress` | Set the entry to `forgotten` so it is no longer surfaced. |
+| `purge` | Delete the entry. Destructive and irreversible. |
+| `refresh-evidence` | Re-read current hashed file references, store the new hashes, set `lastVerifiedAt`, and clear `needsReverifyAt`. It never activates the entry. If any referenced file is missing, the action fails with the `missing` paths, changes nothing, and writes no audit row. |
+
+Age-based re-verification sets `needsReverifyAt` without changing `status`.
+`stale` means an evidence mismatch or explicit invalidation. The recovery order
+is `refresh-evidence`, then `approve` when activation is intended.
+
+`cortex_record` accepts an explicit verified memory or task outcome only;
+candidate or imported text is not recorded as active memory through this
+surface. Imported or candidate content never becomes active without an explicit
+`approve`.
+
+`cortex_safety` reports observed evidence only and never runs git, tests, shells,
+or scanners.
+
+## Output guarantees
+
+- A normal result is a single, schema-valid JSON object in `content[0]` and
+  `structuredContent`; optional advisory text is separate.
+- Results never exceed the 48,000-byte cap; oversized results are replaced by a
+  valid truncation envelope.
+- Unknown input fields are rejected rather than ignored.
+- Tools annotated read-only do not mutate memory, tasks, or graph state.
+  Mutating tools either commit fully or return an error without committing when
+  aborted first.
+- Disabled projects are a successful no-op, not an error.