sieve

English | 简体中文

sieve / dsh-sieve

LLM agent context engineering and token efficiency plugins for DeepSeek Harness (DSH)

sieve filters tool output, prunes older context and progressively discloses skills to reduce redundant input tokens in AI coding agents, improve context window utilization and provide observable usage data for LLM inference cost optimization. Originals are archived before rewriting and can be retrieved on demand.

Over 30% less request payload in offline replay, measured in characters: a 36.28% aggregate reduction across 100 public agent trajectories. See offline replay results.

Historical live model results: 21.2% lower main model input token usage across 80 paired runs on deepseek-flash, with cache hit rate moving from 93.4% to 92.9%. This experiment used the now-removed session-model judge path; the current Jev / Laya configuration has not been remeasured. See live model results and the cache FAQ.

Built around context engineering and token efficiency, sieve manages the context delivered to the model within the agent loop, reducing repeated input across multi-step tool use.

[!IMPORTANT]

sieve works only with a judge model configured: Jev (hosted, needs an API key) or Laya (local, macOS on Apple Silicon). sieve never uses the session's model in its place. With neither configured, the plugin loads but changes no context. See judge models.

Why sieve

In an agent loop the main model rereads its whole context at every step. What makes requests large is rarely the user's input. It is:

• Tool output: build logs, test reports and command output run to thousands or tens of thousands of characters, and the next step usually needs a small part of it;
• Stale context: tool results that a later read superseded, or that stopped mattering long ago, are sent again at every step;
• Skill catalogs: dozens or hundreds of skill descriptions are injected at session start, most of them unrelated to the task.

All of this is billed as input tokens, fills the context window and dilutes the model's attention. sieve adds a judgment kernel on DSH's public extension points that admits, forgets and progressively discloses these three kinds of content, so the main model sees a shorter, more focused context at every step.

The hard part is deciding what can go. Fixed rules have to keep any output format they have not seen; asking the main model to decide costs its tokens and a full round of reasoning. sieve hands this step to a dedicated judge model that answers structured yes/no and single-choice questions with probabilities, and the kernel rewrites or keeps the original by threshold. In offline replay, the median latency of one Jev judgment was about 0.3 seconds.

Core capabilities and use cases

For AI coding agents running on DeepSeek Harness, especially tasks with verbose test logs, frequent tool calls, long sessions or large skill catalogs.

Optimization area · How sieve handles it Input token reduction · Filters redundant tool content before it enters the session, reducing input resent on later steps Tool output filtering · Handles build logs, test reports and command output by category, protecting failure details and test summaries Context compaction / pruning · Replaces irrelevant older tool results in batches, retaining archive pointers for on-demand retrieval Progressive skill disclosure · Shows skills by task relevance, reducing context window usage from unrelated descriptions Prompt cache awareness · Processes new results before they are recorded and batches historical pruning to control prefix rebuild frequency

Quick start

1. Install the plugin (the web profile also gets the panel):

dsh plugin --profile web add dsh-sieve@0.2.0 dsh-sieve-web@0.2.0

1. Configure a judge model, one of:

• Jev: paste a TypeSafe or OpenRouter API key on the Sieve page of the DSH Web sidebar, or set the TYPESAFE_API_KEY environment variable;
• Laya: start the Laya server on this machine and set judge.type to laya in the profile, see Using Laya.

1. Restart dsh web and reload the page, then enter /sieve status in a session and check that the "判断模型" (judge model) line does not say "未配置" (not configured).

For other ways to install (GitHub Release, building from source) see Installation.

Architecture

flowchart LR
    subgraph Loop["DSH Agent Loop"]
        T[Tool execution] -->|post-execute| A
        P[agent/pre-step] --> F
        S[Skill catalog injection] --> D
    end

    subgraph Sieve["dsh-sieve"]
        A["tool.admission<br/>tool.admission.test-log"]
        F[context.forget]
        D[skills.disclosure]
        K(("Judgment kernel<br/>Judge Engine"))
        A <--> K
        F <--> K
        D <--> K
    end

    K <-->|"System One / local HTTP"| J[("Judge model<br/>Jev · Laya")]
    A & F -->|originals| SP[(spill archive)]
    K -->|decision records| L[(ctx.storage ledger)]
    L --> W["/sieve command · Web panel"]

    A & F & D -->|reduced context| M[Main model request]

