@anureo/sdk 0.0.0-stage → 0.3.0

package/src/lifecycle/result.js

@@ -0,0 +1,213 @@
+import { HarnessSdkError } from "../errors.js";
+import { immutable } from "./immutable.js";
+/**
+ * Session.context creates one accumulator per execution. Session.retainEvent supplies privacy-projected
+ * events in publication order and uses the terminal snapshot to resolve the promise read by Turn.result.
+ * Session owns event validation, publication, shared budgets and reclamation.
+ */
+export class ResultAccumulator {
+    maxBytes;
+    maxItems;
+    /**
+     * Session.context supplies positive safe integers for serialized bytes and distinct items.
+     * Omitted session limits default to 16 MiB and 2,048 items before construction.
+     */
+    constructor(maxBytes, maxItems) {
+        this.maxBytes = maxBytes;
+        this.maxItems = maxItems;
+    }
+    /**
+     * Return the UTF-8 JSON byte total of the individual items as if buffered text were materialized.
+     * Session.retainEvent uses the difference across an update for its shared budget, and
+     * Session.reclaimExecution subtracts the total on eviction. Usage and envelope bytes are excluded.
+     */
+    get size() { return this.bytes; }
+    /**
+     * Retain detached turn usage and item content before Session.retainEvent publishes the event.
+     * Snapshots replace buffered content and completed items ignore subsequent deltas. A conflicting
+     * patch throws PROTOCOL_ERROR. Exceeding either limit throws RESULT_BUDGET_EXCEEDED. These throws
+     * reject Session.emit and reach Session.fail, which rejects unfinished Turn.result waits.
+     * Serialization and clone failures also propagate to Session.emit.
+     */
+    accept(event) {
+        switch (event.type) {
+            case 'usage/updated':
+                if (event.payload.scope === 'turn')
+                    this.usage = structuredClone(event.payload);
+                break;
+            case 'item/started':
+            case 'item/completed':
+                this.retainSnapshot(event.payload.item);
+                // Mark completion only after retention succeeds, so a rejected snapshot cannot suppress deltas.
+                if (event.type === 'item/completed')
+                    this.completed.add(event.payload.item.id);
+                break;
+            case 'item/delta':
+                if (!this.completed.has(event.payload.itemId))
+                    this.acceptDelta(event.payload);
+                break;
+        }
+    }
+    /**
+     * Build a detached, frozen snapshot from the current retention. Turn-scoped usage in the terminal
+     * event takes precedence over the latest retained turn usage. Final messages are joined with
+     * newlines in first-seen order. Failed results without native error details get TURN_FAILED.
+     * Session.retainEvent resolves the promise read by Turn.result with this snapshot for every native
+     * terminal status, then publishes the terminal event and ends the execution stream. If cloning or
+     * freezing throws, Session.emit rejects before the snapshot or event is delivered.
+     */
+    finish(payload) {
+        const items = [...this.items.values()].map(materializeItem);
+        const usage = payload.usage?.scope === 'turn' ? payload.usage : this.usage;
+        const common = { text: finalMessageText(items), items, ...(usage ? { usage } : {}) };
+        if (payload.status === 'failed') {
+            const error = payload.error ?? {
+                code: 'TURN_FAILED',
+                message: 'Turn failed',
+                retryable: false,
+                outcomeUnknown: false,
+            };
+            return immutable({ ...common, status: 'failed', error });
+        }
+        if (payload.status === 'interrupted') {
+            return immutable({ ...common, status: 'interrupted', ...(payload.error ? { error: payload.error } : {}) });
+        }
+        return immutable({ ...common, status: payload.status });
+    }
+    /**
+     * Reset retained items, completion markers, usage and bytes for reuse. Previously returned snapshots
+     * stay independent.
+     */
+    clear() {
+        this.items.clear();
+        this.completed.clear();
+        this.usage = undefined;
+        this.bytes = 0;
+    }
+    items = new Map();
+    completed = new Set();
+    bytes = 0;
+    usage;
+    /**
+     * Apply a delta for an item without a completion marker. Snapshot patches take the replacement
+     * path. Text deltas buffer only their matching field on a retained item. Retention failures
+     * propagate to accept.
+     */
+    acceptDelta({ itemId, kind, value, text }) {
+        const entry = this.items.get(itemId);
+        if (kind === 'patch') {
+            this.applySnapshotPatch(entry?.snapshot, value);
+            return;
+        }
+        if (!entry || text === undefined)
+            return;
+        const item = entry.snapshot;
+        if (item.type === 'agentMessage' && kind === 'text')
+            this.append(entry, 'text', item.text, text);
+        else if (item.type === 'reasoning' && kind === 'reasoningSummary')
+            this.append(entry, 'summary', item.summary, text);
+        else if (item.type === 'toolCall' && kind === 'output')
+            this.append(entry, 'output', item.output, text);
+    }
+    /**
+     * acceptDelta passes patch values here after Session.publish has projected them.
+     * Only a patch object with a type discriminator can replace a snapshot. SecretRedactor.deltaValue
+     * validates its shape upstream. Throw PROTOCOL_ERROR on a missing base item or a mismatch in ID
+     * or family. A valid patch replaces the snapshot and discards its text buffer.
+     */
+    applySnapshotPatch(current, value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value) || !('type' in value))
+            return;
+        if (!current || value.id !== current.id || value.type !== current.type) {
+            throw new HarnessSdkError('PROTOCOL_ERROR', 'Conflicting item snapshot');
+        }
+        this.retainSnapshot(value);
+    }
+    /**
+     * acceptDelta supplies a matching field and its snapshot value. Check the exact JSON byte change
+     * before updating the buffer or accounting. Throw RESULT_BUDGET_EXCEEDED without retaining the
+     * chunk on overflow. An empty chunk can establish an absent or non-string field. Preserve a
+     * buffered surrogate tail across empty chunks so a later chunk can complete the pair.
+     */
+    append(entry, field, previous, chunk) {
+        const pending = entry.bufferedText;
+        if (!chunk.length && (pending || typeof previous === 'string'))
+            return;
+        const serializedByteDelta = serializedTextAppendByteDelta({ field, previous, chunk, bufferedText: pending });
+        if (this.bytes + serializedByteDelta > this.maxBytes)
+            throw new HarnessSdkError('RESULT_BUDGET_EXCEEDED');
+        const bufferedText = pending ?? {
+            field,
+            chunks: [typeof previous === 'string' ? previous : ''],
+        };
+        bufferedText.chunks.push(chunk);
+        if (chunk.length)
+            bufferedText.lastCodeUnit = chunk.charCodeAt(chunk.length - 1);
+        entry.bufferedText = bufferedText;
+        entry.serializedBytes += serializedByteDelta;
+        this.bytes += serializedByteDelta;
+    }
+    /**
+     * accept and applySnapshotPatch store detached snapshots here. Check capacity and clone before
+     * mutation. Budget failure throws RESULT_BUDGET_EXCEEDED and serialization or clone failures
+     * propagate. Replacing an existing entry discards its provisional buffer while preserving its
+     * first-seen position for finish.
+     */
+    retainSnapshot(item) {
+        const size = Buffer.byteLength(JSON.stringify(item));
+        const previous = this.items.get(item.id);
+        const bytes = this.bytes - (previous?.serializedBytes ?? 0) + size;
+        if (bytes > this.maxBytes || (!previous && this.items.size >= this.maxItems))
+            throw new HarnessSdkError('RESULT_BUDGET_EXCEEDED');
+        this.items.set(item.id, { snapshot: structuredClone(item), serializedBytes: size });
+        this.bytes = bytes;
+    }
+}
+/**
+ * Return the JSON byte change that append uses to check capacity, including the structural cost of
+ * establishing a text field and any surrogate pair formed with the end of the existing text.
+ */
+function serializedTextAppendByteDelta({ field, previous, chunk, bufferedText }) {
+    const prefix = typeof previous === 'string' ? previous : '';
+    const lastCodeUnit = bufferedText ? bufferedText.lastCodeUnit : prefix.charCodeAt(prefix.length - 1);
+    const chunkContentBytes = Buffer.byteLength(JSON.stringify(chunk)) - 2; // Exclude string quotes.
+    const surrogatePairByteDelta = splitSurrogateByteAdjustment(lastCodeUnit, chunk);
+    let fieldStructureByteDelta = 0;
+    if (!bufferedText && typeof previous !== 'string') {
+        fieldStructureByteDelta = previous === undefined
+            ? Buffer.byteLength(JSON.stringify(field)) + 4 // Comma, colon and empty string quotes.
+            : 2 - Buffer.byteLength(JSON.stringify(previous)); // Replace the previous value with empty string quotes.
+    }
+    return chunkContentBytes + surrogatePairByteDelta + fieldStructureByteDelta;
+}
+/**
+ * ResultAccumulator.finish maps retained entries through this callback in first-seen item order.
+ * Overlay provisional text without consuming its buffer; finish still owns detaching/freezing the
+ * result, since entries without buffers return their retained snapshot directly.
+ */
+function materializeItem({ snapshot, bufferedText }) {
+    return bufferedText
+        ? { ...snapshot, [bufferedText.field]: bufferedText.chunks.join('') }
+        : snapshot;
+}
+/**
+ * ResultAccumulator.finish derives host-visible text from materialized items. Keep final messages in
+ * retained order, including empty messages and their separators; interim messages remain in items.
+ */
+function finalMessageText(items) {
+    return items
+        .filter((item) => item.type === 'agentMessage' && item.phase === 'final')
+        .map(item => item.text)
+        .join('\n');
+}
+/**
+ * Correct append accounting when a chunk joins a trailing high surrogate to a leading low surrogate.
+ * JSON replaces two isolated escapes (6 bytes each) with one UTF-8 pair (4 bytes); empty chunks and
+ * non-pair boundaries need no adjustment.
+ */
+function splitSurrogateByteAdjustment(previousCodeUnit, chunk) {
+    const endsWithHighSurrogate = previousCodeUnit !== undefined && previousCodeUnit >= 0xd800 && previousCodeUnit <= 0xdbff;
+    const firstCodeUnit = chunk.charCodeAt(0);
+    const startsWithLowSurrogate = firstCodeUnit >= 0xdc00 && firstCodeUnit <= 0xdfff;
+    return endsWithHighSurrogate && startsWithLowSurrogate ? 4 - 2 * 6 : 0;
+}

