harnesstrim 0.0.1

package/assets/adapter-hermes/plugin/__init__.py

@@ -0,0 +1,242 @@
+"""
+HarnessTrim Hermes plugin — tool-output reduction via transform_tool_result hook.
+
+When enabled, this plugin intercepts the ``transform_tool_result`` hook after every
+tool call and slims noisy output (test runners, git diffs, build logs) to its signal
+before the result enters the model's context.  Dry-run mode logs what *would* be
+reduced; active mode rewrites the result; telemetry (off by default) records every
+reduction as a TrimEvent JSON line.
+
+Run the ``harnesstrim reduce`` command via a subprocess so the reducers live in the
+shared TypeScript/Node core rather than being reimplemented in Python.
+
+Hook contract
+-------------
+``transform_tool_result`` is a built-in Hermes plugin hook:
+- ``hermes_cli/plugins.py`` — listed in ``VALID_HOOKS``
+- ``model_tools.py:1313-1345`` — core loop fires it after every tool call;
+  first callback to return a string replaces the result
+- ``plugins/security-guidance/__init__.py`` — shipped plugin uses it
+- ``tests/test_transform_tool_result_hook.py`` — dedicated test coverage
+
+Callback receives: tool_name, args, result, task_id, session_id, tool_call_id,
+turn_id, api_request_id, duration_ms, status, error_type, error_message.
+Return a string to replace the result, or None to leave unchanged.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+PLUGIN_DIR = Path(__file__).parent
+
+CONFIG_DEFAULTS = {
+    "mode": "dryrun",       # "dryrun" | "active" | "off"
+    "minLength": 400,
+    "telemetry": False,      # explicit opt-in: tool output may contain sensitive data
+    "debug": False,
+}
+
+# Store telemetry in the active Hermes home. HERMES_HOME is profile-aware when set
+# by Hermes; direct CLI usage falls back to the default profile.
+METRICS_PATH = Path(os.environ.get("HERMES_HOME", str(Path.home() / ".hermes"))) / "harnesstrim-metrics.jsonl"
+
+# Tool types whose output we consider for reduction.
+REDUCER_TOOLS = frozenset({
+    "terminal",
+    "read_file",
+    "web_extract",
+    "search_files",
+    "browser_snapshot",
+    "vision_analyze",
+})
+
+
+def register(ctx):
+    """Register the HarnessTrim transform_tool_result hook."""
+    ctx.register_hook("transform_tool_result", on_tool_result)
+
+
+def _load_config():
+    """Return the active plugin config from the environment (no global registry needed)."""
+    cfg = dict(CONFIG_DEFAULTS)
+    for key in CONFIG_DEFAULTS:
+        env_key = f"HARNESSTRIM_{key.upper()}"
+        val = os.environ.get(env_key)
+        if val is not None:
+            if isinstance(CONFIG_DEFAULTS[key], bool):
+                cfg[key] = val.lower() in ("1", "true", "yes")
+            elif isinstance(CONFIG_DEFAULTS[key], int):
+                try:
+                    cfg[key] = int(val)
+                except ValueError:
+                    pass
+            else:
+                cfg[key] = val
+    return cfg
+
+
+def _find_harnesstrim_cli() -> str | None:
+    """Locate the ``harnesstrim`` CLI binary on PATH."""
+    # Try PATH resolution
+    for p in os.environ.get("PATH", "").split(os.pathsep):
+        candidate = Path(p) / "harnesstrim"
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate.resolve())
+    # Check common monorepo dev location via the repo-root sentinel
+    return None
+
+
+def _call_reducer(text: str, min_length: int) -> tuple[str, str | None]:
+    """Shell out to ``harnesstrim reduce`` and return (slimmed_text, reducer_name).
+
+    Falls back to (original_text, None) if the CLI cannot be found or the pipe fails.
+    The reducer name is parsed from the ``--stats`` stderr line (e.g. ``test-output-slim``),
+    used only for telemetry when enabled.
+    """
+    cli = _find_harnesstrim_cli()
+    if cli is None:
+        import warnings
+        warnings.warn(
+            "[harnesstrim] CLI not found on PATH — output not reduced. "
+            "Install CLI with: curl -fsSL https://harnesstrim.dev/install.sh | bash "
+            "or build from source: git clone https://github.com/harnesstrim/harnesstrim",
+            stacklevel=2,
+        )
+        return (text, None)
+
+    if len(text) < min_length:
+        return (text, None)
+
+    try:
+        result = subprocess.run(
+            [cli, "reduce", "--min-length", str(min_length), "--stats"],
+            input=text,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode == 0 and result.stdout:
+            reducer = None
+            # stderr: "[harnesstrim reduce] <reducer>: <before> -> <after> chars"
+            for line in result.stderr.splitlines():
+                line = line.strip()
+                if line.startswith("[harnesstrim reduce]"):
+                    rest = line[len("[harnesstrim reduce] "):]
+                    if ":" in rest and "no reduction" not in rest:
+                        reducer = rest.split(":")[0].strip()
+            return (result.stdout.rstrip("\n"), reducer)
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        pass
+
+    return (text, None)
+
+
+def _text_targets(payload):
+    """Yield mutable payload mappings and text-field names safe to reduce.
+
+    Hermes tools use different result schemas: terminal returns ``output``, file
+    tools ``content``, browser snapshots ``snapshot``, vision ``analysis``, and
+    web_extract has one content field per entry in ``results``.
+    """
+    if not isinstance(payload, dict):
+        return []
+
+    targets = []
+    for key in ("output", "content", "snapshot", "analysis"):
+        if isinstance(payload.get(key), str) and payload[key]:
+            targets.append((payload, key))
+            break
+
+    results = payload.get("results")
+    if isinstance(results, list):
+        for entry in results:
+            if not isinstance(entry, dict):
+                continue
+            for key in ("content", "output", "text"):
+                if isinstance(entry.get(key), str) and entry[key]:
+                    targets.append((entry, key))
+                    break
+    return targets
+
+
+def on_tool_result(tool_name, args, result, **kwargs):
+    """Reduce recognized textual fields while preserving the original JSON schema."""
+    cfg = _load_config()
+    if cfg["mode"] == "off" or tool_name not in REDUCER_TOOLS:
+        return None
+    if not result or not isinstance(result, str):
+        return None
+
+    try:
+        payload = json.loads(result)
+    except (json.JSONDecodeError, ValueError):
+        payload = None
+
+    if isinstance(payload, str):
+        targets = [(None, None, payload)]
+    elif payload is None:
+        targets = [(None, None, result)]
+    else:
+        targets = [(container, key, container[key]) for container, key in _text_targets(payload)]
+
+    if not targets:
+        return None
+
+    changed = False
+    for container, key, text in targets:
+        before_len = len(text)
+        if before_len < cfg["minLength"]:
+            continue
+        if "[harnesstrim:" in text or "[hermes-trim" in text:
+            continue
+
+        after, reducer = _call_reducer(text, cfg["minLength"])
+        if after == text:
+            continue
+
+        changed = True
+        if cfg["mode"] == "dryrun":
+            print(
+                f"[harnesstrim] dryrun: {tool_name} "
+                f"{before_len} -> {len(after)} chars (would save {before_len - len(after)})",
+                file=sys.stderr,
+            )
+            continue
+
+        if container is None:
+            payload = after
+        else:
+            container[key] = after
+        if cfg["telemetry"]:
+            _write_metric(tool_name, reducer, before_len, len(after))
+
+    if not changed or cfg["mode"] == "dryrun":
+        return None
+    return json.dumps(payload, ensure_ascii=False) if not isinstance(payload, str) else payload
+
+
+def _write_metric(tool: str, reducer: str | None, before: int, after: int) -> None:
+    """Append one TrimEvent JSONL line to METRICS_PATH (read by `harnesstrim metrics`).
+
+    Only called in active mode when telemetry is explicitly enabled. Creates the parent
+    directory lazily and swallows any error — telemetry must never crash the plugin.
+    """
+    import datetime as _dt
+
+    event = {
+        "ts": _dt.datetime.now(_dt.timezone.utc).isoformat(),
+        "harness": "hermes",
+        "tool": tool,
+        "reducer": reducer,
+        "beforeChars": before,
+        "afterChars": after,
+    }
+    try:
+        METRICS_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with open(METRICS_PATH, "a", encoding="utf-8") as f:
+            f.write(json.dumps(event, ensure_ascii=False) + "\n")
+    except OSError:
+        pass  # telemetry must never crash the plugin

package/assets/adapter-hermes/plugin/plugin.yaml

@@ -0,0 +1,6 @@
+name: harnesstrim
+version: "0.0.1"
+description: >
+  HarnessTrim reducer plugin — slims noisy tool output (test logs, git diffs, build output)
+  before it reaches the model, via the transform_tool_result hook.
+requires_env: []

package/assets/adapter-pi/extension/harnesstrim.ts

@@ -0,0 +1,62 @@
+// HarnessTrim Pi extension — slims noisy tool output via the `tool_result` hook.
+//
+// Pi fires `tool_result` after a tool finishes and before the result reaches the model;
+// handlers chain like middleware and may return a patch ({ content, details, isError }).
+// This extension reduces string `content` for noisy output (test runners, git diffs, ...)
+// by shelling out to `harnesstrim reduce`, so it is self-contained (no workspace imports)
+// and loads from `~/.pi/agent/extensions/` or `<project>/.pi/extensions/`.
+//
+// Requires `harnesstrim` on PATH; if it is missing or fails, the output is passed through
+// unchanged (a reducer must never break a tool result). Config via env:
+//   HARNESSTRIM_MODE=dryrun|active|off   (default dryrun — logs, does not mutate)
+//   HARNESSTRIM_MINLENGTH=<chars>        (default 400)
+import { spawnSync } from "node:child_process";
+
+interface ToolResultEvent {
+  content?: unknown;
+  isError?: boolean;
+}
+interface ExtensionAPI {
+  on(event: string, handler: (event: ToolResultEvent, ctx: unknown) => unknown): void;
+}
+
+const env = globalThis.process?.env ?? {};
+const MODE = env.HARNESSTRIM_MODE ?? "dryrun";
+const MIN_LENGTH = Number(env.HARNESSTRIM_MINLENGTH ?? "400") || 400;
+const MARKER = "[harnesstrim";
+
+function reduceViaCli(text: string): string | null {
+  try {
+    const r = spawnSync("harnesstrim", ["reduce", "--min-length", String(MIN_LENGTH)], {
+      input: text,
+      encoding: "utf8",
+      timeout: 30000,
+    });
+    if (r.status === 0 && typeof r.stdout === "string" && r.stdout.length > 0) {
+      return r.stdout.replace(/\n$/, "");
+    }
+  } catch {
+    /* harnesstrim not on PATH or failed — pass through */
+  }
+  return null;
+}
+
+export default function harnesstrim(pi: ExtensionAPI): void {
+  if (MODE === "off") return;
+  pi.on("tool_result", async (event) => {
+    const content = event.content;
+    if (typeof content !== "string" || content.length < MIN_LENGTH) return;
+    if (content.includes(MARKER)) return; // already reduced — avoid double work
+
+    const reduced = reduceViaCli(content);
+    if (!reduced || reduced.length >= content.length) return;
+
+    if (MODE === "dryrun") {
+      globalThis.process?.stderr?.write(
+        `[harnesstrim] dryrun tool_result: ${content.length} -> ${reduced.length} chars\n`
+      );
+      return; // dryrun: observe only
+    }
+    return { content: reduced }; // active: patch the tool result the model sees
+  });
+}

package/assets/skills/compact-handoff/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: compact-handoff
+description: This skill should be used when a session is being compacted/summarized (context is full or the user runs a compact command), or when writing any handoff summary that a later session or subagent will continue from. Defines what to preserve versus drop so the continuation doesn't waste tokens re-reading files and re-deriving state. Part of the HarnessTrim token-economy stack; the OpenCode adapter injects this guidance automatically via experimental.session.compacting.
+version: 0.1.0
+license: MIT
+---
+
+# compact-handoff
+
+A compaction summary is the seed context for everything that follows. If it drops the wrong
+things, the next turns re-read files, re-run searches, and re-decide settled questions — spending
+far more tokens than the summary ever saved. Optimize the summary for *resumption*, not brevity.
+
+## Preserve
+
+1. **The task and its acceptance criteria** — what "done" means, verbatim if the user stated it.
+2. **Decisions made and alternatives rejected** — with the reason, so they aren't re-litigated.
+3. **Hard-won specifics** — exact file paths, symbol names, commands that worked, config values,
+   version numbers, API signatures discovered. These are the expensive-to-rediscover facts.
+4. **Current state** — what is done, what is verified (and how), what is still failing and the
+   last error seen.
+
+## Drop
+
+- Step-by-step narration of what was already done ("first I opened X, then I ran Y").
+- Raw tool output that has already been acted on (test logs, file dumps, search results).
+- Anything trivially reconstructable from the current diff or a single cheap command.
+- Restatements of the codebase's structure that the next session can read directly.
+
+## Shape
+
+Write the summary as short labeled sections (Task / Decisions / Key facts / State), not prose.
+A resuming agent should be able to act from it without re-reading the whole transcript.

package/assets/skills/debug-log-slim/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: debug-log-slim
+description: This skill should be used before pasting, printing, or otherwise embedding test-runner output, build logs, or CI output into the conversation — whenever a test suite, linter, or build was just run and its raw output is large. Filters logs down to failure/error signal before they enter context. Part of the HarnessTrim token-economy stack (see packages/core/src/reducers/test-output-slim.ts for the reference implementation the OpenCode adapter automates this with).
+version: 0.1.0
+license: MIT
+---
+
+# debug-log-slim
+
+Raw test/build output is mostly noise: hundreds of PASS/OK lines for every one line that
+actually matters. Don't paste it all into context — filter first.
+
+## Rule
+
+Before showing test/build/lint output to the user or reasoning over it at length, reduce it to:
+
+1. **Every FAIL / ERROR / Exception / Traceback / assertion line.**
+2. **A few lines of context around each** (the stack frame or expected/received diff — usually
+   3–5 lines is enough to act on).
+3. **The final summary line** (e.g. `12 passed, 3 failed`), always kept verbatim.
+4. **Everything else collapsed** into a single count, e.g. `… 40 passing lines omitted …` — never
+   silently dropped without saying how much was cut.
+
+## How to apply it
+
+- If the HarnessTrim OpenCode adapter is installed, this happens automatically via
+  `tool.execute.before` — no manual filtering needed, this skill is then just a fallback for
+  contexts where the adapter isn't wired in.
+- Without the adapter: when a command produces long output, pipe it through a targeted filter
+  before reading it in full — e.g. `grep -E 'FAIL|ERROR|Exception' -A 5` (adjust the pattern to
+  the test runner's failure markers) — rather than reading the entire raw log.
+- Never summarize-then-discard: if you filtered, the user should still be able to ask "show me
+  the full log" and get it — filtering is about what enters *reasoning context* by default, not
+  deleting the underlying artifact.
+
+## What NOT to filter out
+
+- Warnings that indicate a real (if non-fatal) problem — e.g. deprecation notices tied to the
+  change just made.
+- Anything the user explicitly asked to see in full.

package/assets/skills/delegate-bulk/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: delegate-bulk
+description: This skill should be used when deciding whether to hand volumetric or noisy work to an isolated subagent (or another harness) instead of doing it in the main context — e.g. reading many files, digesting long logs/docs, wide searches, or bulk mechanical generation. It gives the rule for when isolation saves tokens versus when it just multiplies them. Part of the HarnessTrim token-economy stack.
+version: 0.1.0
+license: MIT
+---
+
+# delegate-bulk
+
+Subagents are not free parallelism — each carries its own context and bills its own tokens. The
+right move is surgical isolation of *noise*, not "multi-agent everything."
+
+## Delegate to an isolated subagent when
+
+- A task will **read a large volume the main thread doesn't need to retain** — many files, long
+  logs, big docs, wide search results — and you only need the *conclusion* back, not the raw bytes.
+- The work is **noisy but self-contained**: exploring a subsystem, triaging a failing test suite,
+  digesting API docs. Isolate it so its raw output never pollutes the main context.
+- You need **several independent investigations at once** and each one's detail is irrelevant to the
+  others.
+
+The token win comes from the subagent returning a short structured answer while its expensive
+reading stays in a context you throw away.
+
+## Do NOT delegate when
+
+- The task is small enough that spawning a context costs more than it saves.
+- The main thread needs the **full detail** anyway (delegating then re-reading is pure overhead).
+- You'd spawn many agents that each re-load the same large context — that multiplies tokens, the
+  opposite of the goal.
+
+## Cross-harness delegation
+
+The same logic extends across harnesses: route bulk scaffolding/boilerplate to a cheaper or
+execution-oriented channel and keep architecture, review, and validation on the main one. Suppress
+the delegated channel's verbose thinking/output from re-entering the main context. Pair with
+[[scaffold-fast]] for the delegated bulk work and [[compact-handoff]] for what the subagent returns.
+
+## Rule of thumb
+
+Delegate to **shrink** what the main context must hold, never to **duplicate** it.

package/assets/skills/delta-response/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: delta-response
+description: This skill should be used for every response produced in a coding harness (Claude Code, Codex, OpenCode, Pi) — not only when explicitly requested. Enforces terse, structured, information-dense output instead of narrated verbosity, to cut output-token cost. Part of the HarnessTrim token-economy stack (see delta-response/references/examples.md for before/after samples).
+version: 0.1.0
+license: MIT
+---
+
+# delta-response
+
+Say the delta, not the story. Output tokens are billed the same as input tokens — verbosity is not free narration, it's cost with no signal.
+
+## Rules
+
+1. **Lead with the result.** State the answer, the change, or the finding first. Don't restate the request or narrate intent ("I will now check...", "Let me look at...") before acting — just act, then report what you found.
+2. **No filler.** Cut greetings, hedges, and meta-commentary ("Great question!", "As you can see,", "I hope this helps"). Every sentence must carry information the reader doesn't already have.
+3. **Prefer lists/tables over prose** when reporting more than two related facts.
+4. **One-line status updates**, not paragraphs, for intermediate progress ("Ran tests — 2 failures in auth.spec.ts", not three sentences describing the act of running tests).
+5. **End-of-task summary: 1–2 sentences max** — what changed, what's next. No recap of steps already visible in the transcript/diff.
+6. **Don't over-explain obvious code.** Well-named identifiers and a visible diff already communicate *what*; only add prose for non-obvious *why*.
+7. **Match length to the question.** A yes/no question gets a direct answer, not headers and sections.
+
+## When NOT to compress
+
+Don't cut content that changes a decision: trade-offs the user must choose between, a warning about a risky/irreversible action, or a caveat that changes whether the result can be trusted. Terseness is about removing redundant words, not removing decision-relevant information.
+
+See `references/examples.md` for verbose-vs-terse rewrites.

package/assets/skills/delta-response/references/examples.md

@@ -0,0 +1,33 @@
+# delta-response — before/after examples
+
+**Task: "run the tests"**
+
+Verbose (avoid):
+> I'll go ahead and run the test suite now to check if everything is passing correctly.
+> [runs tests]
+> Great, I've run the tests for you! Here's what I found: the test suite completed and it
+> looks like there were a couple of failures. Let me break those down for you in detail...
+
+Terse (target):
+> Ran tests — 2 failures: `auth.spec.ts:42` (timeout), `billing.spec.ts:110` (assertion mismatch).
+
+**Task: "what does this function do?"**
+
+Verbose (avoid):
+> So looking at this function, what we can see here is that it takes an input parameter
+> called `items`, and then what it does is it iterates over each item in the array using
+> a for loop, and for each one it checks a condition...
+
+Terse (target):
+> Filters `items` to those with `active: true`, then sorts by `createdAt` descending.
+
+**Task: "fix the bug and tell me what you did"**
+
+Verbose (avoid):
+> I identified the root cause of the issue. The problem was in the validation logic.
+> I've now updated the code to fix this. Here's a summary of the changes I made: first,
+> I changed the regex pattern, then I added a null check, and finally I updated the tests
+> to reflect these changes. Let me know if you have any questions!
+
+Terse (target):
+> Fixed: regex in `validate.ts:18` didn't allow `+` in emails; added a null guard for empty input. Tests updated.

package/assets/skills/review-delta/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: review-delta
+description: This skill should be used when asked to review code, review a pull request, or review a diff. Focuses the review on problems worth fixing rather than restating or summarizing what changed. Part of the HarnessTrim token-economy stack.
+version: 0.1.0
+license: MIT
+---
+
+# review-delta
+
+A code review that restates the diff wastes tokens telling the reader something the diff already
+shows. Review for *problems*, not for *content*.
+
+## Rules
+
+1. **Don't summarize what changed file-by-file.** The diff is already visible; narrating
+   "this file now does X, that file now does Y" adds no information.
+2. **Only report actual findings**: correctness bugs, security issues, missed edge cases,
+   inconsistent-with-the-rest-of-the-codebase patterns, risky assumptions. If a file has nothing
+   wrong, say nothing about it — don't write "looks good" for every clean file.
+3. **Rank findings by severity**, most important first.
+4. **Cite `file:line`** for every finding so it's actionable, not abstract.
+5. **One or two sentences per finding**: what's wrong and the concrete failure scenario
+   (input/state that breaks), plus a fix suggestion only if it's non-obvious.
+6. **If there are zero findings, say so in one line.** Don't pad a clean review to look thorough.
+
+## Failure scenario, not just a label
+
+"This could be a null pointer issue" is not a finding. "`user` can be `undefined` when
+`fetchUser` 404s (see `api.ts:12`), and `line 40` dereferences it without a check — crashes on
+any unknown user id" is a finding: concrete state, concrete break.

package/assets/skills/scaffold-fast/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: scaffold-fast
+description: This skill should be used for mechanical, low-novelty coding work — generating boilerplate, wiring up a component from an existing pattern, adding a CRUD endpoint like the others, writing repetitive tests, or applying a rote transformation across files. It keeps reasoning effort low and output terse for work whose shape is already decided. Part of the HarnessTrim token-economy stack; the lean-scaffold preset pairs it with low reasoning effort.
+version: 0.1.0
+license: MIT
+---
+
+# scaffold-fast
+
+When the *shape* of the work is already decided and the task is to produce more of it, spend tokens
+on the code, not on deliberation. Deep reasoning on rote work is wasted budget.
+
+## When this applies
+
+- Boilerplate: config files, DTOs, barrel exports, index files.
+- "Same as the others" work: a new endpoint/component/model that mirrors existing ones.
+- Repetitive tests following an established pattern.
+- Mechanical transforms: rename a symbol across files, migrate a call signature, reformat.
+
+## Rules
+
+1. **Copy the existing pattern, don't reinvent it.** Find the nearest sibling (the last component,
+   the adjacent endpoint) and match its structure, naming, imports, and error handling exactly.
+2. **Minimal reasoning.** Don't weigh architectural alternatives for work whose design is settled —
+   if you find yourself deliberating, that's a signal the task is *not* scaffolding and this skill
+   doesn't apply.
+3. **Terse output.** State what was generated in one line; the diff shows the rest. No walkthrough.
+4. **Don't gold-plate.** No speculative abstraction, options, or config for needs nobody stated.
+5. **Batch mechanical edits** rather than narrating each one.
+
+## When to STOP and escalate
+
+If the "boilerplate" turns out to require a real decision — an unclear data model, a security
+boundary, an ambiguous requirement — stop scaffolding and surface the decision. Fast is for settled
+work, not for guessing past ambiguity. See [[delegate-bulk]] when the volume itself is the problem.