Component · Role Judgment kernel · One decision engine: builds the questions, calls the judge model, validates the structured answers and decides by confidence threshold whether to rewrite; a timeout or failure always keeps the original `tool.admission` · Admission control for tool results before they enter the session; handles long output in tiers and rewrites only content, never the tool call `tool.admission.test-log` · A dedicated admission path for test runs that protects failures, summaries and anything it does not recognize `context.forget` · Forgets older tool results in batches through DSH's native compaction/prune and result replacement; a batch is committed only when it saves enough, see the cache FAQ `skills.disclosure` · Filters the first skill catalog by task relevance and announces skills that become relevant in later turns; hidden skills can still be loaded directly Ledger · One ctx.storage document per session with each judgment's result, usage and estimated saving `dsh-sieve-web` · DSH Web sidebar panel: the session's estimated input token reduction and context reduction in characters, the judge model in use, and Jev key configuration

Judge models (Jev / Laya)

What rules can handle, deterministic rules handle. What they cannot settle goes to the judge model. A decision point turns the content into structured questions (yes/no, single choice); the judge model answers each with a probability or an option, and the kernel rewrites or keeps the original by threshold.

flowchart LR
    D[Decision point] --> R{Judge model configured?}
    R -->|no| N[Change nothing<br/>rules do not run either]
    R -->|yes| Q[Structured questions<br/>redacted]
    Q --> JV["Jev<br/>System One protocol"]
    Q --> LY["Laya<br/>local sidecar"]
    JV & LY -->|probabilities / options| P{Threshold}
    P -->|passes| AP[Rewrite context]
    P -->|fails / timeout / error| KP[Keep original]

Judge model · Description · Needs Jev · TypeSafe's structured judgment model. It answers yes/no and single-choice questions natively over the System One protocol, with a probability for each answer. Reached through TypeSafe's own endpoint or OpenRouter, billed by TypeSafe (official pricing) · A TypeSafe or OpenRouter API key Laya · An open-weight typed decision model (mmBERT-base, 322M) running on Core ML on this machine: requests never leave it and cost nothing. Its window is only 1024 tokens, so long states are cut, and it is clearly weaker than Jev on complex questions · macOS on Apple Silicon, with the local Laya server running

No session model. Judgments go only to Jev or Laya. sieve never hands a judgment to the session's main model and has no setting for it; a profile from an older version with judge.type: llm, judge.type: off, judge.provider or routes fails to load.

No judge model, no changes. The default judge.type: auto looks for a Jev key before each decision. Without one, all four decisions let everything through: nothing is folded, forgotten or filtered, and nothing is recorded; /sieve status and the web panel say no judge model is configured. A saved key takes effect from the next decision, without a restart.

Judgments stay out of the conversation. A judge call is a side request: it is not written to the session log, does not enter the main model's context and does not change the main model's request prefix. What goes to the judge is redacted first: only content that is certainly a credential is replaced, namely credential-shaped tokens, assignments whose names mark them as secrets, and the values of this process's credential variables.

Failure keeps the original. Each judgment has a deadline (4000 ms by default); on a timeout, an error or an invalid answer the original is kept and the reason is recorded in the ledger.

Using Jev

Provide a key in any of these ways:

• Web panel: the "Jev 判断服务" (Jev judge service) section of the Sieve sidebar page. Paste a TypeSafe or OpenRouter key and save it. The key is stored in $DSH_HOME/.credentials.yaml, sent only to the host, and never shown again. With both configured, TypeSafe is used.
• Environment variables: TYPESAFE_API_KEY or SIEVE_JUDGE_OPENROUTER_API_KEY, in the shell that starts dsh, a .env in the start directory, or $DSH_HOME/.env. Process environment variables take precedence over keys saved in the panel; the panel then shows only the source and cannot change it.
• Profile: judge.type: system-one with an apiKey (preferably !!js process.env.XXX) and optional baseUrl and model, see Configuration.

[!NOTE]

With the default auto, any TYPESAFE_API_KEY in the environment (an export in a shell profile, or a project .env) makes sieve call Jev and incur TypeSafe charges.

Measured in offline replay: 326 Jev requests, all successful; HTTP latency P50 287 ms, P95 590 ms.

Using Laya

Laya runs on this machine and supports only macOS 15+ on Apple Silicon (Core ML). sieve only connects to a Laya server over local HTTP, by default at 127.0.0.1:47823; it ships no server and does not install or start one. Setting one up takes three parts:

