@namzu/sdk 38.2.1 → 40.0.0

package/dist/runtime/query/file-evidence-context.js

@@ -0,0 +1,180 @@
+import { fingerprintContent } from '../../tools/builtins/content-fingerprint.js';
+import { ReadFileTool } from '../../tools/builtins/read-file.js';
+import { MAX_EDIT_CALLS, MAX_PATH_UNITS, MAX_WITNESSED_PATHS, createReplayBudget, indexVisibleHistory, knownStale, lexicalFileKeys, replayHop, spend, visibleCall, visibleEdit, visibleWrite, } from './file-evidence-replay.js';
+/**
+ * Receipt text a read entry may point at.
+ *
+ * The same class of bound as the one on a write call's arguments, and set to
+ * the same number for the same reason: past it the text is not read at all. A
+ * bigger file is simply not admitted this way — the model re-reads it, which is
+ * what it does today.
+ */
+const MAX_RECEIPT_UNITS = 32_000;
+/** Join visible call bodies, successful receipts and this executor's observation ledger. */
+export function describeVisibleFileEvidence(messages, tracker, workingDirectory, sandboxed) {
+    // Execution-owned witnesses survive transparent wrappers; a name alone proves nothing.
+    if (!tracker.writeCallId || !tracker.fingerprint)
+        return;
+    // Lexical, as this projection has always looked entries up: a spelling that
+    // does not resolve to the tool's canonical key finds nothing and the path is
+    // simply not admitted. Writing the ledger is the side that has to key the
+    // way the tools do — see `file-evidence-seed.ts`.
+    const history = indexVisibleHistory(messages, lexicalFileKeys(workingDirectory, sandboxed));
+    const budget = createReplayBudget();
+    const files = new Map();
+    for (const [id, call] of history.calls) {
+        const name = call?.function.name;
+        if (name !== 'write' && name !== 'edit' && name !== 'read')
+            continue;
+        try {
+            const admitted = name === 'write'
+                ? writeEvidence(id, tracker, history)
+                : name === 'edit'
+                    ? chainEvidence(id, tracker, history, budget)
+                    : readEvidence(id, tracker, history);
+            if (!admitted)
+                continue;
+            // A write-rooted entry outranks a read of the same file: it names a
+            // body the model composed itself, and edits can be replayed onto it.
+            // The ledger already withholds a read witness where one survives; this
+            // keeps a read that ran BEFORE the write from taking the path back.
+            const held = files.get(admitted.key);
+            if (admitted.evidence.kind === 'read' && held && held.kind !== 'read')
+                continue;
+            files.delete(admitted.key);
+            files.set(admitted.key, admitted.evidence);
+            if (files.size > MAX_WITNESSED_PATHS)
+                files.delete(files.keys().next().value);
+        }
+        catch {
+            // Malformed retained inputs or a custom tracker cannot establish evidence.
+        }
+    }
+    if (files.size === 0)
+        return;
+    return `Visible file evidence (this request only): each entry's current body is the complete body in the named successful write call, with the edit calls in editsInCalls — when present — applied in that order. An entry marked kind:"read" instead names a successful read call whose own receipt shows the file WHOLE, rendered with every line behind its own N<tab> prefix; that receipt is the body, and such an entry never carries editsInCalls. This runtime performed that reconstruction and checked it against its own file observation; it is not a derivation left to you. Reuse the body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check, and after a resume the observation behind an entry may itself have been rebuilt from this conversation's own earlier calls rather than made while this process ran. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`;
+}
+/** A full body that arrived whole in one call and is still the file's body. */
+function writeEvidence(id, tracker, history) {
+    const written = visibleWrite(history, id);
+    if (!written || knownStale(tracker, written.key))
+        return;
+    const fingerprint = fingerprintContent(written.body);
+    if (tracker.writeCallId?.(written.key) !== id ||
+        tracker.fingerprint?.(written.key) !== fingerprint)
+        return;
+    return {
+        key: written.key,
+        evidence: {
+            path: written.path,
+            bodyInCall: id,
+            observedFingerprint: fingerprint,
+        },
+    };
+}
+/**
+ * A full body plus the visible edits since, replayed and then checked.
+ *
+ * Only the chain's TIP establishes the path: a middle hop is validated as part
+ * of the walk below, and admitting one on its own would claim the file stops
+ * at an edit later calls have already moved past. The replay runs the same
+ * apply core the tool ran at mutation time, over call arguments that are
+ * already in the conversation — no filesystem read, and the result is compared
+ * to the ledger's disk-derived fingerprint, never written into it.
+ */
+function chainEvidence(id, tracker, history, budget) {
+    const tip = visibleEdit(history, id);
+    if (!tip || knownStale(tracker, tip.key))
+        return;
+    const key = tip.key;
+    const chain = tracker.editChain?.(key);
+    const observed = tracker.fingerprint?.(key);
+    if (!chain || observed === undefined || chain.editCallIds.at(-1) !== id)
+        return;
+    // The call bound before the walk, the unit bound before each operation it
+    // pays for. Neither is measured by doing the work it exists to refuse.
+    if (chain.editCallIds.length > MAX_EDIT_CALLS)
+        return;
+    const rootId = chain.rootWriteCallId;
+    const root = visibleWrite(history, rootId);
+    // A root naming a different file is an ambiguity, not a base: the ledger
+    // and the visible call disagree about what was written where.
+    if (!root || root.key !== key)
+        return;
+    let content = root.body;
+    if (!spend(budget, content.length))
+        return;
+    for (const editId of chain.editCallIds) {
+        const hop = editId === id ? tip : visibleEdit(history, editId);
+        if (!hop || hop.key !== key)
+            return;
+        // Each of this hop's operations is measured against the body it is about
+        // to be applied to, charged, and only then applied — so a hop over the
+        // ceiling is refused before it is built rather than after, and one that
+        // fits is never turned away for a ceiling that guessed high. A hop the
+        // budget refuses, or one whose anchors no longer match, reconstructs
+        // nothing and withholds the whole path.
+        const replayed = replayHop(content, hop.input, budget);
+        if (replayed === undefined)
+            return;
+        content = replayed;
+    }
+    if (fingerprintContent(content) !== observed)
+        return;
+    return {
+        key,
+        evidence: {
+            path: root.path,
+            bodyInCall: rootId,
+            editsInCalls: [...chain.editCallIds],
+            observedFingerprint: observed,
+        },
+    };
+}
+/**
+ * A body the model can still see because a read of the whole file put it there.
+ *
+ * Structurally unlike the two above, and deliberately so. They name a body the
+ * model itself composed, in arguments this projection can parse and replay; this
+ * names a RESULT, and the only thing anyone is allowed to do with it is compare
+ * it. The tool fingerprinted the exact string it emitted, and the entry is
+ * admitted only while the receipt still fingerprints to that — so a receipt the
+ * output budget elided or spilled, one compaction cleared, or one changed in any
+ * other way withholds the path rather than pointing the model at a body that is
+ * no longer in front of it. Nothing here undoes the line numbering to recover
+ * text: the numbering is what makes the comparison conclusive, not an encoding
+ * to be reversed.
+ *
+ * No chain, ever. A read roots nothing, so an entry here is the file as that one
+ * call showed it, and the ledger drops the witness the moment an edit lands.
+ */
+function readEvidence(id, tracker, history) {
+    if (!tracker.readWitness)
+        return;
+    const call = visibleCall(history, id, 'read');
+    const shown = history.results.get(id)?.content;
+    if (!call || typeof shown !== 'string' || shown.length > MAX_RECEIPT_UNITS)
+        return;
+    const input = ReadFileTool.inputSchema.safeParse(JSON.parse(call.function.arguments));
+    if (!input.success || input.data.path.length > MAX_PATH_UNITS)
+        return;
+    const key = history.keyOf(input.data.path);
+    if (key === undefined || knownStale(tracker, key))
+        return;
+    const witness = tracker.readWitness(key);
+    const observed = tracker.fingerprint?.(key);
+    if (!witness || witness.callId !== id || observed === undefined)
+        return;
+    if (fingerprintContent(shown) !== witness.renderedFingerprint)
+        return;
+    return {
+        key,
+        evidence: {
+            path: input.data.path,
+            kind: 'read',
+            bodyInCall: id,
+            observedFingerprint: observed,
+        },
+    };
+}
+//# sourceMappingURL=file-evidence-context.js.map

