DSH plugin token meter and spill: logRevision and SpillRef

DSH plugin context cost is decided by two mechanisms: token metering, which snapshots pressure per position, and spill, which moves oversized intermediates out of context. Metering's key property is logRevision — every number corresponds to "how many durable events were consumed" — so an older snapshot remains interpretable as replay advances. Node pricing splits in two: route-priced tokens drives trigger and retention decisions, while the fixed-heuristic heuristicTokens keeps shadow pricing consistent. Spill does exactly one thing: save caller-supplied text verbatim and return an opaque locator whose hint you render but never parse.

DSH plugin token metering: an immutable snapshot at a revision

Bottom line: the measurement is immutable and anchored to consumed event count; replay moving on does not reshape it.

1. Core fields: logRevision, baseline, surfaceDeltaTokens (signed), totalTokens, surfaceTokens, nodes.
2. Two anchor kinds: baseline.kind === 'usage' means the latest successful call shares the canonical envelope and is no lower than its full route-priced anchor; estimated means no reusable conservative anchor exists and the service prices the full envelope and surface itself.
3. Anchors are replaced: later successful calls replace earlier anchors, with both sides repriced under the same route.
4. Two totals: totalTokens is pressure, surfaceTokens is the surface price sum.
5. Reading the numbers: if totalTokens rises while surfaceTokens stays flat, the pressure came from responses, not from more surface content.

DSH plugin surface pricing: nodes, two token values and positional order

Bottom line: surface order is authoritative, and a replacement node's seq may exceed nodes positioned after it — never sort by seq.

1. Images follow the route: when the routed adapter declares image pricing, images charge visual tokens plus model-visible text; other routes keep the heuristic.
2. Order is authoritative: a replacement node's durable seq may be higher than nodes after it, so sorting by seq breaks semantics.
3. Immutable snapshot: it does not grow as the replay fold advances, which makes it safe to cache and compare.
4. O(1) fold: heuristicTokens exists so projection folds agree with their own appends; do not use it for decisions.

DSH plugin measurement: measure and estimateMessage

Bottom line: measure recomputes the current surface and accepts a replacement envelope; estimateMessage prices one message heuristically.

1. Whole-session measurement:

const m = ctx.tokenMeter.measure(session, requestHeader?)
// m.logRevision / m.totalTokens / m.surfaceTokens / m.nodes

2. Replacement envelope: passing requestHeader replaces the latest logged envelope, useful for "what will this next request cost."
3. Complexity: every call clones positional nodes, so it is O(surface) — avoid high-frequency calls on very long sessions.
4. Single message: ctx.tokenMeter.estimateMessage(message) uses the fixed heuristic.
5. Selection: use measure for cost decisions and estimateMessage (or node heuristicTokens) for shadow pricing.

DSH plugin spill: saveText and an opaque locator

Bottom line: spill has one operation, saving text verbatim and returning a locator, byte count and retrieval hint.

interface SaveTextSpill {
  owner: { sessionId: SessionId }
  source: { kind: 'tool'; toolName: string; callId: ToolCallId; label: string }
        | { kind: 'session-reference'; sessionId: SessionId; label: string }
  suggestedName: string   // a naming hint, never a path
  content: string
}
// returns SpillRef: { locator, bytes, retrievalHint }

1. Owner scopes storage: the backend groups by producing session; forked sessions inherit locators already in the seeded log, artifacts are not copied or re-owned, and new spills use the child session id.
2. Source is descriptive only: tool sources carry a callId, session-reference sources carry the captured session id; it is never access control.
3. suggestedName is a hint: the backend sanitizes it to a single safe path segment.
4. Locators are opaque: a local backend renders a path, remote backends may render URIs or keys; render with retrievalHint, never parse.
5. Failures reject: real storage failures (permissions, ENOSPC, backend unavailable) reject, and the caller decides how to degrade.
6. Scope: the seam only stores; it owns no retention policy, tool-result replacement or search API.

DSH plugin local spill backend: layout, permissions and symlink defense

Bottom line: the local backend writes into a private session subdirectory with exclusive owner-only writes, preventing planted symlinks from redirecting output.

1. Path shape: <root>/session-<hash>/<random>-<safeName>, with session subdirectories keyed by sha256(sessionId).
2. Private root: the root is a configured or lazily created private directory (0700).
3. Write mode: open(path, 'wx', 0o600) — exclusive and owner-only, so a pre-planted symlink cannot redirect the write.
4. Retrieval hint: the local backend tells the model to use read or grep on that path.
5. Single implementation: only one ctx.spillStore per context; loading a second fails under Cordis duplicate-service rules.

DSH plugin metering and spill troubleshooting

Bottom line: match revisions for metering, and never treat a spill locator as a path.

1. Numbers disagree — compare logRevision; different revisions should not match.
2. Surface order looks wrong — you sorted by seq; surface order is authoritative.
3. Cost jumped — check whether totalTokens or surfaceTokens moved.
4. Spill locator will not open — do not build paths; follow retrievalHint, which may not be a path at all.
5. Tool errors after a failed save — the consumer turned a reject into isError; the official policy keeps the inline result.
6. Repair status, stated honestly: measurement fields, anchor rules and the spill contract follow the official Token metering and Spill storage pages; confirm signatures against their Cordis API blocks and your version.

Sources: Token metering, Spill storage, dsh-token-meter source.