1. Inference library: laya-coreml (Apache-2.0), a Core ML port of Laya that needs no PyTorch. With uv:

uv venv --python 3.12 ~/.laya/.venv

uv pip install --python ~/.laya/.venv/bin/python --index-url https://pypi.org/simple laya-coreml==0.1.0

1. Weights: the checkpoint aac6fef/laya-multilingual-coreml on Hugging Face (mmBERT-base, 322M, FP16, about 680 MB). Download it and check it against the bundle's own manifest:

~/.laya/.venv/bin/python - <<'PY'
   import json
   from pathlib import Path
   from huggingface_hub import snapshot_download
   from laya_coreml.artifacts import verify_files

   target = Path.home() / ".laya/models/laya-multilingual-coreml"
   snapshot_download("aac6fef/laya-multilingual-coreml", local_dir=target, allow_patterns=[
       "coreml_config.json", "rl_agent_config.json", "encoder/config.json", "tokenizer/*",
       "model.mlpackage/**", "host_weights.safetensors", "README.md", "LICENSE*", "NOTICE*"])
   files = json.loads((target / "coreml_config.json").read_text())["files"]
   verify_files(target, files)
   print(f"verified {len(files)} files")
   PY

In Python, laya_coreml.load(model_dir, local_files_only=True) returns a model whose predict(state, questions) answers Laya's own question types (noul, choice, score).

1. HTTP server: a small local service around that model that implements the protocol below. sieve does not provide one; write your own or use any implementation of the same protocol.

Laya server protocol

POST /evaluate, Content-Type: application/json:

{
  "state": "string, object or array",
  "questions": {
    "q1": { "type": "boolean", "instructions": "…", "criteria": { "true": "…", "false": "…" } },
    "q2": { "type": "choice", "instructions": "…", "criteria": { "keep": "…", "drop": null } },
    "q3": { "type": "score", "instructions": "…", "criteria": ["low", "mid", "high"] }
  }
}

boolean corresponds to Laya's noul; criteria of a boolean question is optional, and null descriptions should be passed to Laya as empty or left out. A successful response is HTTP 200:

{
  "answers": {
    "q1": { "type": "boolean", "probability": 0.93 },
    "q2": { "type": "choice", "choice": "keep", "probabilities": { "keep": 0.81, "drop": 0.19 } },
    "q3": { "type": "score", "score": 1.4, "probabilities": { "0": 0.1, "1": 0.4, "2": 0.5 } }
  },
  "usage": { "inputTokens": 980, "outputTokens": 0 },
  "warnings": [{ "type": "state_truncated", "questionId": "q1", "message": "…" }],
  "providerMetadata": { "laya": { "model": "laya:aac6fef/laya-multilingual-coreml", "answers": { "q1": { "confidence": 0.7 } } } }
}

• Every question must get an answer of the same type, or sieve rejects the whole response. probability is P(true); score is a fractional position in [0, levels - 1].
• usage, warnings and providerMetadata are optional. warnings is where truncation should be reported (sieve records it in the ledger); providerMetadata.laya.model names the model in the ledger, and confidence must be in [0, 1] or it is ignored.
• Errors: 4xx (bad request) or 5xx (server failure) with {"error": {"message": "…"}}; either way sieve keeps the original.
• Bind to loopback only, since the protocol has no authentication. A Core ML model must not be called concurrently, so serialize requests.

With the server running, set in the profile:

- id: sieve
  config:
    judge:
      type: laya
      # baseUrl: http://127.0.0.1:47823   # the default; set it only if the sidecar uses another port

While the Laya server is not running, every judgment fails and keeps the original, recorded as error:unreachable in the ledger; the rules still run.

[!NOTE]

Laya's window is 1024 tokens, shared by the question, its options and the state; anything beyond is cut from the end of the state and recorded as a warning in the ledger. Earlier measurements show it usable on simple predicates and close to random on questions that need a synthesized judgment. sieve's four decisions have not been measured on Laya; use Jev when judgment quality matters.

Design constraints

sieve aims to reduce context without lowering the task success rate, so it holds itself to a few hard constraints:

