@jev-harness/omp — Jev tools + auto-hooks for Oh My Pi

OMP-native adapter over @jev-harness/core (TypeSafe's Jev / System One). Registers ONE advisory tool (jev, three modes) and 4 opt-in automatic hooks (5 handler registrations: the skill router uses input to observe the prompt and before_agent_start to deliver its hint; tool_result pruning is opt-in separately — it does NOT join OMP_JEV_AUTO).

Install

# from the harness repo
npm run build --workspace @jev-harness/omp
omp plugin install ./packages/omp

Or copy the built entry into your agent dir so OMP loads it as an extension:

cp packages/omp/bundle/extension.js ~/.omp/agent/extensions/jev-tools.js

The package.json omp.extensions field points at ./bundle/extension.js.

Tools (always registered)

The jev tool also serves mode: "savings", which reports what the gate SKIPPED versus what it JUDGED for this session, straight from the decision log and spending no request. It separates MEASURED figures (latency of calls that ran, blocks) from ESTIMATED ones (dollars and milliseconds avoided, priced at the measured mean), because mixing the two is how a savings dashboard becomes fiction.

loadMode: "discoverable" is deliberate: OMP mounts a discoverable tool under xd:// or BM25 search instead of the top-level schema, so the large three-mode schema stays off every request. Nothing here duplicates OMP's own tooling — the previous jev_ask re-implemented the native judge() / judge_batch() prelude available inside eval, and jev_models duplicated omp models typesafe, so both were removed.

Hooks (all opt-in)

Read-only pre-filter: before any request is spent, a strictly closed-form allowlist (gate-prefilter.ts) recognises bash commands that are provably non-mutating — plain reads (ls, cat, grep, head), listing subcommands (git log, gh api, npm ls), and only the read-shaped arguments of multi-purpose commands (certutil -hashfile, sort without -o). A match skips the request; the skip means "do not judge", never "approve" — it returns the same allowance as a tool it does not adjudicate, so OMP's normal flow is unchanged. The allowlist is an allowlist by construction: anything unrecognised, ambiguous, or even arguably mutating still reaches Jev, because the residue is the semantic work. It was measured at 28% of real bash calls absorbed with zero false positives, and each skip is logged with its rule id (action: "skip:<rule>") so the list's own decisions are auditable.

tool_result pruning (default off — OMP_JEV_PRUNE=1 to enable)

This hook is deliberately OUTSIDE OMP_JEV_AUTO: enabling the master switch does not arm it, and disabling pruning never touches the other hooks.

• Why default-off — prompt-cache invalidation. Every replacement rewrites that tool result from the point it appears, invalidating the provider's prompt-cache prefix from there on. Each scored result then costs +200-400 ms to re-cache on every later turn that re-sends it — and the hook spends one Jev call per bulky result even when the verdict is "keep". Opt in only if bulky outputs are a real, recurring cost in your sessions.
• Latency. Disabled: zero work, zero calls. Enabled, per qualifying result: no call under 2000 chars; one Jev noul call for a bulky result, bounded by an 8 s self-deadline combined with the host's abort signal — far below the host's 30 s tool_result handler budget, so a slow Jev call can never stall the turn.
• Hard-cap fallback. Text over 200_000 chars is capped LOCALLY (head + tail plus a [locally capped …] note) and never sent to Jev — an oversize state makes Jev answer HTTP 400, and no request is worth a guaranteed 400. A capped result carries the same idempotency marker, so it is never pruned or capped twice.
• Recovery. The host retains the ORIGINAL content in all cases: the hook only ever returns a replacement string (verbatim head + a note naming the omitted size). Every note names the result it came from: id=<toolCallId> (for core drops, id= is the candidate id passed to pruneContext, i.e. the same toolCallId), so the original is recoverable from the session transcript or tool log by that id.
• Errors. A failed tool (isError: true) is judged under the stricter error drop bar — live error output is dropped only when Jev reads it as fully spent. Any throw — transport, timeout, missing key — returns undefined and records prune:output / prune:error in the refusal ledger (packages/omp/src/prune.test.ts pins this).

Environment variables

Resilience

• Budget guard. OMP_JEV_MAX_CALLS_PER_MIN caps runaway loops; the cap is shared by every tool and hook.
• Persistent cache. Identical judgments are free hits across sessions (OMP_JEV_CACHE_DIR, OMP_JEV_CACHE_TTL_MS).
• Failure taxonomy. A transport failure is classified (classifyJevFailure) and handled by policy (policyForFailure) rather than swallowed: an auth or model failure disables Jev for the session — every later call would fail identically while burning a host handler's latency budget — rate_limit backs off, network stays quiet, and anything else is surfaced in the logs.
• Degraded routing. When the Jev routing call fails — not when it abstains — the hook reroutes locally with core's localRouteSkill and promotes a match only at overlap ≥ 0.2 (LOCAL_ROUTE_MIN_SCORE, on that router's own hits / sqrt(|message| × |name+description|) scale). The floor is deliberately stricter than core's 0.05 plausibility floor: one incidental shared word scores ~0.08 and would send the model after the wrong skill, while two content words over short descriptions score ~0.29 and are kept. Below the floor, no hint is produced at all — a wrong hint costs more than none.
• Refusal ledger. Gate blocks, routing abstains, compaction deferrals, prune failures (prune:output / prune:error), and local fallbacks (match or no-match) are recorded with their reason, so a declined action leaves a trace instead of vanishing.
• Fail-open. Apart from an explicit destructive block, no Jev failure ever stops the agent.

Layout

• src/extension.ts — default-export factory (pi: ExtensionAPI) => void; all tools + hooks.
• src/prune.ts — tool_result pruning hook body: env gate, idempotency, local hard cap, pruneContext call, fail-open catch (src/prune.test.ts).
• src/compact.ts — pure verbatim-compaction planning + rendering (no host, no network).
• src/router.ts — pure skill-roster loading, the single-flight, cached ranked-merge router, and the conservative local router used on the degraded path.
• src/failure.ts — the one place a Jev transport failure becomes a decision.
• src/config.ts — env parsing, thresholds re-exported from core, deadline helper.
• src/index.ts — re-exports the factory.