package/dist/runtime/query/file-evidence-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-evidence-context.js","sourceRoot":"","sources":["../../../src/runtime/query/file-evidence-context.ts"],"names":[],"mappings":"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"}

package/dist/runtime/query/file-evidence-replay.d.ts

@@ -0,0 +1,260 @@
+import type { Message, ToolCall } from '../../types/message/index.js';
+import type { FileReadTracker } from '../../types/tool/index.js';
+/**
+ * Reconstructing a file's body from calls the conversation can still see.
+ *
+ * One module because two callers need the same answer and must not each have
+ * their own idea of it: the derived work context asks "is this ledger entry's
+ * body one the model can rebuild from what is in front of it?", and the resume
+ * seed asks "which of these ledger entries can be rebuilt at all?". A
+ * predicate that admitted a hop in one and refused it in the other would mean
+ * a path referenced as evidence that the ledger never witnessed, or the
+ * reverse. Everything below is a function of the messages, the ledger and the
+ * bounds — there is no filesystem access anywhere in this file.
+ */
+/**
+ * Edit CALLS one chain may carry before the path is withheld.
+ *
+ * On calls rather than replacements because the bound is on replay work, and
+ * an `edits: [...]` batch is one pass over the content however many hunks it
+ * holds. Eight is generous for the shape this exists for — a file written and
+ * then refined within a turn — and short enough that the whole request's
+ * replay stays a rounding error beside the model call it rides on.
+ */
+export declare const MAX_EDIT_CALLS = 8;
+/**
+ * Content a replay may materialise across every path in one pass.
+ *
+ * Counted cumulatively in UTF-16 units — the measure the caps below and the
+ * step-context budget already use — and charged for the write body each chain
+ * starts from as well as every body an edit builds on top of it, because those
+ * are the strings actually built. Each operation is measured exactly against
+ * the content it is about to be applied to and refused before it is built, so
+ * a pass whose history is full of long chains it is going to refuse anyway
+ * cannot make itself slow proving that. A refusal is charged nothing: the body
+ * was never built, and the paths after it keep their room.
+ */
+export declare const MAX_REPLAYED_UNITS: number;
+/**
+ * Path lengths a `write` entry may go out with.
+ *
+ * Exported because `file-evidence-context.ts` puts the same bound on the
+ * spelling a `read` entry emits — a read is the other thing that puts a path
+ * in the work-context message, and the constant belongs to this module.
+ */
+export declare const MAX_PATH_UNITS = 512;
+/**
+ * One pass's answer to "which file did this call touch", memoised.
+ *
+ * Keyed on the call OBJECT rather than on its id: an id claimed by two calls
+ * is an ambiguity this module refuses to settle by position, and settling it
+ * by cache hit instead would be the same mistake wearing a different hat. A
+ * `WeakMap` because the entries are worth exactly as long as the transcript
+ * they describe, and the value is the declared path or `null` for a call that
+ * declares none — `undefined` means only "not asked yet".
+ */
+export type PathAttributions = WeakMap<ToolCall, string | null>;
+export declare function createPathAttributions(): PathAttributions;
+/**
+ * The ledger key a tool-call path belongs to, or `undefined` for a path this
+ * pass may not key at all.
+ *
+ * A resolver rather than a working directory, because the two callers do not
+ * key alike and must not be made to. The projection READS a ledger the tools
+ * wrote and looks entries up lexically, as it always has: a spelling that does
+ * not match the tool's canonical key simply finds nothing. A seed WRITES that
+ * ledger, so its keys have to be the ones the tools will come looking for —
+ * which means resolving a path the way `write` and `edit` resolve it, through
+ * every symlink, and that is filesystem work nothing in this module is allowed
+ * to do. So the caller resolves first and hands the answers in.
+ */
+export type FileKeyResolver = (path: string) => string | undefined;
+/**
+ * The lexical key space: the path resolved against the working directory, or
+ * the path as written when the tools address a sandbox.
+ *
+ * What a reader of the ledger uses. Not what a writer of it may use: see
+ * {@link FileKeyResolver}.
+ */
+export declare function lexicalFileKeys(workingDirectory: string, sandboxed: boolean): FileKeyResolver;
+/** The calls and receipts of one conversation, indexed by call id. */
+export interface VisibleHistory {
+    /** `null` where an id was claimed by more than one assistant call. */
+    readonly calls: ReadonlyMap<string, ToolCall | null>;
+    /** `null` where an id was answered more than once. */
+    readonly results: ReadonlyMap<string, Message | null>;
+    /** The ledger key a tool-call path resolves to. */
+    readonly keyOf: FileKeyResolver;
+}
+/**
+ * Index a transcript once, so every lookup below is a map hit.
+ *
+ * An id claimed twice, or answered twice, indexes to `null` rather than to
+ * whichever message came last: two calls wearing one id is an ambiguity, and
+ * resolving it by position would let the second silently vouch for the first.
+ */
+export declare function indexVisibleHistory(messages: readonly Message[], keyOf: FileKeyResolver): VisibleHistory;
+/**
+ * Every path a replay of this history might have to key, in the order the
+ * calls arrived.
+ *
+ * For a caller that has to resolve them before the replay can run, and only
+ * for that: nothing here decides anything about a path. Empty when the history
+ * holds no `write` and no `edit` call at all, because a claim is only ever made
+ * by a mutation — a conversation that only read files reconstructs nothing, and
+ * resolving its reads would be filesystem work with no possible result.
+ *
+ * Every mutation the walk can ATTRIBUTE has to appear here, the ones it will
+ * refuse to reconstruct included. This used to drop a call whose arguments ran
+ * past the evidence bound, so the walk reached it holding no key for its path,
+ * read that as a mutation it could not attribute, and abandoned the seeding
+ * entirely: one thirty-kilobyte `write` anywhere in a conversation erased every
+ * witness in it. The bounds belong to what may be believed; the path is read
+ * here out of the same field the walk reads it from, under no bound at all.
+ */
+export declare function collectObservedPaths(messages: readonly Message[], attributions?: PathAttributions): readonly string[];
+/**
+ * The visibility every hop must pass, write or edit, root or tip.
+ *
+ * One function because a middle hop is not a lesser claim than the last one.
+ * A chain whose second edit was cleared by compaction, or came back an error,
+ * or arrived truncated, reconstructs nothing at all — so the whole path is
+ * withheld rather than emitted as the part still visible, which would name a
+ * body the model cannot rebuild.
+ *
+ * A call a `pre_tool_use` hook SKIPPED is the one refusal that does not arrive
+ * as an error. The hook declined the call; nothing failed, so the receipt is a
+ * plain success carrying the sentence `plugin-hooks.ts` writes for it, and
+ * reading that as a `write` would hand back a body the tool was never allowed
+ * to put on disk — a fingerprint for a file that still holds whatever it held
+ * before, and a spurious drift refusal on the next edit. Recognised through
+ * the same function that writes the sentence, so the two cannot drift apart.
+ */
+export declare function visibleCall(history: VisibleHistory, id: string, name: 'write' | 'edit' | 'read'): ToolCall | undefined;
+/** A full body that arrived whole in one visible call. */
+export declare function visibleWrite(history: VisibleHistory, id: string): {
+    readonly path: string;
+    readonly key: string;
+    readonly body: string;
+} | undefined;
+/**
+ * One visible edit call's arguments, ready to replay.
+ *
+ * No length bound on the path here, unlike the write above. A write's path is
+ * the spelling an entry goes out with; an edit is held to the KEY it resolves
+ * to, which its chain's root has already been bounded on.
+ */
+export declare function visibleEdit(history: VisibleHistory, id: string): {
+    readonly key: string;
+    readonly input: unknown;
+} | undefined;
+/** Room left for content this pass may still materialise. */
+export interface ReplayBudget {
+    remaining: number;
+}
+export declare function createReplayBudget(units?: number): ReplayBudget;
+/**
+ * Charge one body against the pass's replay allowance.
+ *
+ * Checked before it is taken, so a refusal costs nothing. Deducting first and
+ * reporting afterwards left the allowance negative, and one oversized path
+ * then refused every admissible path behind it in the same pass.
+ */
+export declare function spend(budget: ReplayBudget, units: number): boolean;
+/**
+ * Replay one edit call onto the body in hand, within what the budget has left.
+ *
+ * `undefined` for a hop the budget turns away and for one that no longer
+ * applies, because both mean the same thing to every caller here: this path
+ * reconstructs nothing. The charge is settled either way — what the attempt
+ * built, it built — and for a hop refused at its first operation that charge
+ * is zero.
+ */
+export declare function replayHop(content: string, input: unknown, budget: ReplayBudget): string | undefined;
+/**
+ * Whether a refused mutation has reported this path stale since the ledger
+ * last observed it.
+ *
+ * That refusal read the real file to make its comparison, so the ledger knows
+ * its body is behind disk without a consumer here touching the filesystem.
+ * The reconstruction would still be a body the model can rebuild — but not the
+ * FILE's body, which is what an entry claims. Withheld until a real
+ * observation re-baselines the ledger, which is also what clears the flag.
+ */
+export declare function knownStale(tracker: FileReadTracker, key: string): boolean;
+/**
+ * Paths one pass may hold a reconstructed body for at a time.
+ *
+ * The projection emits at most this many entries and keeps the most recent, so
+ * a pass that tracked more would be doing work whose result is discarded.
+ */
+export declare const MAX_WITNESSED_PATHS = 6;
+/** What one pass of {@link replayObservationLedger} established. */
+export interface LedgerReplayReport {
+    /** Paths whose body was reconstructed exactly, with a fingerprint and a witness. */
+    readonly pathsWitnessed: number;
+    /**
+     * Paths the conversation demonstrably mutated but whose body could not be
+     * rebuilt. Nothing is written to the ledger for these; see {@link commit}.
+     */
+    readonly pathsSeen: number;
+    /**
+     * Content materialised, in UTF-16 units. Never above
+     * {@link MAX_REPLAYED_UNITS}, and non-zero even for a pass that established
+     * nothing: it reports the work done, not the work kept.
+     */
+    readonly unitsReplayed: number;
+}
+/**
+ * Rebuild an observation ledger from a conversation's own history.
+ *
+ * The ledger is process state. A resumed conversation gets a fresh empty one,
+ * and until something reads a file again the runtime knows nothing about files
+ * this conversation wrote in full — so the projection admits nothing and the
+ * model re-reads a body already in front of it, every time a session is picked
+ * back up.
+ *
+ * What is reconstructable here is exactly what the projection would admit, by
+ * the same predicates and the same bounded replay, because both go through the
+ * functions above. A `write` whose call and successful receipt are both intact
+ * hands back its body and its witness; the edits on top of it are replayed
+ * hop by hop and extend the chain. Anything else about a path the conversation
+ * mutated — a receipt compaction cleared, a call the transcript never answered,
+ * a mutation it refused, one a `pre_tool_use` hook skipped before it ever ran,
+ * a hop that no longer applies, a body past the bounds, a call too long to
+ * quote back — withdraws whatever this pass was holding for that path and
+ * writes NOTHING for it.
+ *
+ * Content-backed observations only, and that is the whole of what a resume
+ * restores. A path in the ledger with no fingerprint is a path `write` lets
+ * through unread: the read-before-overwrite refusal is `hasRead`, and the drift
+ * comparison it guards needs a body to compare. Seeding membership alone would
+ * therefore admit a full overwrite of a file that changed while the session was
+ * closed, with nothing checked — weaker than the empty ledger a resume used to
+ * start from, which refuses that overwrite outright. So a path this pass cannot
+ * rebuild is left exactly as that empty ledger leaves it, and the first real
+ * read re-establishes it.
+ *
+ * Two things this deliberately does not do. It never reads the filesystem: a
+ * fingerprint restored here is a claim derived from history, and the built-in
+ * mutation checks still compare it against the real file before anything is
+ * written — so a file changed while the session was closed is refused exactly
+ * as it is today, and the refusal's drift flag withdraws the entry. And it
+ * never recovers a body from a `read` receipt by undoing the line numbering: a
+ * read's rendering is compared, whole, against a body this pass already holds,
+ * and a read that cannot be matched that way withdraws the body rather than
+ * supplying one.
+ *
+ * That first guarantee is the reason `keyOf` is a parameter. Everything written
+ * here has to land on the key the mutation tools will look it up under, and on
+ * a host those keys are canonical — `write` and `edit` follow every symlink
+ * before they touch the ledger. Keying a seed lexically instead writes entries
+ * into a key space the tools never read: the projection would then match a
+ * fingerprint this pass had just written to it, and the drift refusal that is
+ * supposed to withdraw the claim would land somewhere else and never reach it.
+ * So the caller resolves the paths the way the tools do — see
+ * `file-evidence-seed.ts` — and a path it could not resolve gets no key, which
+ * makes the mutation that named it unattributable and stops the pass.
+ */
+export declare function replayObservationLedger(messages: readonly Message[], tracker: FileReadTracker, keyOf: FileKeyResolver, attributions?: PathAttributions): LedgerReplayReport;
+//# sourceMappingURL=file-evidence-replay.d.ts.map

package/dist/runtime/query/file-evidence-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-evidence-replay.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/file-evidence-replay.ts"],"names":[],"mappings":"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"}