Fast Jev Compaction for Agent Hosts

This repository adapts fast-jev-compaction as a portable Agent plugin. It exposes the same MCP server to Agent hosts and keeps a .codex-plugin/ compatibility manifest for Codex.

It exposes an on-demand MCP tool, compact_transcript, that uses TypeSafe Jev to decide which tool calls and tool results can be removed or truncated while keeping retained transcript content verbatim. It does not replace a host's internal automatic compaction.

Install as an Agent plugin

npm install
npm run typecheck
npm test
npm run build

The portable entrypoint is plugin.json with mcp.json and skills/. Codex can also load .codex-plugin/plugin.json with .mcp.json. The two MCP files are intentionally identical so either loader gets the same server configuration.

Set TYPESAFE_API_KEY before using the MCP tool. The supplied transcript's compaction state is sent to https://api.typesafe.ai/v1/systemone by default. Set TYPESAFE_BASE_URL to use a compatible endpoint. Do not send secrets or private transcripts without checking the data boundary.

Related MCP server: mcp-token-optimizer

Agent-neutral transcript contract

compact_transcript accepts a messages array. The canonical shape is:

{
  "role": "assistant",
  "text": "",
  "toolUses": [{"tool_use_id": "call-1", "tool": "Read", "input": {"path": "README.md"}}],
  "toolResults": []
}

The MCP adapter also accepts common content, tool_calls, toolCalls, tool_results, and tool_call_id aliases from Agent hosts. Tool-role messages are normalized to the internal result representation; no tool from the supplied transcript is executed.

Options accepted by compact_transcript include:

• messages: transcript messages with role, text, toolUses, and optional toolResults;

• options: optional thresholds and token budgets from the original library;

• model: optional per-call model override; the MCP server reads TYPESAFE_API_KEY from its environment.

The result contains the compacted messages, per-call decisions, and stats.

Development

npm run typecheck
npm test
npm run build
npm run validate:plugin

The original MIT license and core compaction implementation are retained. Claude Code-specific hooks are intentionally not part of this portable Agent plugin.