Documentation
¶
Overview ¶
Package dedup implements a per-session dedup stub for token-heavy sofia tools: a repeated, byte-identical call within a short window of the same session returns a one-line stub ("already returned in call #N; --force to repeat") instead of paying for the full output again. This is the self-teaching-stdout counterpart to internal/common/hook's Read guard — hook stops the FIRST wasteful full read, dedup stops a SECOND identical tool call from re-paying for output the agent already has in context.
Mirrors hook's State/gc/sanitize pattern (internal/common/hook): one append-only JSONL file per session, no locks. The difference is the key — hook keys on a bare file path, dedup keys on the whole call (tool + normalized arguments), since the concern here is a repeated QUERY, not a repeated read of one file.
Currently wired into `sf code` only (see the H-B build plan); the package itself is generic, and a second caller (grep, changed) is a follow-up if telemetry shows the same repeat rate there.
Index ¶
Constants ¶
const DefaultWindow = 180 * time.Second
DefaultWindow is the dedup window used when SOFIA_DEDUP_WINDOW is unset or unparseable.
Variables ¶
This section is empty.
Functions ¶
func Key ¶
Key returns a stable, order-insensitive identifier for "the same call": tool plus its normalized arguments, reusing calllog's existing Fingerprint so dedup groups calls exactly the way history already does. Callers build parts from whatever makes two invocations equivalent (e.g. code.keyParts).
func Window ¶
Window reads SOFIA_DEDUP_WINDOW (whole seconds); 0 disables dedup entirely; unset or unparseable falls back to DefaultWindow. Same Sscanf idiom as code.rawBelow — 0 is meaningful here too (the off switch), so only negatives are rejected.
func WriteStub ¶
WriteStub writes the one-line dedup stub for hit in the given output format (json gets the structured form, everything else — toon, md, plain slice output — gets the text line). Callers still print the normal cost footer after this (see emit.Footer): SOFIA_FOOTER=off silences that footer but not the stub line itself, which is the payload, not decoration.
Types ¶
type Guard ¶
type Guard struct {
// contains filtered or unexported fields
}
Guard is the per-call handle Begin returns. Call Hit once; if it's non-nil, emit the stub and call CommitStub; otherwise produce the full output and call CommitFull on every successful path (never on a failed one — a failed call must not poison a retry with a dedup stub).
func Begin ¶
Begin opens a dedup check for one call: tool names the caller (e.g. "code"), force bypasses the check (the call still records itself, so a later non-force call sees it as the new "original"), and keyParts are the caller-specific arguments that define "the same call" (see Key).
func (*Guard) CommitFull ¶
CommitFull records that this call produced fresh, full output: tok is its token cost, filed under the next ordinal in the session's log. Call this only on a successful full-output path.
func (*Guard) CommitStub ¶
func (g *Guard) CommitStub()
CommitStub records that a stub was emitted for a dedup hit, sliding the window forward: the new entry repeats the ORIGINAL call's ordinal and token cost with a fresh timestamp, so a stub-of-a-stub still points at the real call.
Source Files