package/src/lifecycle/value.d.ts

@@ -0,0 +1,4 @@
+export { immutable } from "./immutable.js";
+export { inputBlocks } from "./input.js";
+export { positive } from "./limits.js";
+export { deferred } from "./deferred.js";

package/src/lifecycle/value.js

@@ -0,0 +1,5 @@
+// Compatibility re-exports for internal lifecycle helper imports.
+export { immutable } from "./immutable.js";
+export { inputBlocks } from "./input.js";
+export { positive } from "./limits.js";
+export { deferred } from "./deferred.js";

package/src/ports.d.ts

@@ -0,0 +1,224 @@
+import type { AhpEventPayload, AhpMethod, AhpRequestMap, AhpResultMap, Capabilities, HarnessError, InitializeParams, InitializeResult, InteractionRequested, InteractionResponse, JsonSchema, SessionBinding, SessionOpenParams } from '@anureo/protocol';
+import type { QueueLimits } from "./queue.js";
+/**
+ * Deliver an interaction answer or cancellation to the native peer. Adapters supply this callback to
+ * the sink's requestInteraction. InteractionRegistry.deliverResponse invokes it with an answer;
+ * cancelPending invokes it with null and a reason on expiry/cancellation/teardown.
+ * Session.requestInteraction also calls it directly when rejecting closed, unsupported or handler
+ * capacity admission. Resolve once native delivery or cancellation is confirmed by the adapter.
+ * Reject delivery failures and mark uncertain outcomes so the SDK can report them without retrying
+ * a response that might already have been accepted.
+ */
+export type NativeInteractionResponder = (response: InteractionResponse | null, reason?: string) => Promise<void>;
+/** Session.request and BackendSession.execute use these methods; Client handles initialize/session-open separately through HarnessAdapter. */
+export type SessionMethod = Exclude<AhpMethod, 'initialize' | 'session/open'>;
+/** Supply the execution and item identities for a native event. IDs in scope and payload must agree. */
+export interface EventScope {
+    /** Execution identity needed for item/usage events whose payload carries no turn ID. */
+    turnId?: string;
+    /** Optional item identity; must agree with an item payload's own ID. */
+    itemId?: string;
+}
+/**
+ * Publish events and settle interactions through the sink received by HarnessAdapter.openSession.
+ * OutputSession.open supplies adapter callbacks that route events through structured-output policy
+ * before delivering them to Session. Await publication calls to preserve source order. Report
+ * observation failures through fail and release native resources through the adapter's disposal.
+ */
+export interface SessionEventSink {
+    /**
+     * Project final JSON synchronously for privacy. Session supplies this hook to
+     * OutputSession.publishOutput, which revalidates the returned text against the schema.
+     * Projection or validation failure turns the native success into a failed terminal result.
+     */
+    projectOutput?(text: string): string;
+    /**
+     * Publish an association between a submission and its native execution. Successful publication
+     * can resolve Session.submit before the native receipt. Invalid or conflicting bindings fail
+     * publication. PiBackendSession.beginTurn awaits this before processing later turn events.
+     */
+    bindSubmission(submissionId: string, turnId: string): Promise<void>;
+    /**
+     * Admit a detached event for ordered processing. Await this call before sending a dependent event.
+     * Structured-output policy can hold events until a binding arrives. Admission can throw or reject.
+     * Queued processing failures reject and end observation.
+     */
+    emit(event: AhpEventPayload, scope?: EventScope): Promise<void>;
+    /** Attempt event admission without waiting. False reports immediate failure. True allows later processing failure to end observation. */
+    tryEmit(event: AhpEventPayload, scope?: EventScope): boolean;
+    /**
+     * Register a native request and the callback that delivers its answer or cancellation. Session
+     * publishes interaction/requested before scheduling a configured host handler. Manual answers
+     * arrive through Session.request. Resolve with the answer after delivery and settlement
+     * publication. Admission failures, cancellation and expiry reject. If native delivery and
+     * publication of its unknown outcome both fail, the pending answer can remain unresolved.
+     * Keep native callback resources available through settlement or adapter teardown.
+     */
+    requestInteraction(request: InteractionRequested, responder: NativeInteractionResponder): Promise<InteractionResponse>;
+    /**
+     * Report settlement already completed by the native peer. Session publishes the result without
+     * invoking the responder and rejects the pending requestInteraction, including for a responded
+     * outcome, because there is no answer value. Unknown or resolved IDs are ignored. A publication
+     * failure rejects this call.
+     */
+    resolveInteraction(result: AhpResultMap['interaction/respond']): Promise<void>;
+    /**
+     * Report observation loss. The first call on an open Session ends observation, cancels pending
+     * interactions and attempts backend cleanup. Session suppresses backend disposal rejection.
+     * Native execution stop remains unconfirmed.
+     */
+    fail(cause: unknown): Promise<void>;
+}
+/**
+ * Inspect the candidate decision returned by StructuredOutputToolDefinition.execute to native tool
+ * adapters. OutputSession.submitCandidate checks and retains accepted candidates. Acceptance is
+ * provisional: final privacy/schema validation occurs at terminal publication. Rejection carries
+ * safe retry/terminal policy; infrastructure failure can reject the callback promise instead.
+ */
+export type StructuredOutputToolResult = {
+    accepted: true;
+} | {
+    accepted: false;
+    error: HarnessError;
+};
+/**
+ * Present this tool to the native agent and invoke execute for candidate calls. OutputSession.prepareOutput
+ * passes the definition to a native StructuredOutputToolPort before input dispatch. The adapter
+ * consumes acceptance or safe failure. Each callback captures its submission, so a late call cannot
+ * satisfy a replacement input. Native tool registration/cleanup remains the adapter's responsibility.
+ */
+export interface StructuredOutputToolDefinition {
+    /** Native tool name supplied by the output wrapper; keep it stable when presenting the tool. */
+    name: string;
+    /** Model-facing instructions supplied by the output wrapper. */
+    description: string;
+    /** Candidate schema whose constraints the native tool presentation must preserve. */
+    schema: JsonSchema;
+    /** Native tool calls await candidate validation/retention; resolve a decision, or reject an infrastructure failure. Acceptance does not settle Turn.result. */
+    execute(value: unknown): Promise<StructuredOutputToolResult>;
+}
+/**
+ * Implement session-scoped native tool registration on a BackendSession. OutputSession.prepareOutput
+ * awaits installation before dispatch. OutputSession.completeTurn, reject and release disable the
+ * tool on completion, definite rejection or teardown. Finish changes before resolving.
+ */
+export interface StructuredOutputToolPort {
+    /**
+     * OutputSession replaces the tool or disables it with undefined. Resolve when native registration
+     * changes complete; setup rejection prevents input dispatch, while teardown rejection reports cleanup failure.
+     */
+    configure(tool?: StructuredOutputToolDefinition): Promise<void>;
+}
+/**
+ * Return an owned native session from HarnessAdapter.openSession. OutputSession.open adopts it; Client then
+ * attaches the wrapper to Session. Session.executeRequest awaits wrapper execute and
+ * Session.disposeBackend awaits wrapper disposal, which releases the native backend. Receipt promises
+ * and sink events can settle independently; adapters must preserve that distinction.
+ */
+export interface BackendSession {
+    /** Optional native tool registration used by OutputSession.prepareOutput when native outputSchema support is absent. */
+    readonly structuredOutputTool?: StructuredOutputToolPort;
+    /** Optional attachment snapshot; Session.attach restores its active execution observations after checking its binding. */
+    readonly state?: import('@anureo/protocol').SessionState;
+    /** Session.attach requires the requested session/adapter/configuration IDs, then adopts this binding's nativeRef. */
+    readonly binding: SessionBinding;
+    /** Session-specific capabilities adopted at attachment, after output projection; may differ from initialization capabilities. */
+    readonly capabilities: Capabilities;
+    /**
+     * OutputSession.execute invokes the native backend after policy setup and request validation.
+     * Resolve a native receipt/result or reject a safe failure with unknown-outcome metadata when
+     * acceptance is uncertain; neither wrapper nor Session automatically retries native dispatch.
+     */
+    execute<M extends SessionMethod>(method: M, params: AhpRequestMap[M]): Promise<AhpResultMap[M]>;
+    /** OutputSession.dispose awaits native handle release; implementations must be idempotent and reject cleanup failure without claiming execution stopped. */
+    dispose(): Promise<void>;
+}
+/**
+ * Implement native negotiation, session acquisition and client-wide cleanup for ClientOptions.adapter.
+ * Client invokes these operations through its structured-output wrapper. Release partially acquired
+ * native resources if setup fails. Be prepared to dispose after failed negotiation or while
+ * negotiation or a native open is still in flight, since a host can stop waiting first.
+ */
+export interface HarnessAdapter {
+    /**
+     * Select a bridge transport reachable by the native session, or return undefined to disable MCP
+     * fallback. OutputSession.open calls this synchronously when initialization lacks native
+     * outputSchema support. Opt in when native open can consume session-scoped MCP configuration.
+     * A throw rejects session setup.
+     */
+    outputBridgeTransport?(params: SessionOpenParams): 'http' | 'stdio' | undefined;
+    /** Client.initialize awaits negotiation through its wrapper, validates the result and stores capabilities; reject incompatible contracts/native setup failure. */
+    initialize(params: InitializeParams): Promise<InitializeResult>;
+    /**
+     * OutputSession.open supplies detached params and forwarding sink callbacks. Resolve an owned
+     * backend; callbacks may run before it resolves. Reject setup failure after releasing partially
+     * acquired native resources; the wrapper/Session release backends that arrive after caller teardown.
+     */
+    openSession(params: SessionOpenParams, sink: SessionEventSink): Promise<BackendSession>;
+    /** The output wrapper invokes this after session cleanup attempts; release client-wide native resources or reject release failure. */
+    dispose(): Promise<void>;
+}
+/**
+ * Hosts supply these hooks/budgets through ClientOptions.runtime. Client consumes ID/wait policy;
+ * Session consumes publication, interaction and privacy policy. Hooks can perform host-owned effects,
+ * but do not transfer native execution ownership. Callback failures propagate through their invoking
+ * operation; hosts must arrange any cleanup needed by their callbacks.
+ */
+export interface RuntimeOptions {
+    /**
+     * Generate nonempty, collision-free IDs synchronously; defaults to randomUUID. Client session helpers
+     * and Session request/stream allocation invoke this; allocation failures propagate to their callers.
+     */
+    createId?: () => string;
+    /**
+     * Supply public ISO timestamps for Session.publish. Defaults to new Date().toISOString().
+     * An invalid timestamp or throw fails publication. Interaction expiry uses wall-clock time.
+     */
+    now?: () => string;
+    /**
+     * Default wait for initialization, session requests, submission association and native interaction
+     * responders, in milliseconds. Defaults to 30_000. Per-call waits can override the operation
+     * wait. Turn.result has a separate 30-second default.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Default session attachment wait in milliseconds; defaults to 120_000. Per-call waits override it;
+     * abort/expiry does not abandon late backend cleanup.
+     */
+    openTimeoutMs?: number;
+    /**
+     * Bound actionable interaction lifetime in milliseconds. Defaults to 600_000.
+     * An earlier native expiry takes precedence.
+     */
+    interactionTimeoutMs?: number;
+    /**
+     * Separate caps for pending/settling interactions and live automatic handlers; each defaults to 32.
+     * Aborted host work retains its slot until settled.
+     */
+    maxPendingInteractions?: number;
+    /**
+     * Retained idempotency-outcome count per session; defaults to 1024.
+     * Session.admitRequestCapacity never evicts unsettled requests.
+     */
+    requestCacheSize?: number;
+    /**
+     * Set maxEvents, maxBytes and maxFrameBytes for session and structured-output event buffering.
+     * Their defaults are 2048 events, 16 MiB buffered and 8 MiB per frame. Observer queues use
+     * EventSubscriptionOptions.
+     */
+    queue?: QueueLimits;
+    /**
+     * Persist irreversible privacy metadata synchronously before accepting a new marked secret.
+     * Session registers this hook with SecretRedactor. SecretRedactor.rememberScalar invokes it before
+     * retaining a new marked value during InteractionRegistry.respond's pre-delivery check.
+     * A throw prevents native response delivery and leaves earlier persisted values in place.
+     */
+    onMarkedSecret?: (binding: Readonly<SessionBinding>, value: string) => void;
+    /**
+     * Apply host privacy metadata, including secrets retained across processes, to a native history page.
+     * Session.executeRequest invokes/awaits this after local history redaction, then validates/freezes
+     * the returned history/read page for its caller. Host I/O is allowed; throws/rejection fail the
+     * history request without SDK retries.
+     */
+    redactHistory?: (binding: Readonly<SessionBinding>, page: AhpResultMap["history/read"]) => AhpResultMap["history/read"] | Promise<AhpResultMap["history/read"]>;
+}

