<div align="center">

# codex-jev-compaction

**Keep the evidence. Carry less context.**

Jev-powered context handoffs for Codex — original text, visible decisions, conservative fallbacks.

[![CI](https://github.com/Wang-auspicious/codex-jev-compaction/actions/workflows/ci.yml/badge.svg)](https://github.com/Wang-auspicious/codex-jev-compaction/actions/workflows/ci.yml)
[![MIT](https://img.shields.io/badge/license-MIT-0e8a70)](LICENSE)
[![Node](https://img.shields.io/badge/node-22%2B-334155)](package.json)

[Quick start](#quick-start) · [How it works](#how-it-works) · [Measured results](#measured-results) · [简体中文](README.zh-CN.md) · [Pi edition](https://github.com/Wang-auspicious/pi-jev-compaction)

</div>

![How Codex context curation works](docs/architecture.svg)

A real Codex plugin containing a **skill**, a **stdio MCP tool**, and a **zero-dependency CLI**. Give it explicit context blocks; it returns a traceable JSON or Markdown packet for the next task or session.

**This release prepares explicit handoffs. It does not replace Codex native automatic compaction, reclaim tokens in the current conversation, or modify Codex session files.**

## What and why

Long tasks accumulate tool output that is no longer useful. A generated summary can lose an exact constraint, path, or error. This plugin asks Jev a narrower question: *should this old, verified read-only tool pair remain in the handoff?*

Jev returns classification probabilities. Code decides which evidence is eligible, validates every answer, preserves protected content, and builds the packet. Retained source text stays verbatim and in order. Selection itself is lossy: removed evidence is absent, and a classifier can be wrong. Keep the original input as the authoritative archive.

This is an independent Codex implementation inspired by [tamaratran/fast-jev-compaction](https://github.com/tamaratran/fast-jev-compaction), with a different host integration and explicit preservation rules.

## Quick start

Requirements: **Node.js 22+** on `PATH`, a Codex CLI with `codex plugin`, and a TypeSafe API key for live selection. Local host acceptance used **Codex CLI 0.153.4 on Windows**. The source has no runtime npm dependencies or build step.

```sh
codex plugin marketplace add Wang-auspicious/codex-jev-compaction
codex plugin add codex-jev-compaction@codex-jev-compaction
```

To pin a release, add `--ref v0.1.0` to the marketplace command. The marketplace name and plugin name are both `codex-jev-compaction`.

Set the key in the environment that launches Codex. Keep it out of plugin manifests, source files and shell-history literals. For **PowerShell 7**:

```powershell
$env:TYPESAFE_API_KEY = Read-Host 'TypeSafe API key' -MaskInput
codex
```

For **Bash**:

```bash
read -rsp 'TypeSafe API key: ' TYPESAFE_API_KEY
export TYPESAFE_API_KEY
codex
```

Open a **new Codex task** after installing or changing the launch environment. Desktop apps must inherit the same environment; installing a plugin cannot inject a key into an already running process.

Then ask:

> Use the jev-handoff skill to prepare a context handoff from these source blocks. Keep my instructions, paths, unresolved work and unverified actions. Show what was removed and why.

The skill calls `curate_context`. It uses exact visible evidence or a source artifact you provide; it cannot retrieve hidden or missing history. Missing keys are supported: the tool returns the original blocks with an explicit reason and sends nothing.

### Install from a checkout or release ZIP

Clone the repository or extract the source ZIP, then run:

```sh
codex plugin marketplace add /absolute/path/to/codex-jev-compaction
codex plugin add codex-jev-compaction@codex-jev-compaction
```

Point Codex at the repository root containing `.agents/plugins/marketplace.json`. No `npm install` is needed to use the plugin.

## Use the MCP tool

The server is named `jev_context`; its tool is `curate_context`. This minimal input is also a safe installation check:

```json
{
  "goal": "Finish the parser fix and keep generated files unchanged.",
  "blocks": [
    {
      "id": "request-1",
      "role": "user",
      "content": "Finish the parser fix and keep generated files unchanged."
    },
    {
      "id": "next-1",
      "role": "context",
      "content": "TODO: run the parser regression test.",
      "status": "open"
    }
  ]
}
```

Expected result: `status: "unchanged"`, `reason: "nothing_eligible"`, `stats.requests: 0`. Both blocks are protected; this check does **not** test Jev connectivity.

For selection, supply actual tool evidence with matching `callId` values:

```json
{
  "goal": "Investigate the current warning.",
  "preserveRecent": 1,
  "blocks": [
    { "id": "u1", "role": "user", "content": "Investigate the warning. Do not publish." },
    {
      "id": "c1", "role": "tool_call", "callId": "read-1",
      "toolName": "read", "readOnly": true, "verified": true,
      "content": "Read the previous console output."
    },
    {
      "id": "r1", "role": "tool_result", "callId": "read-1",
      "content": "Previous run: completed successfully; no warning was present."
    },
    { "id": "a1", "role": "assistant", "content": "The current warning still needs investigation." }
  ]
}
```

This small example demonstrates the contract; metadata overhead may make its handoff larger than its input. Use truthful metadata. `verified: true` on the call means the read completed and its result was observed and verified. An explicit `verified: false` on either member protects the pair. Never relabel shell commands, edits, sends or deletes as read-only reads.

| Field | Meaning |
| --- | --- |
| `goal` | Required, nonempty current goal. |
| `blocks` | Required ordered list of exact source blocks. |
| `id` | Required unique source identifier. |
| `role` | `system`, `developer`, `user`, `assistant`, `context`, `tool_call`, or `tool_result`. |
| `content` | Required exact source text; never a fabricated or abbreviated transcript. |
| `callId` | Required for tool blocks, shared by a call and its result. |
| `toolName` | Eligible call names: `read`, `read_file`, `search`, `list`, `inspect`, `fetch`. Unknown names remain protected. |
| `readOnly`, `verified` | Both must be explicitly true on an eligible call. |
| `pin` | `true` always preserves the block and its tool partner. |
| `status` | `open` protects unresolved work; `resolved` does not override other protection. |
| `preserveRecent` | Number of newest blocks to preserve. Default `4`; minimum `1`. |

## Use the CLI

From the repository root:

```sh
# Offline, no key or service required
node plugins/codex-jev-compaction/scripts/cli.mjs --input fixtures/minimal.json --offline

# Live selection when the environment contains TYPESAFE_API_KEY
node plugins/codex-jev-compaction/scripts/cli.mjs --input context.json --format markdown > handoff.md

# Markdown source: preserve the whole document as one protected block
node plugins/codex-jev-compaction/scripts/cli.mjs --input notes.md --goal "Continue the parser fix" --format markdown
```

JSON can also arrive on stdin. `--format json` is the default. The CLI writes only to stdout and never overwrites source files itself. When redirecting output, use a different filename. Plain Markdown is treated as protected source text; it is **not** silently parsed into invented tool pairs or advertised as semantically pruned.

Attach the resulting packet to a new task, or explicitly reference it next session. The receiving agent should read it as historical evidence, inspect current files, and verify incomplete external actions before continuing.

## How it works

1. **Pin before inference.** Preserve all narrative and instruction blocks, recent evidence, explicit pins, ordinary path-bearing text and known unfinished markers. A tool pair is indivisible.
2. **Restrict the candidates.** Only a complete, unambiguous one-call/one-result pair from a known read-only operation with a verified result can qualify. Unknown tools, writes and incomplete pairs stay.
3. **Show Jev the evidence.** Send the complete supplied goal and blocks as `state` to `https://api.typesafe.ai/v1/systemone`, using `model: "jev-latest"`. Each `noul` question asks whether an eligible pair should be kept. Tool results are not omitted or abridged.
4. **Keep uncertainty.** Drop a candidate pair only when its validated keep probability is **below 0.2**. Values at or above 0.2 retain it. A probability is not a proof of irrelevance.
5. **Apply atomically.** Every batch must return every requested probability as a finite number in `[0, 1]`. Any failure abandons all proposed removals.
6. **Make the decision inspectable.** Return retained source blocks, per-id decisions and content-size measurements. Markdown uses literal fenced blocks, not a generated summary.

The API key travels only in the authorization header. When selection runs, **all supplied evidence**, including protected blocks, is sent to TypeSafe so the classifier can see the constraints. Do not include credentials or material you are not authorized to share. The plugin does not log keys, provider error bodies or transcript text.

### Limits and fallback behavior

| Condition | Result |
| --- | --- |
| No eligible pair | Complete input retained; `nothing_eligible`; no API call. |
| No key | Complete input retained; `missing_api_key`; no API call. |
| State above 24,000 UTF-8 bytes | Complete input retained; `evidence_too_large`; no evidence truncation. |
| HTTP failure or rate limit | Complete input retained; `http_<status>`. |
| Network error / 15-second total timeout | Complete input retained; `network_error` / `timeout`. |
| Malformed JSON, missing answer, invalid probability | Complete input retained; `invalid_response`. |
| Invalid input contract | CLI exits nonzero; MCP returns a tool error. No filtering is performed. |

Each serialized request is bounded to 56,000 bytes; state plus the longest question is bounded to 28,000 bytes. UTF-8 bytes are a conservative budgeting proxy, not measured model tokens. At most 24 questions are sent per batch. Batches run sequentially under one deadline, without retries.

This conservative first release works on bounded evidence packets. Large raw sessions may exceed the limit and remain unchanged. Path recognition covers slash/backslash paths and common filenames; arbitrary filenames and every language's unfinished-work phrasing cannot be inferred reliably. Use `pin: true` and `status: "open"` when those facts matter.

## Measured results

The bundled fixture has a repeated, obsolete console output, a relevant warning, a protected unverified send, user constraints and open work. Its fake transport returns **fixed, predetermined probabilities**. It tests integration and preservation mechanics, not Jev's judgment.

One local run on Windows with Node.js 24.13.1, 50 measured iterations after one warm-up:

| Measurement | Result |
| --- | ---: |
| Source content bytes, before → after | 7,081 → 848 |
| Source content reduction | 88.02% |
| Complete input JSON | 8,044 bytes |
| Complete output JSON packet | Approximately 2,613 bytes; timing metadata can vary a few bytes |
| Complete Markdown handoff | 1,940 bytes |
| Local median / p95 selection time | 0.33 ms / 0.79 ms |
| Removed source ids | `old-read`, `old-result` |
| Retained blocks matching source exactly | All |

These are **offline fixture measurements**, not live Jev latency, semantic quality, cost savings, task success, or Codex token reductions. `contentReduction` excludes packet metadata; short inputs can produce larger full packets. No TypeSafe API key was available for a live evaluation at release preparation.

Reproduce:

```sh
npm run check
npm test
npm run benchmark
npm run smoke:codex
```

The host smoke creates a temporary `CODEX_HOME`, installs the actual marketplace plugin, discovers its skill, starts an ephemeral Codex task, lists the MCP tool, invokes it through Codex's app-server, and uninstalls it. It performs no model turn and no Jev request. Temporary diagnostic evidence is retained at the printed path; your usual Codex configuration and sessions are unchanged. `CODEX_BIN` can select a specific Codex executable.

The release-preparation checks passed **37 automated tests**, **10 JavaScript syntax checks**, JSON and manifest consistency checks, the official local plugin and skill validators, and the Codex 0.153.4 host smoke. The project is plain JavaScript; `check` is a syntax/contract check, not a TypeScript type-check. CI covers Node 22/24 on Windows/Linux; published CI results are shown by the badge above.

After publication, verify the remote release through the same host acceptance path with `npm run smoke:codex -- Wang-auspicious/codex-jev-compaction v0.1.0`.

## Disable, remove, and update

Nothing runs automatically on compaction. Stop invoking the skill or tool to stop selection. Unset `TYPESAFE_API_KEY` before a new Codex process to disable network selection while retaining offline handoffs. Use the Codex plugin settings to disable the plugin, or remove it with:

```sh
codex plugin remove codex-jev-compaction@codex-jev-compaction
# Optional: also remove the marketplace source
codex plugin marketplace remove codex-jev-compaction
```

Your handoff files and original source artifacts remain yours. To update, remove the plugin and marketplace, re-add the desired Git ref, and install again. Start a new task afterward.

## Support and future work

| Capability | Status in 0.1.0 |
| --- | --- |
| Codex marketplace installation, skill discovery, MCP invocation | Implemented; local Windows CLI 0.153.4 acceptance passed |
| JSON selection with provenance and rollback | Implemented; offline protocol and preservation tests passed |
| JSON / Markdown handoff output | Implemented |
| Live Jev endpoint integration | Implemented; live API quality and latency not evaluated |
| Native Codex automatic-compaction replacement | Not implemented; no claim of current support |
| Automatic hidden-history access | Not implemented |
| Very large transcript selection / chunking | Future work; currently returns unchanged |
| Real-task continuation and comparative evaluation | Future work; requires a consented dataset and live key |
| macOS Codex host acceptance | Not yet run |

Read [the design and plan](docs/DESIGN.md), [release changes](CHANGELOG.md), and [verification notes](docs/VERIFICATION.md). To produce a source ZIP from a clean committed checkout, run `npm run pack`.

## Attribution and license

Inspired by **Tamara Tran's [fast-jev-compaction](https://github.com/tamaratran/fast-jev-compaction)**, version 0.2.0 at commit `e3f262a7f4d42bd8dd32ced30d26176f7cb545b0`. Its core idea is to classify evidence instead of generating a new summary. This repository independently implements Codex integration and its own packet, eligibility and failure contracts; it does not rebrand or ship the original Claude Code hook.

MIT © 2026 Wang-auspicious. [Project license](LICENSE) · [Upstream attribution and retained MIT notice](plugins/codex-jev-compaction/NOTICE.md).

An independent community project, not an official OpenAI, TypeSafe, or upstream-author product.