Cachekite

README

# CacheKite

CacheKite is a cache-first agent harness that plugs into OpenClaw through the Agent Client Protocol (ACP). OpenClaw owns routing, channels, identity and delivery; CacheKite owns the model loop, sessions, tools, goals, steering and prompt-cache policy.

This README has two paths:

- **Host onboarding** configures CacheKite into an already-working OpenClaw installation.
- **Local proof** runs a credential-free, isolated OpenClaw + ACP + mock-DeepSeek stack in Docker.

## Fastest working setup

For a working OpenClaw installation, the first successful run should take about five minutes.

### Prerequisites

- Node.js 24 is recommended; use a version supported by your OpenClaw release. CacheKite itself requires Node.js 20 or newer.
- A working OpenClaw Gateway and the `openclaw` command on your `PATH`.
- A provider credential. The quick start uses `DEEPSEEK_API_KEY`; OpenAI-compatible and self-hosted providers are also supported.
- A normal local checkout. CacheKite has no runtime npm dependencies, so `npm install` is not required.

The onboarding helper is tested with OpenClaw `2026.7.1-2` and installs the pinned `@openclaw/acpx` `2026.7.1` backend when it is missing. Newer OpenClaw versions may work, but should be verified with the smoke path before production use.

### 1. Clone and check prerequisites

Replace `YOUR_ORG` with the GitHub owner after publication:

```sh
git clone https://github.com/YOUR_ORG/cachekite.git
cd cachekite
npm run onboarding:check
```

### 2. Configure the ACP agent and plugin

Export the provider key in the shell that will restart the Gateway. The key is inherited by the ACP child process; it is never written to the OpenClaw prompt or committed configuration.

```sh
export DEEPSEEK_API_KEY='paste-your-key-here'
npm run onboarding:configure -- --workspace "$PWD"
openclaw gateway restart
openclaw plugins inspect cache-harness-control --runtime --json
```

The helper performs additive configuration: it links the CacheKite Control plugin, installs the pinned acpx backend if needed, preserves existing ACP agents, adds the `cachekite` agent, sets the ACP allowlist/default, validates `openclaw.json`, and points acpx at the repository’s `bin/cachekite-openclaw.sh` entrypoint.

### 3. Send the first ACP prompt

Open the OpenClaw terminal:

```sh
openclaw chat
```

Run these commands inside the OpenClaw chat:

```text
/acp doctor
/acp spawn cachekite --mode persistent --thread off --cwd /absolute/path/to/cachekite --label cachekite-quickstart
/acp steer --session cachekite-quickstart Say exactly: CacheKite is online.
```

You should receive a response from the CacheKite ACP session. If your normal OpenClaw channel is already configured, you can bind the spawned session to that conversation instead of using the local chat terminal.

## Credential-free proof

Use this when you want to verify the complete integration before adding a provider key. Docker is the only extra prerequisite:

```sh
npm run onboarding:smoke
```

This copies the repository to a disposable temporary directory, runs the checks and tests there, builds the pinned OpenClaw/acpx image, starts the isolated Gateway and mock DeepSeek server, sends prompts through the authenticated OpenClaw Gateway, and verifies ACP spawning, cache reuse, goals, steering, plugin tools, cancellation, compaction, restart recovery, isolation and secret-safe logs. It writes proof to `artifacts/onboarding-proof.json`.

For the shorter repeatable sandbox command:

```sh
npm run sandbox:test
```

The sandbox keeps passing containers running for inspection. Stop or reset only this project’s resources with `npm run sandbox:stop` or `npm run sandbox:reset`. See [docs/sandbox.md](docs/sandbox.md) for the route and isolation model.

## ACP integration considerations