package/src/privacy/file-change-limits.d.ts

@@ -0,0 +1,20 @@
+import type { Item } from '@anureo/protocol';
+/**
+ * boundMaterial caps available materials across every file in one tool-call item. Existing
+ * unavailable metadata does not consume this count; excess available materials are omitted.
+ */
+export declare const FILE_CHANGE_MATERIAL_LIMIT = 50;
+/**
+ * Per-item UTF-8 text budget used by boundFileChangeItem.
+ * Canonical material reserves bytes before mirrors; JSON keys and item metadata are outside the cap.
+ */
+export declare const FILE_CHANGE_TEXT_LIMIT: number;
+/**
+ * Bound a tool call's file-change evidence without mutating the input. Items without fileChanges
+ * and non-tool items pass through by identity. Canonical material consumes the shared byte budget
+ * before input, output, raw and extensions, in that order. Overflow sets x-anureo/fileChangesTruncated.
+ * Only loss of canonical material downgrades a change's completeness and existing stat accuracy.
+ * SecretRedactor.toolCall calls this after redaction, so live events and history get the same
+ * retention rules. Callers own protocol validation and publication.
+ */
+export declare function boundFileChangeItem(item: Item): Item;

package/src/privacy/file-change-limits.js

@@ -0,0 +1,124 @@
+/**
+ * boundMaterial caps available materials across every file in one tool-call item. Existing
+ * unavailable metadata does not consume this count; excess available materials are omitted.
+ */
+export const FILE_CHANGE_MATERIAL_LIMIT = 50;
+/**
+ * Per-item UTF-8 text budget used by boundFileChangeItem.
+ * Canonical material reserves bytes before mirrors; JSON keys and item metadata are outside the cap.
+ */
+export const FILE_CHANGE_TEXT_LIMIT = 256 * 1024;
+/**
+ * Bound a tool call's file-change evidence without mutating the input. Items without fileChanges
+ * and non-tool items pass through by identity. Canonical material consumes the shared byte budget
+ * before input, output, raw and extensions, in that order. Overflow sets x-anureo/fileChangesTruncated.
+ * Only loss of canonical material downgrades a change's completeness and existing stat accuracy.
+ * SecretRedactor.toolCall calls this after redaction, so live events and history get the same
+ * retention rules. Callers own protocol validation and publication.
+ */
+export function boundFileChangeItem(item) {
+    if (item.type !== 'toolCall' || item.fileChanges === undefined)
+        return item;
+    const budget = {
+        bytes: FILE_CHANGE_TEXT_LIMIT,
+        materials: 0,
+        truncated: false,
+        encoder: new TextEncoder(),
+    };
+    const fileChanges = item.fileChanges.map(change => boundChange(change, budget));
+    const result = { ...item, fileChanges };
+    if (item.input !== undefined)
+        result.input = boundMirror(item.input, budget);
+    if (item.output !== undefined)
+        result.output = boundMirror(item.output, budget);
+    if (item.raw !== undefined)
+        result.raw = boundMirror(item.raw, budget);
+    if (item.extensions)
+        result.extensions = boundMirror(item.extensions, budget);
+    if (budget.truncated)
+        result.extensions = { ...result.extensions, 'x-anureo/fileChangesTruncated': true };
+    return result;
+}
+/**
+ * boundMaterial and boundMirror use this shared accounting rather than independent budgets. Return
+ * text within the remaining UTF-8 allowance and debit it. Overflow sets the sticky truncation flag
+ * and keeps only complete newline-terminated lines, dropping any split UTF-8 character with its line.
+ * Debit only the retained prefix, leaving unused bytes available to later material or mirrors.
+ */
+function takeText(budget, value) {
+    const encoded = budget.encoder.encode(value);
+    if (encoded.byteLength <= budget.bytes) {
+        budget.bytes -= encoded.byteLength;
+        return { value, complete: true };
+    }
+    const decoded = new TextDecoder().decode(encoded.subarray(0, budget.bytes));
+    const prefix = decoded.slice(0, decoded.lastIndexOf('\n') + 1);
+    budget.bytes -= budget.encoder.encode(prefix).byteLength;
+    budget.truncated = true;
+    return { value: prefix, complete: false };
+}
+/**
+ * boundChange calls this in source order with the item-wide budget. Return retained material and a
+ * partial flag, omitting material beyond the count cap. An empty retained patch becomes unavailable.
+ * Replacement sides must both fit to remain usable. Their consumed bytes stay reserved even when
+ * the replacement becomes unavailable metadata.
+ */
+function boundMaterial(material, budget) {
+    if (material.format === 'unavailable')
+        return { material, partial: false };
+    if (++budget.materials > FILE_CHANGE_MATERIAL_LIMIT) {
+        budget.truncated = true;
+        return { partial: true };
+    }
+    if (material.format === 'unified') {
+        const patch = takeText(budget, material.patch);
+        return {
+            material: patch.value ? { ...material, patch: patch.value } : { format: 'unavailable', reason: 'tooLarge' },
+            partial: !patch.complete,
+        };
+    }
+    const oldText = material.oldText === null ? null : takeText(budget, material.oldText);
+    const newText = takeText(budget, material.newText);
+    if ((oldText !== null && !oldText.complete) || !newText.complete) {
+        return { material: { format: 'unavailable', reason: 'tooLarge' }, partial: true };
+    }
+    return { material: { ...material, oldText: oldText === null ? null : oldText.value, newText: newText.value }, partial: false };
+}
+/**
+ * boundFileChangeItem maps canonical changes through this before traversing mirrors. Retain material
+ * in order and downgrade completeness/stat accuracy when a cap discards content; keep a metadata placeholder
+ * when all supplied material was omitted. Only the shared budget is mutated, never the source change.
+ */
+function boundChange(change, budget) {
+    let partial = false;
+    const materials = [];
+    for (const material of change.materials) {
+        const retained = boundMaterial(material, budget);
+        partial ||= retained.partial;
+        if (retained.material)
+            materials.push(retained.material);
+    }
+    if (!materials.length && change.materials.length)
+        materials.push({ format: 'unavailable', reason: 'tooLarge' });
+    const result = { ...change, materials };
+    if (partial) {
+        result.completeness = 'partial';
+        if (change.stats)
+            result.stats = { ...change.stats, accuracy: 'partial' };
+    }
+    return result;
+}
+/**
+ * boundFileChangeItem invokes this for input, output, raw and extensions after canonical material.
+ * Return recursively bounded JSON without changing keys or scalar types. String values consume the
+ * remaining budget in traversal order; only the shared budget is mutated.
+ */
+function boundMirror(value, budget) {
+    if (typeof value === 'string')
+        return takeText(budget, value).value;
+    if (Array.isArray(value))
+        return value.map(entry => boundMirror(entry, budget));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, boundMirror(child, budget)]));
+    return value;
+}