• Nothing is lost: before any lossy rewrite, the original goes to the spill archive, and the model can read it back on demand.
• Cold restore is consistent: everything the model sees can be rebuilt from the session log. Requests after a resume or fork match the live ones, with no repeated judgments or rewrites.
• No custom events: state is derived from native DSH events and the ledger lives in ctx.storage, so an unknown event can never make a session unresumable.
• Zero DSH core patches: only public extension points (agent/pre-step, tool post-execute, the skill catalog listener, ctx.storage, ctx.credentials, connection.fetch routes).
• Resources follow the plugin lifecycle: every listener and timer is registered through ctx and every operation honors AbortSignal, so unloading and hot reload clean up completely.
• Fail open: when the judge model is unavailable, answers invalidly or times out, the original is kept.

Each constraint has contract tests that check call order, result replacement, spill order, skill catalog filtering and cold restore against the pinned DSH source.

Offline replay results

The data are frozen public agent trajectories and raw sessions. Each trajectory was replayed with all four decisions off and with all four on, paired one to one, on the real DSH loop with sieve's listeners. The judge was the real Jev (jev-1.13.0); main model calls were replayed.

Dataset · Pairs · Total request payload · Tool output SWE-smith + Nebius public trajectories · 100 · 537,410,284 → 342,420,598 chars (−36.28%) · 11,312,658 → 4,193,084 chars (−62.93%)   of which SWE-smith · 50 · −30.88% · −50.47%   of which Nebius · 50 · −37.58% · −67.66% SWE-chat raw sessions · 7 · 33,733,731 → 18,204,646 chars (−46.03%) · 314,263 → 128,407 chars (−59.14%)

Information retention. On 38 hand-labeled tool output samples (29 for tuning, 9 held out), required information was kept 72/72 and 19/19, with zero labeled deletions.

Correctness. All 222 replays passed the checks on tool return values and error states, protected log lines, the original archive, native cold restore and projection rebuild; all 1,422 archived originals can be read back byte for byte.

Judge overhead. 326 Jev requests, all successful, no fallbacks; 729,167 input and 30,868 output tokens. HTTP latency P50 287 ms, P95 590 ms, max 1,195 ms, none over 4 seconds (the replay waited longer; the production 4-second deadline was not rerun in this round).

[!NOTE]

Payload and tool output are counted in characters of request JSON. The two measures overlap, cannot be added, and are not actual tokens. Offline replay fixes the follow-up actions, so it cannot show that re-reads and task success are unchanged in a live run. The SWE-chat replay covers only the first skill catalog, not later re-disclosure.

Live model results (DeepSeek Flash)

On 2026-10-07 we ran a paired experiment with a live main model on deepseek-flash: the pinned DSH CLI (0.2.1-alpha.1) ran real headless sessions in a disposable DSH_HOME, and the model chose its own tool calls. 4 tasks (fix from a test log, fix from a build error, load a skill, 7 incremental edits plus a recall question) × 4 configurations × 5 repetitions; all 80 runs were valid, and the decision rules were written down before the runs.

Configuration · Main input tokens · Cache misses · Output · Cache hit rate sieve off (baseline) · 3.73M · 248K · 68K · 93.4% Baseline, second run (noise reference) · +4.5% · −2.4% · −1.4% · 93.8% All four decisions on · −21.2% · −15.3% · −6.7% · 92.9% All on, forgetting off · −11.6% · −11.5% · −3.5% · 93.3%

• Tokens: all on used about 21% fewer tokens than the baseline, beyond the noise of rerunning the same configuration (about 4%). With forgetting off the saving was about 11%, so forgetting accounts for about half.
• Cache: the hit rate did not change with sieve on; excluding each run's first request, it was 96.1% for the baseline and 96.3% with all on. Why forgetting rewrites history without lowering the hit rate is explained in the FAQ.
• Task results: every configuration solved the code tasks 20/20. On the recall question, all on answered wrong once, because the model itself cut the line with the answer using tail -60; sieve had not touched that output. Every other configuration answered correctly.

[!NOTE]

At the time of this run sieve still allowed the session's model to judge, and there was no Jev key in the environment, so deepseek-flash judged for itself (5 of 17 calls exceeded the 4-second deadline and kept the original). The current version has removed that path and needs Jev or Laya; the table has not been rerun with Jev or Laya. Since most of the saving comes from rules, the change of judge model mainly affects what the rules cannot settle. The experiment also covers only 4 self-built tasks on deepseek-flash, task success is near the ceiling so it discriminates little, and cold restore was not tested.

FAQ