ACP is the process boundary between OpenClaw and an external harness. These rules matter whether the caller is OpenClaw, another ACP client, or a local test driver. The [OpenClaw ACP overview](https://docs.openclaw.ai/tools/acp-agents) and [ACP setup guide](https://docs.openclaw.ai/tools/acp-agents-setup) are the authoritative references for OpenClaw-side behavior.

### Transport and process contract

- CacheKite speaks ACP JSON-RPC over newline-delimited stdin/stdout and currently advertises `protocolVersion: 1`.
- Configure an executable path, not a shell snippet. `bin/cachekite-openclaw.sh` resolves the checkout and starts `bin/cachekite.js acp`.
- Keep stdout protocol-only. Diagnostics belong on stderr; otherwise an innocent log line can corrupt ACP framing.
- The ACP child must inherit the provider environment it needs. Restart a managed Gateway after changing that environment.
- Use an absolute working directory and ensure it exists for the OpenClaw user.

### Lifecycle, identity and persistence

- A persistent ACP session is a long-lived child/runtime association. Gateway restarts should be expected; CacheKite replays durable session events and marks interrupted runs during recovery.
- `cachekite` is the preferred OpenClaw agent ID. The legacy `cache-harness` ID and session-key prefix remain available for existing configurations; see [docs/migration.md](docs/migration.md).
- Keep `CACHE_HARNESS_DATA_DIR` on a durable, writable filesystem. Do not put production sessions in `/tmp`; back up the event files if they matter.
- Do not reuse one data directory concurrently across unrelated installations unless you intentionally want them to share sessions.

### Streaming, steering and cancellation

- ACP updates stream assistant text, reasoning, tool calls and tool results separately. A client must tolerate incremental updates and wait for the terminal response.
- Tool-call/result adjacency is part of the runtime contract. Steering is queued and applied at a safe model/tool boundary instead of rewriting a live transcript.
- Propagate cancellation to the ACP request and provider signal. A cancelled turn must not be reported as a successful completed turn.
- Goals, plans, steering and compaction are durable events, not hidden mutations to the stable system prompt.

### Cache-aware model integration

CacheKite maximizes provider prefix-cache reuse by canonicalizing stable instructions and tool schemas, appending dynamic state at the prompt tail, and making model/compaction changes explicit cache epochs. Keep the provider, model, system instructions and tool schemas stable across turns when reuse matters. Inspect token-weighted cache metrics instead of assuming that a request was cached.

### OpenClaw responsibilities

OpenClaw must have ACP enabled, the acpx backend loaded, `cachekite` in `acp.allowedAgents`, an ACP agent entry pointing at the executable, and the CacheKite Control plugin enabled if operator steering is needed. Verify the live runtime—not only a cold config—with:

```sh
openclaw config validate
openclaw plugins inspect cache-harness-control --runtime --json
```

The plugin is an authenticated bridge for `/cachekite-steer`; it does not replace ACP or own the CacheKite model loop. Plugin code runs with the harness process permissions, so only load code you trust. See [docs/openclaw.md](docs/openclaw.md) and [docs/plugins.md](docs/plugins.md).

## Providers

DeepSeek is the recommended hosted path:

```sh
export CACHE_HARNESS_PROVIDER=deepseek
export CACHE_HARNESS_MODEL=deepseek-chat
export DEEPSEEK_API_KEY='...'
```

For an OpenAI-compatible endpoint:

```sh
export CACHE_HARNESS_PROVIDER=openai
export OPENAI_API_KEY='...'
export OPENAI_BASE_URL='https://api.openai.com'
```

For a local vLLM endpoint:

```sh
export CACHE_HARNESS_PROVIDER=vllm
export VLLM_BASE_URL='http://127.0.0.1:8000'
export CACHE_HARNESS_MODEL='your-model'
```

These settings are consumed by the ACP child, not by OpenClaw’s own model provider configuration.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| `Node.js 20 or newer is required` | Install a current Node.js release and rerun `npm run onboarding:check`. |
| `OpenClaw was not found` | Install OpenClaw and ensure `openclaw --version` works in the same shell. |
| The helper reports the wrong OpenClaw version | A parent `node_modules/.bin` may be shadowing your intended binary. Set `OPENCLAW_BIN=/absolute/path/to/openclaw` and rerun `npm run onboarding:check`. |
| `@openclaw/acpx` is incompatible | Upgrade OpenClaw to the version used by this quick start, or choose a compatible pinned ACPX release in the helper before onboarding. |
| `ACP runtime backend is not configured` | Run `npm run onboarding:configure`, restart the Gateway, then run `/acp doctor`. |
| Agent is not allowed | Confirm `cachekite` appears in `acp.allowedAgents`; rerun the configure helper. |
| Plugin is installed but its command is missing | Restart the Gateway and run `openclaw plugins inspect cache-harness-control --runtime --json`. |
| `DEEPSEEK_API_KEY is required` | Export the key before restarting the Gateway so its child process inherits it. Never paste it into a prompt or commit it. |
| Data-directory permission error | Set `CACHE_HARNESS_DATA_DIR` to a writable durable directory owned by the Gateway user. |
| Cache hits stay at zero | Keep provider/model/system prompt/tool schemas stable; inspect `session/metrics` and provider-reported usage. |
| Docker sandbox cannot start | Check `docker version`, then run `npm run sandbox:reset` and retry. |

## Deeper documentation

- [OpenClaw integration](docs/openclaw.md)
- [ACP and sandbox proof](docs/sandbox.md)
- [Harness plugins](docs/plugins.md)
- [Architecture task breakdown](docs/tasks.md)
- [Branding and migration compatibility](docs/migration.md)
- [Branding decision](docs/branding.md)

## Development

```sh
npm run check
npm test
npm run onboarding:smoke
```

The `cache-harness` executable and `CACHE_HARNESS_*` settings remain compatibility interfaces. New installations should use `cachekite`; technical compatibility details are intentionally kept in the migration document rather than the quick start.