The package root exports pure, deterministic classification, policy, adapter, optimizer, watermark, literal, expand, tool-result, and compressor APIs. The OpenCode host integration lives behind the ./plugin subpath so importing the core does not load the host runtime.
import { classifyText, selectLlmlinguaCandidates } from "opencode-context-optimisations"
import plugin from "opencode-context-optimisations/plugin"Heuristically determines whether a text span is safe for token-dropping compression. The classifier is deliberately conservative: ambiguity returns "unknown", which is never compressible.
text:string— The text to classify.
Classification:kind:"empty" | "json" | "diff" | "code" | "log" | "prose" | "unknown"confidence:number— Between0.0and1.0reasons:string[]— Diagnostic descriptions of the matched heuristics
import { classifyText } from "opencode-context-optimisations"
const sample = `import { readFile } from "node:fs/promises"
import path from "node:path"
export async function loadConfig(dir: string): Promise<Config> {
const file = path.join(dir, "config.json")
const raw = await readFile(file, "utf8")
return JSON.parse(raw)
}`
console.log(classifyText(sample))
// { kind: "code", confidence: 0.8, reasons: ["6 declaration lines", "3 indented lines"] }Returns true only for kind === "prose" with confidence >= 0.7. Code, diffs, JSON, logs, empty text, and unknown content always return false.
Fast, zero-dependency estimate for budgets and stats. It is not a provider tokenizer: Latin text uses chars / 4, CJK code points use count / 1.5, and the result is rounded up.
Pure, deterministic selection. It does not call a model and does not mutate the transcript.
- Every message at or after the protected boundary is rejected as
"recent". - System messages are rejected as
"system". - Old user prose is rejected as
"role"unlessallowUserProseis true. - Old tool messages are rejected as
"role"whenincludeToolProseis false. - Text parts marked
protected: trueare rejected as"content"with detail"protected". - Non-prose content is rejected as
"content"with the classification kind as detail. - Spans below
minTokensare rejected as"small". - Eligible spans are sorted oldest-first and admitted until
budgetTokensis exhausted; oversized candidates are skipped and later candidates may fit.
| Option | Default | Meaning |
|---|---|---|
protectedTurns |
2 |
Number of recent user turns kept verbatim. Minimum 1; 1 is an explicit advanced override. |
minTokens |
400 |
Minimum estimated tokens for a candidate. |
budgetTokens |
2000 |
Maximum total estimated tokens selected. |
allowUserProse |
false |
Permit stale user prose. |
includeToolProse |
true |
Permit stale tool prose. |
modelId |
"llmlingua-2" |
Included in the cache key. |
rate |
0.6 |
Included in the cache key. |
Non-finite numeric options (NaN, Infinity) fall back to their defaults. This is a safety behavior: NaN would otherwise make every comparison false and disable a gate. A rate outside (0, 1] also falls back to 0.6.
candidates:Candidate[]— Oldest-first eligible spans.rejected:RejectedPart[]— Reason and optional detail for every rejected span.protectedFromIndex:number— First index of the protected tail.selectedTokens:number— Sum of candidate token estimates.
Candidate fields: messageIndex, partIndex (null for legacy string content), role, text, tokens, ageTurns, classification, cacheKey.
import { selectLlmlinguaCandidates } from "opencode-context-optimisations"
const { candidates, rejected, selectedTokens } = selectLlmlinguaCandidates(messages, {
protectedTurns: 2,
minTokens: 400,
budgetTokens: 2000,
})OpenCode V2 messages use content: ContentPart[], and tool output is a tagged value rather than a plain text part. The adapter flattens every eligible textual span and remembers exactly where it came from.
export interface V2Message {
role: string
content?: string | readonly V2ContentPart[]
id?: string
}
export interface V2ContentPart {
type: string
text?: string | null
id?: string
name?: string
namespace?: string
result?: { type: string; value?: unknown }
}| Source | Policy treatment | Write-back target |
|---|---|---|
{ type: "text", text } |
Classified normally | part.text |
tool-result.result.type === "text" |
Classified normally | result.value |
tool-result.result.type === "json" |
protected: true (never compressed) |
unchanged |
tool-result.result.type === "error" |
protected: true (never compressed) |
unchanged |
tool-result.result.type === "content" text entries |
Classified normally | result.value[i].text |
tool-call, reasoning, media, compaction, effort |
Ignored | untouched |
Returns:
messages: one syntheticPolicyMessageper input message (indexes are preserved),spans:V2TextSpan[]with the original source pointer andprotectedflag,byPolicyPart:Map<string, V2TextSpan>keyed bypolicySpanKey(messageIndex, policyPartIndex).
Applies compressed strings to the exact source spans and returns how many replacements succeeded. It preserves message IDs, tool IDs/names, file attachments, JSON/error results, and all non-text parts.
Returns the "messageIndex:policyPartIndex" key used by the adapter map.
The lane orchestration:
- Adapt the V2 transcript.
- Select candidates with the policy.
- Serve cache hits; batch misses through an injected backend.
- Enforce a per-candidate timeout.
- Reject output that drops protected literals.
- Optionally annotate the result with a retrieval marker.
- Enforce the expansion guard.
- Apply successful replacements in place.
Backend errors, empty output, timeouts, and literal failures leave the original span untouched. The function never throws because of a backend failure.
| Option | Default | Meaning |
|---|---|---|
enabled |
true |
Set false to skip all work. |
timeoutMs |
1200 |
Per-candidate deadline. |
cacheMaxEntries |
500 |
LRU capacity when no cache is supplied. |
maxCompressedRatio |
0.9 |
Skip results at least this fraction of the input size. |
validateLiterals |
true |
Require paths, URLs, numbers, line references, and error codes to survive. |
literalOptions |
defaults | Tune the literal classes and maximum count. |
interface OptimizerDeps {
backend: CompressionBackend
cache?: TextCache
inflight?: Map<string, Promise<string>>
onCompressed?: (event: {
original: string
compressed: string
span: V2TextSpan
}) => string
now?: () => number
}
interface CompressionBackend {
compress(request: CompressionRequest): Promise<string>
}onCompressed is used by the plugin to append [ctx_expand:...] markers while keeping the raw compressed text in the cache.
enabled, candidates, compressed, applied, cacheHits, failures, skipped, literalRejects, rejected, selectedTokens, savedTokens, latencyMs, protectedFromIndex.
Insertion-ordered LRU. A capacity of zero disables storage. Cache keys come from the policy and include policy version, model ID, rate, and original text.
Estimates the outgoing payload from system parts, tool schemas, message text, tool-call inputs, and tool-result content. It is a cheap approximation, not a provider token count.
interface WatermarkOptions {
highRatio?: number // default 0.7
outputReserveTokens?: number // default 15% of limit, clamped to 1-16k
}
interface WatermarkDecision {
usedTokens: number
contextLimit: number
reserveTokens: number
usableTokens: number
ratio: number
threshold: number
shouldCompress: boolean
}Returns undefined for an unusable model limit. The plugin then falls back to running compression without a watermark.
Extracts deduplicated file paths, URLs, error codes, line references, and numbers. Options can disable any class and cap the result count.
Returns the extracted literals that are absent from the compressed text. An empty array means the output passed the post-check. This is intentionally strict: a path that gains spaces around punctuation is considered lost.
Bounded LRU of original spans with deterministic ctx_<sha256-prefix> handles. Options: maxEntries (200), maxChars (1,000,000), maxQueryLines (40), maxReturnChars (20,000).
Returns an optimizer onCompressed callback that stores the original and appends:
[ctx_expand:ctx_ab12cd34ef56]
The marker is deterministic for identical original text.
Chooses the longest textual payload from result.content (string or text entries) or a string result.output. The returned apply() replaces only that slot and preserves file attachments, metadata, and tool identity.
Exact-name or trailing-* prefix matching. The plugin's default protected list includes write, edit, patch, task, todowrite, question, context_expand, and plan_*.
const backend = createHttpCompressor({
endpoint: "http://127.0.0.1:8765/compress",
timeoutMs: 1200,
})The request body is:
{
"text": "...",
"rate": 0.6,
"model": "llmlingua-2",
"kind": "text",
"tool": "read"
}kind is "text" or "tool-result"; tool is present only for tool results. The response must be JSON with a non-empty text field (compressed is accepted as an alias). Non-2xx responses, timeouts, and malformed bodies reject; the optimizer catches those and fails open.
The default export is a Plugin.define({ id: "opencode-llmlingua", setup }) definition. setup reads ctx.options and registers:
ctx.session.hook("context")— watermark-gated request compression.ctx.session.hook("compaction")— precompress the summarizer transcript; never setsevent.result.ctx.tool.hook("execute.after")— only whentoolOutputEnabledis true.ctx.tool.transform(...)— addscontext_expandwhenexpandToolEnabledis true.
The plugin registers nothing when enabled is false or neither endpoint nor an injected backend is available.
Builds a plugin definition with injected dependencies:
interface PluginRuntime {
backend?: CompressionBackend
cache?: TextCache
inflight?: Map<string, Promise<string>>
expandStore?: ExpandStore
logger?: (message: string) => void
}Maps ctx.options into a ContextPluginConfig. Unknown keys are ignored. A blank endpoint is treated as absent and is trimmed.
| Option | Default | Meaning |
|---|---|---|
enabled |
true |
Master switch. |
endpoint |
undefined |
Full sidecar URL. Without it the plugin is inert. |
debug |
false |
Log one-line stats, watermark decisions, and failure details. |
protectedTurns |
2 |
Request-lane recency window. |
minTokens |
400 |
Request-lane minimum chunk. |
budgetTokens |
2000 |
Request-lane budget. |
allowUserProse |
false |
Permit stale user prose. |
includeToolProse |
true |
Permit tool-role prose. |
modelId |
"llmlingua-2" |
Cache-key/backend model identifier. |
rate |
0.6 |
Default compression rate. |
timeoutMs |
1200 |
Request-lane deadline. |
cacheMaxEntries |
500 |
LRU capacity. |
maxCompressedRatio |
0.9 |
Expansion guard. |
validateLiterals |
true |
Literal post-check. |
watermarkEnabled |
true |
Gate the request lane. |
watermarkRatio |
0.7 |
Pressure threshold. |
outputReserveTokens |
15% clamp | Response reserve. |
compactionEnabled |
true |
Precompress compaction input. |
compactionProtectedTurns |
inherits | Compaction recency window. |
compactionMinTokens |
inherits | Compaction minimum chunk. |
compactionBudgetTokens |
8000 |
Compaction budget. |
compactionRate |
0.7 |
Compaction rate. |
compactionTimeoutMs |
12000 |
Compaction deadline. |
toolOutputEnabled |
false |
Incremental tool-output lane. |
toolMinTokens |
300 |
Tool-output minimum. |
toolBudgetTokens |
2000 |
Tool-output budget. |
toolRate |
0.6 |
Tool-output rate. |
toolTimeoutMs |
1200 |
Tool-output deadline. |
protectedTools |
built-in list | Exact names or prefix*. |
expandToolEnabled |
true |
Store originals, append markers, register the tool. |
expandStoreMaxEntries |
200 |
Original-store capacity. |
expandStoreMaxChars |
1,000,000 |
Original-store character budget. |
Input: { handle: string, query?: string }. It returns the original span, or lines matching query with L<n>: prefixes. Unknown handles return a plain text message. The tool is local-only and never touches the network.
event.system, event.tools, event.options, tool-call inputs, reasoning parts, media, compaction checkpoints, JSON tool results, error tool results, tool-call/result IDs, and the protected recent window.
- The tool-output lane is default-off. V2 docs show result replacement, but persistence across history is unverified; test your OpenCode build before enabling it.
- Compaction is precompress-only. The plugin never sets
event.resultor replaces the summarizer. - The watermark uses a heuristic token estimate, not provider usage. If
ctx.model.list()cannot supply a limit, the plugin falls back to running compression without a gate. - Literal validation is a post-check, not force-token protection. Technical prose with many numbers/paths will often be rejected rather than compressed.
- The root package does not bundle an LLMLingua model or Python runtime; the worker is optional and external.
- Token estimates are heuristic, not provider token counts.
- The worker binds to loopback and has no authentication.
- The plugin assumes the outgoing V2
contextandcompactionmessages are mutable at the nestedcontent[].textandtool-result.result.valuelevel. The research note flags this as an open runtime question; if a build freezes those objects, switch the adapter to immutable message replacement. context_expandis in-memory and bounded; markers add a small token cost. On restart, old handles are gone.- The quality harness is a fact-retention smoke test, not a SWE-bench-style task-success evaluation.