内容
<p align="center">
<img src="assets/sando-mark.png" alt="Sando logo" width="96">
</p>
# Sando
[](https://github.com/yuzushi-dev/Sando/actions/workflows/hol-plugin-scanner.yml)
[](https://github.com/yuzushi-dev/Sando/actions/workflows/hol-plugin-scanner.yml)
**Context-management plugin for Claude Code and Codex. It bounds what a tool result costs before that result reaches the model.**
Large output is truncated to a cap set by the kind of content it is, the full bytes are kept on
disk with a verified hash, and the lines that answer the question — error lines, test totals —
are pulled out of the part that was cut. The default path is deterministic and local; the optional
TypeSafe shadow judge is measurement-only and never changes the request.
<p align="center">
<a href="sando-promo.mp4">
<img src="plugins/sando/assets/screenshot-terminal.png" alt="Sando demo: bounded output and recoverable context" width="960">
</a>
</p>
<p align="center">
<a href="sando-promo.mp4">▶ Watch the 21-second demo</a>
</p>
## Expected savings
| Surface | Reduction | Measured over | Reproduce |
|---|---|---|---|
| Codex shell output | **90.9%** (78.5M → 7.2M tokens) | 40,000+ recorded results | `node scripts/bench-codex-shell.mjs` |
| Claude `PostToolUse` tool results | **14.5% – 18.9%** | two machines | [`docs/measurements.md`](docs/measurements.md) |
| Files fitting a 200,000-token window | **~2.4x more** (2.39x–2.44x) | any git checkout | `node scripts/bench-reduction.mjs` |
These are output reductions, one tool result at a time. What a session costs also depends on
prompt-cache economics, which these numbers do not model. On Claude, text blocks of external
`mcp__*` results are now bounded too, and recoverable with `sando_artifact_get`; the published
numbers were measured before that and exclude them. Method and per-corpus variation:
[`docs/measurements.md`](docs/measurements.md).
## Install
Requirements: Claude Code or Codex, and Node.js `>=22.22.0 <23` with `node` on `PATH`
(`node --version`). Each marketplace source ships its hooks and bundles, so there is no build
step.
**Claude Code** — run in the session:
```text
/plugin marketplace add yuzushi-dev/yuzushi-plugins
/plugin install sando@yuzushi
```
**Codex**:
```bash
codex plugin marketplace add yuzushi-dev/yuzushi-plugins
```
Then open `/plugins`, select `sando`, and install/enable it. Start a new session if Codex was
already open.
On Codex the `PostToolUse` hook cannot rewrite output at all, so Sando bounds shell output by
rewriting the command before it runs. That is on by default; `SANDO_CLI_ROUTING=0` switches it
off. What the rewrite preserves is measured rather than assumed: exit codes, death by signal,
standard input, stderr and the resulting working tree all match the unwrapped run across 1,290
recorded commands, and binary output is withheld rather than bounded. See
[`docs/measurements.md`](docs/measurements.md#does-the-codex-wrap-preserve-what-it-wraps).
Approval is untouched — Codex handles that through a separate `PermissionRequest` event.
## What you get
- **Bounded tool results.** Every result is capped by content kind before the model sees it.
- **Nothing is lost.** Full bytes go to a content-addressed store with a verified hash; the
bounded result carries the command to fetch back whatever was cut.
- **The answer survives the cut.** `npm test` here prints 595 test results across two summary
blocks, 120 KB in total. Bounded, the model sees 4 KB and still answers *585 passed, 0 failed*,
because the totals are salvaged out of the elided middle. Before that salvage existed, the same
model read the surviving block and answered *100 passed*, with nothing to mark the omission.
- **Secrets redacted first,** with project-local detectors in `.sando/redaction.json`.
- **Composes, doesn't compete.** It acts on tool results only, so it stacks with output filters
or scope rules.
- **Accounting you can check.** Provider-reported tokens and mechanical trimming are recorded
separately; mechanical reduction is never turned into a provider-billing claim.
## Architecture in brief
```
host (Claude PostToolUse hook | Codex shell routing)
│ tool result
▼
redaction ──► bound to a per-kind cap ──► salvage errors + totals
│ │
▼ ▼
artifact store (sha256, on disk) preview to the model
│ + recovery handle
└──► sando artifact get / sando_artifact_get (MCP)
```
- **Three bundles**, one per host surface: `adapters/claude/sando`, `adapters/codex/sando`,
`plugins/sando`. Each carries `hooks/`, `mcp/`, `bin/`, `lib/`. The `lib/` trees are synced
from the single source in `packages/sando/src` by `scripts/sync-bundles.mjs`.
- **MCP server** exposes read-only artifact recovery, plus optional Slice symbol tools when a
natively built engine is configured.
- **Each host wires only what its manifest declares:** the hooks and the MCP surfaces. The
provider proxy and the Lazy MCP Gateway are separate processes that no host starts — you launch
them yourself or they never run. The CLI, audit, artifact recovery, statusline, metrics and
accounting launchers are likewise manual entrypoints. Sando changes no Claude or Codex global
configuration, and telemetry is off until you choose.
Release notes: [Sando 0.8.0](docs/changelogs/0.8.0.md). Development branch: `main`.
Telemetry is off by default — see the [full disclosure](TELEMETRY.md).
API cost estimates require an explicit versioned profile and complete per-request
Responses records; Codex transcript totals are not automatically priced:
```sh
npm run accounting -- --profile openai-gpt-6.1-sol-standard-2026-09-30 --requests /absolute/requests.jsonl --json
```
The available profiles cover GPT-6.1 Sol and GPT-6 Luna Standard without regional
surcharges. Select the profile matching the observed model. The estimate keeps
provider-reported amounts, normalized cost units, and API list-price estimates
separate. Unsupported requests leave the total indeterminate and retain a valid
subtotal. Codex subscription usage is not an API invoice. See the
[record format and pricing rules](docs/compatibility/pricing.md),
[Codex evidence](docs/compatibility/codex.md), and
[optional benchmark protocol](docs/compatibility/benchmark.md).
---
<details>
<summary><b>Reference: Slice symbol reads and opt-in writes</b></summary>
Slice connects Sando's MCP to a separately built native symbol engine. Build the
tested engine from a Sando source checkout with Bash, Git, Make, CMake 3.24+ and GCC 13+
(C and C++ compilers). The verified target is Ubuntu 24.04 on Linux x86-64;
other operating systems, architectures and toolchains are not verified by Sando.
```bash
# Run from the Sando checkout. The destination must not already exist.
bash scripts/build-slice.sh "$HOME/sando-slice"
```
The script fetches [upstream source at commit
`d90acb2cb3295da8ca0fd33a88e81cb51a8575fb`](https://github.com/redhat-et/ripwire/tree/d90acb2cb3295da8ca0fd33a88e81cb51a8575fb),
checks the revision and builds with vendored dependencies and CMake downloads
disabled. It retains the source and its licenses, refuses an existing destination,
and leaves a failed build in place for diagnosis. Expect several minutes of
compilation, several GB of RAM, and space for the source and build tree. It does not install hooks,
modify host configuration or install a binary globally.
Build on the machine where the MCP server runs: the executable uses that system's
C/C++ runtime libraries. This is a pinned source build, not a promise of identical
binary bytes across compilers or portability to older distributions. The native
engine is Apache-2.0, with dependency notices in its `THIRD_PARTY.md` and
`third_party/` license files; Sando's JavaScript remains MIT. Keep those notices
with any redistributed native artifact. The plugin and npm library contain no
native executable.
Configure the MCP server environment with the resulting absolute executable path
and a canonical workspace directory:
```bash
SANDO_SLICE_BINARY=/absolute/path/to/sando-slice/build/ripwire
SANDO_SLICE_ROOT=/absolute/path/to/workspace
SANDO_SLICE_WRITE=1
```
Without a valid binary and root, no Slice tools are advertised. Omit
`SANDO_SLICE_WRITE` for read-only use. Codex runs the engine inside the host's
managed restricted sandbox; missing sandbox metadata is refused.
Read tools are `sando_slice_for`, `sando_slice_find_symbol`,
`sando_slice_find_referencing_symbols`, and `sando_slice_fetch_body` (at most 400
body-relative lines per call). Writes are `sando_slice_replace_symbol_body` and
`sando_slice_insert_after_symbol`.
Find the symbol, fetch its body, then pass its `sym#…@…` identifier as the write's
`handle`. Plain names are not accepted for writes. Replacement covers exactly
the fetched definition span: preserve modifiers such as `export` that sit
outside it instead of adding them again. Stale handles are refused; read again
and reconsider the edit. Insertion before a definition is not exposed.
Slice applies Sando's project redaction rules to results and errors. Redacted
source is marked as non-round-trippable and its handle cannot be used for replacement.
The engine's handles, freshness metadata, and edit receipts are otherwise preserved.
`post_check` provides static feedback, not a test run; run project tests after
editing. If a write is interrupted or loses its response, inspect the file
before retrying: cancellation does not imply rollback.
Native integration checks use temporary workspaces. The Codex cases additionally
require the Codex CLI on `PATH` and a working host sandbox (Bubblewrap on Linux);
they are skipped when Codex is absent. CI provides both and runs every native case:
```bash
SANDO_SLICE_TEST_BINARY="$HOME/sando-slice/build/ripwire" npm test
```
Bash previews also remove ANSI formatting and retain bounded error diagnostics
from omitted output, prioritizing failures over warnings. Full admitted
artifacts retain the original redacted output; ANSI formatting is also removed
there when necessary to redact a credential split by escape sequences.
</details>
## Publish the npm package
The marketplace plugin is installed from Git tags; `sandoichi` is a separate npm package. Stable
`vX.Y.Z` tags publish `packages/sando` through the `Publish sandoichi to npm` workflow after its
tests and package check pass. The package version must match the tag.
Before the first publish, configure npm Trusted Publishing for package `sandoichi` with GitHub
owner `yuzushi-dev`, repository `Sando`, and workflow file `publish-npm.yml`. Under Allowed actions,
enable `Allow npm publish`; new trusted publishers default to staged-only publishing. The workflow
uses OIDC and needs no npm token. It tests the tagged package and enforces the npm archive allowlist
before publishing. With npm 11.15 or later and account-level 2FA enabled, the equivalent CLI setup is:
```sh
npm trust github sandoichi --repo yuzushi-dev/Sando --file publish-npm.yml --allow-publish
```
Later stable tags publish automatically. To publish the existing `v0.7.1` tag,
first run the workflow once on `main` (the publish job will be skipped), then trigger the tag with
`gh workflow run publish-npm.yml --ref v0.7.1`. See [npm Trusted Publishing docs](https://docs.npmjs.com/trusted-publishers/).
<details>
<summary><b>Reference: result progressive disclosure and artifact recovery</b></summary>
Recover a bounded byte or line range from an installed workspace artifact:
```bash
/path/to/installed/sando/bin/sando artifact get --root . --ref sando:sha256:... --start-line 1 --end-line 40 --json
# Claude bundle: node /path/to/installed/sando/artifact.mjs artifact get --root . --ref sando:sha256:... --json
```
From inside a session, the MCP server exposes the same recovery as the read-only
`sando_artifact_get` tool. It reads artifacts kept in that MCP process first, then the files
hooks wrote under the project's `.sando/sando/artifacts` (hex prefix of at least 16 characters,
exactly one match, symlinks rejected, full SHA-256 verified). On Claude the recover hint in a
bounded result names this tool; Codex keeps the CLI hint.
**Limits.** Bytes are kept for any result up to the 1 MiB artifact limit. Beyond that, and beyond
the 16 MiB a wrapped command captures, the excess is truncated at the source and marked as such.
The limit is an admission threshold, not a truncation target: if the complete redacted result
exceeds it, Sando keeps a bounded preview, issues no artifact handle, and marks recovery
unavailable rather than pretending a partial artifact is complete. On writes it removes entries
older than seven days and caps retained artifacts at 64 MiB, touching only regular
content-addressed files and never following symlinks.
**What the model sees.** The library and MCP result APIs attach a `sando-result-disclosure/v1`
record — redacted byte counts, provenance, elision markers, and the digest handle, never the
payload. Claude and Codex hook responses stay host-native and carry no disclosure metadata;
errors, current results, IDs, order, batches, and binary status are untouched.
</details>
<details>
<summary><b>Reference: experimental surfaces, not started by any host</b></summary>
Two surfaces ship in the bundle but are never launched by Claude Code or Codex. Neither is
production-ready, and neither is covered by the savings table.
**Lazy MCP Gateway.** A replacement surface for explicitly allowlisted external MCP servers, not
a wrapper around host built-ins. Configure `SANDO_MCP_GATEWAY_CONFIG` with JSON (or an explicit
JSON file path) containing `enabled`, `allowlist`, and `servers` entries with `command`/`args`,
then run `node packages/sando/gateway.mjs`. Do not expose the same MCPs through the host at the
same time. Roll back by stopping the process and removing the gateway MCP entry; `enabled: false`
is the safe kill switch. It supports initialize, ping, tools/list, catalog discovery, and
allowlisted `tools/call` through `sando_call`; other downstream paths fail closed, and auth,
approval and elicitation are intentionally unsupported. The production gate remains
`insufficient-evidence`, evaluated by `sando context gateway-gate` against a
`sando-progressive-gateway-evidence/v1` file.
**Provider proxy.** The context/history transformer behind an explicit launcher, for hosts that
support a configured local base URL. It archives older tool observations across turns. Codex
transport is untouched unless you point the client at the proxy's printed local URL:
```bash
SANDO_UPSTREAM_URL=https://api.example.test \
SANDO_PROXY_TRANSFORM=1 \
SANDO_CONTEXT_POLICY='{"maxHistoryTokens":1000}' \
/path/to/installed/sando/bin/sando-proxy
```
Request transformation is off unless `SANDO_PROXY_TRANSFORM=1`; individual transform families can
be disabled with `SANDO_CONTEXT_POLICY.strategies`. For the opt-in footprint record, also set
`SANDO_CONTEXT_FOOTPRINT_PATH`, `SANDO_CONTEXT_FOOTPRINT_HOST` (`claude` or `codex`) and an
explicit `SANDO_CONTEXT_SESSION_KEY`; the record contains no request content, and without a
session key the capture is skipped. For the local Grafana cockpit, set `SANDO_F1_TELEMETRY=1`
with the loopback-only `SANDO_F1_TELEMETRY_ENDPOINT=http://127.0.0.1:4319/v1/logs`; only
coverage and size buckets leave the capture process.
For an opt-in TypeSafe/Jev shadow measurement, install the optional `pi-typesafe` package in the
launcher environment and set `SANDO_TYPESAFE_SHADOW=1` together with `SANDO_PROXY_TRANSFORM=1`.
Sando sends only redacted, bounded samples
of eligible historical results and their deterministic previews. Jev reports whether diagnostic
evidence may have been lost; it never changes the forwarded request. The judge is fail-open and
disables itself when the package or key is unavailable. `SANDO_PROJECT_ROOT` selects the project
whose `.sando/redaction.json` should be applied; `SANDO_TYPESAFE_TIMEOUT_MS` and
`SANDO_TYPESAFE_MAX_REQUESTS` bound the optional calls. This is a measurement surface, not a
general prompt-injection guard or a semantic summarizer.
The offline semantic-quality test uses labeled diagnostic facts and an injected judge to compare
the deterministic preview with a loss-gated preview. It verifies the gate's trade-off, not Jev's
model accuracy, and never enables live request gating:
`node --test packages/sando/tests/semantic-quality.test.mjs`.
What the replays measured, and why it is not a savings claim, is in
[`docs/measurements.md`](docs/measurements.md).
</details>
<details>
<summary><b>Reference: project redaction rules</b></summary>
Teams can add project-local detectors in `.sando/redaction.json`:
```json
{
"schema": "sando-redaction/v1",
"rules": [
{ "type": "assignment-key", "key": "DATABASE_URL" },
{ "type": "token-prefix", "prefix": "acme_", "minLength": 24, "maxLength": 128 }
]
}
```
Built-in detectors remain enabled. The supported declarative rules are `assignment-key` and `token-prefix`; both use the fixed `[REDACTED]` placeholder. The profile is loaded from the current project only, and its digest is recorded in receipts. Invalid profiles are reported instead of silently ignored.
</details>
连接信息
猜你喜欢
暂无推荐服务器