@anureo/sdk 0.2.0 → 0.3.0

package/src/lifecycle/interactions.js

@@ -0,0 +1,282 @@
+// Owns native interaction capacity, expiry, settlement and response replay.
+import { createHash } from "node:crypto";
+import { assertInteractionResponse } from "@anureo/protocol";
+import { HarnessSdkError, sdkError } from "../errors.js";
+import { waitForRequest } from "../request.js";
+/**
+ * Track native requests, settle their answers and retain bounded response replay state.
+ * Session uses this SDK implementation helper and supplies publication and privacy hooks.
+ * Direct consumers own those integrations and should await cancelAll with a teardown reason
+ * when releasing a session. The registry owns request expiry and native response wait timers.
+ */
+export class InteractionRegistry {
+    publish;
+    limits;
+    beforeResponse;
+    /**
+     * Configure settlement publication and synchronous pre-response checks without starting native
+     * work. Session supplies a publisher that aborts the host handler and awaits publication of
+     * interaction/resolved while observation is open. It also supplies SecretRedactor.rememberResponse
+     * to register secrets before delivery. respond runs the check for every validated attempt, including
+     * replays, and propagates a throw before delivery. Settlement awaits publication without a deadline.
+     */
+    constructor(publish, limits, beforeResponse) {
+        this.publish = publish;
+        this.limits = limits;
+        this.beforeResponse = beforeResponse;
+    }
+    /**
+     * Count requests that consume admission capacity in begin, including native delivery and
+     * cancellation in flight. Capacity becomes available when a request is marked resolved.
+     */
+    get pendingCount() {
+        return [...this.records.values()].filter((record) => record.state !== "resolved").length;
+    }
+    /**
+     * List detached copies of actionable requests for manual answering. Cloning failures throw
+     * without changing registry state. These copies retain native fields, so callers own projection
+     * before exposing them to observers.
+     */
+    pending() {
+        return [...this.records.values()]
+            .filter((record) => record.state === "pending")
+            .map((record) => structuredClone(record.request));
+    }
+    /**
+     * Register a unique unexpired request and an unrefed expiry timer. Duplicate IDs, exhausted
+     * capacity and invalid/elapsed lifetimes throw synchronously. A request-cloning failure rejects
+     * the returned promise after the expiry timer is scheduled. On success, the promise resolves
+     * with the answer after native delivery and result publication.
+     * Cancellation and peer settlement reject it after publication is attempted. If native delivery
+     * fails and publishing its unknown outcome also fails, this waiter stays unresolved; respond
+     * rejects the publication failure instead.
+     * Session.requestInteraction adopts this promise after publishing interaction/requested and
+     * scheduling any host handler. Adapters supply the responder through that sink method and own
+     * the native resources it uses.
+     */
+    begin(request, responder) {
+        if (this.records.has(request.interactionId))
+            throw new HarnessSdkError("INTERACTION_ALREADY_EXISTS");
+        if (this.pendingCount >= this.limits.maxPending)
+            throw new HarnessSdkError("BACKPRESSURE_EXCEEDED", "Pending interaction limit exceeded");
+        const ttl = interactionTtl(request, this.limits.timeoutMs);
+        if (!Number.isFinite(ttl) || ttl <= 0)
+            throw new HarnessSdkError("INTERACTION_EXPIRED");
+        this.evictOldestResolvedRecord();
+        const result = new Promise((resolve, reject) => {
+            // Expiry has no caller to receive cancellation failure. Settlement owns the request waiter.
+            const timer = setTimeout(() => { void this.cancel(request.interactionId, "timeout", "expired").catch(() => { }); }, ttl);
+            timer.unref?.();
+            this.records.set(request.interactionId, { request: structuredClone(request), responder, state: "pending", timer, resolve, reject });
+        });
+        // An adapter can still attach its await after the event publication; retain rejection observation meanwhile.
+        void result.catch(() => { });
+        return result;
+    }
+    /**
+     * Deliver an answer or replay the retained operation for the same request ID and serialized
+     * response. Validation and the synchronous pre-response hook run before any replay or delivery.
+     * Missing IDs reject with INTERACTION_EXPIRED. Conflicting answers to settling or resolved
+     * requests reject with INTERACTION_ALREADY_RESOLVED. The operation clears expiry, retains
+     * capacity during native delivery, and settles after the publication it initiates. If another
+     * settlement wins during delivery, late native success rejects with RESULT_UNKNOWN.
+     * Session.invokeRequest returns the promise for manual requests. Session.startInteractionHandler
+     * awaits it for automatic answers and attempts handler_failed cancellation on rejection while
+     * its signal remains active.
+     */
+    async respond(id, requestId, response) {
+        const record = this.records.get(id);
+        if (!record)
+            throw new HarnessSdkError("INTERACTION_EXPIRED");
+        assertInteractionResponse(record.request, response);
+        this.beforeResponse?.(record.request, response);
+        const fingerprint = responseFingerprint(response);
+        const replay = record.responseReplay;
+        if (replay && replay.requestId === requestId && replay.fingerprint === fingerprint) {
+            return replay.operation;
+        }
+        if (record.state !== "pending")
+            throw new HarnessSdkError("INTERACTION_ALREADY_RESOLVED");
+        // The responder can reenter synchronously. Mark the request settling before invoking it.
+        startSettlement(record);
+        const operation = this.deliverResponse({ id, record, response });
+        record.responseReplay = { requestId, fingerprint, operation };
+        return operation;
+    }
+    /**
+     * Cancel or expire an unresolved request, notifying native once when pending. The reason and
+     * outcome both default to "cancelled". Missing IDs reject with INTERACTION_EXPIRED. Resolved IDs
+     * and in-flight settlement with reason "cancelled" reject with INTERACTION_ALREADY_RESOLVED.
+     * Other reasons mark in-flight settlement unknown without another native call. Native notification
+     * failure or timeout also changes the outcome to unknown.
+     * Await publication, reject begin's waiter with INTERACTION_CANCELLED or RESULT_UNKNOWN, and
+     * return the outcome. If publication fails, the cancellation caller receives that failure and
+     * the original waiter still receives its lifecycle error. Session.invokeRequest returns this
+     * promise for manual cancellation. Session.startInteractionHandler and the expiry timer observe
+     * and suppress its rejection. cancelAll collects its outcome during teardown.
+     */
+    async cancel(id, reason = "cancelled", outcome = "cancelled") {
+        const record = this.records.get(id);
+        if (!record)
+            throw new HarnessSdkError("INTERACTION_EXPIRED");
+        if (record.state === "resolved")
+            throw new HarnessSdkError("INTERACTION_ALREADY_RESOLVED");
+        if (record.state === "pending")
+            return this.cancelPending({ id, record, reason, outcome });
+        if (reason === "cancelled")
+            throw new HarnessSdkError("INTERACTION_ALREADY_RESOLVED");
+        record.state = "resolved";
+        clearTimeout(record.timer);
+        const result = { interactionId: id, outcome: "unknown", reason };
+        await this.publishRejectedSettlement({ record, result, error: endedInFlight() });
+        return result;
+    }
+    /**
+     * Attempt concurrent cancellation of unresolved interactions, optionally limited to turnId; await
+     * every attempt and suppress individual failures. Session.fail, Session.finishClose and
+     * Session.dispose await this before releasing the backend. Use a reason other than "cancelled"
+     * to settle in-flight requests. The literal reason "connection_lost" requests an unknown outcome.
+     */
+    async cancelAll(reason, turnId) {
+        const ids = [...this.records]
+            .filter(([, record]) => record.state !== "resolved" && (turnId === undefined || record.request.turnId === turnId))
+            .map(([id]) => id);
+        const outcome = reason === "connection_lost" ? "unknown" : "cancelled";
+        await Promise.allSettled(ids.map((id) => this.cancel(id, reason, outcome)));
+    }
+    /**
+     * Publish native-side settlement without calling the responder; ignore unknown/resolved IDs
+     * and reject the waiter even for responded because no value is supplied. Clear expiry and release
+     * capacity before publication; publication failure rejects this call but still rejects the waiter.
+     * An unknown outcome rejects the waiter with RESULT_UNKNOWN; other outcomes use INTERACTION_ALREADY_RESOLVED.
+     * Session.resolveInteraction returns this promise to adapters reporting an already-settled native request.
+     */
+    async resolveExternally(result) {
+        const record = this.records.get(result.interactionId);
+        if (!record || record.state === "resolved")
+            return;
+        record.state = "resolved";
+        clearTimeout(record.timer);
+        await this.publishRejectedSettlement({
+            record, result,
+            error: new HarnessSdkError(result.outcome === "unknown" ? "RESULT_UNKNOWN" : "INTERACTION_ALREADY_RESOLVED", "Interaction was resolved by the native peer", false, result.outcome === "unknown"),
+        });
+    }
+    records = new Map();
+    /**
+     * begin calls after admission checks, before inserting a new request. At the replay bound, evict
+     * only the oldest resolved record so unresolved native work and its capacity remain accounted for.
+     * Duplicate checks run first: a retained ID cannot be reused by evicting its own replay guard.
+     */
+    evictOldestResolvedRecord() {
+        const atReplayLimit = this.records.size >= this.limits.maxPending + 1024;
+        if (!atReplayLimit)
+            return;
+        for (const [id, record] of this.records) {
+            if (record.state === "resolved") {
+                this.records.delete(id);
+                return;
+            }
+        }
+    }
+    /**
+     * respond caches this operation after admission. Bound native delivery without retrying it, then
+     * publish before resolving begin's waiter. If delivery succeeds after another settlement resolves
+     * the record, reject with RESULT_UNKNOWN without publishing again. Normalize delivery/publication
+     * failures for both callers. If publishing the unknown outcome itself fails, that failure escapes
+     * before the original waiter is rejected. Cancellation uses publishRejectedSettlement's finally instead.
+     */
+    async deliverResponse({ id, record, response }) {
+        try {
+            await this.notifyNative(record, response);
+            if (record.state === "resolved")
+                throw endedInFlight();
+            const result = { interactionId: id, outcome: "responded" };
+            // Release capacity before publication, but never release the waiter before publication finishes.
+            record.state = "resolved";
+            await this.publish(result);
+            record.resolve(response);
+            return result;
+        }
+        catch (cause) {
+            // This also catches publication failures, not just responder failures.
+            const error = sdkError(cause, "RESULT_UNKNOWN", true);
+            if (record.state !== "resolved") {
+                record.state = "resolved";
+                await this.publish({ interactionId: id, outcome: "unknown", reason: error.code });
+            }
+            record.reject(error);
+            throw error;
+        }
+    }
+    /**
+     * cancel calls only for an actionable record. Hold capacity and clear expiry before notifying native;
+     * timeout or notification failure changes the requested outcome to unknown. Release capacity before
+     * publication, then reject begin's waiter even if publication fails. Once started, this attempt
+     * still publishes after its native wait, even if teardown or peer settlement has already published.
+     */
+    async cancelPending({ id, record, reason, outcome }) {
+        startSettlement(record);
+        try {
+            await this.notifyNative(record, null, reason);
+        }
+        catch {
+            outcome = "unknown";
+        }
+        record.state = "resolved";
+        const result = { interactionId: id, outcome, reason };
+        const outcomeUnknown = outcome === "unknown";
+        await this.publishRejectedSettlement({
+            record, result,
+            error: new HarnessSdkError(outcomeUnknown ? "RESULT_UNKNOWN" : "INTERACTION_CANCELLED", "Interaction is no longer actionable", false, outcomeUnknown),
+        });
+        return result;
+    }
+    /**
+     * Wait for publication before rejecting begin's waiter with its lifecycle error. A publication
+     * failure still reaches cancel, cancelPending or resolveExternally. Those callers clear expiry
+     * and release capacity before entering this step.
+     */
+    async publishRejectedSettlement({ record, result, error }) {
+        try {
+            await this.publish(result);
+        }
+        finally {
+            record.reject(error);
+        }
+    }
+    /**
+     * Bound one invocation of the adapter's registered callback. deliverResponse supplies the answer
+     * and cancelPending supplies null and a reason. Both await and classify native errors or timeout.
+     * A timeout ends the registry's wait and keeps observing late rejection. The adapter still owns
+     * completion and native resource cleanup.
+     */
+    notifyNative(record, ...args) {
+        return waitForRequest(() => record.responder(...args), { timeoutMs: this.limits.responseTimeoutMs ?? 30_000 });
+    }
+}
+/** Hold admission capacity and clear expiry before respond or cancelPending invokes the adapter. */
+function startSettlement(record) {
+    record.state = "settling";
+    clearTimeout(record.timer);
+}
+/** Share the unknown-outcome error between in-flight teardown and a superseded response delivery. */
+function endedInFlight() {
+    return new HarnessSdkError("RESULT_UNKNOWN", "Interaction ended while response was in flight", false, true);
+}
+/**
+ * InteractionRegistry.begin uses the returned duration before allocating its expiry timer. Clamp a
+ * nonempty request expiry to the configured interaction lifetime; omitted/empty expiry uses the full
+ * lifetime. begin rejects a non-finite or non-positive result before allocating its timer.
+ */
+function interactionTtl(request, timeoutMs) {
+    return request.expiresAt ? Math.min(timeoutMs, new Date(request.expiresAt).getTime() - Date.now()) : timeoutMs;
+}
+/**
+ * InteractionRegistry.respond stores and compares this fingerprint before deciding whether to replay
+ * the response promise. Hash the serialized payload for replay detection; the request ID alone
+ * cannot distinguish conflicting retries.
+ */
+function responseFingerprint(response) {
+    return createHash("sha256").update(JSON.stringify(response)).digest("hex");
+}

package/src/lifecycle/limits.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate the selected retention budget as a positive safe integer, using the caller's fallback
+ * for an omitted value. Throw INVALID_PARAMS on failure. assertClientOptions checks configured
+ * limits at construction. Session.context, getOrCreateSubmission and retainEvent use the returned
+ * budget for allocation or accounting in units chosen at each call site.
+ */
+export declare function positive(value: number | undefined, fallback: number): number;

package/src/lifecycle/limits.js

@@ -0,0 +1,13 @@
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Validate the selected retention budget as a positive safe integer, using the caller's fallback
+ * for an omitted value. Throw INVALID_PARAMS on failure. assertClientOptions checks configured
+ * limits at construction. Session.context, getOrCreateSubmission and retainEvent use the returned
+ * budget for allocation or accounting in units chosen at each call site.
+ */
+export function positive(value, fallback) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result <= 0)
+        throw new HarnessSdkError('INVALID_PARAMS');
+    return result;
+}

package/src/lifecycle/result.d.ts

@@ -0,0 +1,77 @@
+import type { AhpEvent } from '@anureo/protocol';
+import type { TurnResult } from "../types.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 declare class ResultAccumulator {
+    private readonly maxBytes;
+    private readonly 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: number, maxItems: number);
+    /**
+     * 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(): number;
+    /**
+     * 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: AhpEvent): void;
+    /**
+     * 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: Extract<AhpEvent, {
+        type: 'turn/completed';
+    }>['payload']): TurnResult;
+    /**
+     * Reset retained items, completion markers, usage and bytes for reuse. Previously returned snapshots
+     * stay independent.
+     */
+    clear(): void;
+    private readonly items;
+    private readonly completed;
+    private bytes;
+    private 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.
+     */
+    private acceptDelta;
+    /**
+     * 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.
+     */
+    private applySnapshotPatch;
+    /**
+     * 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.
+     */
+    private append;
+    /**
+     * 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.
+     */
+    private retainSnapshot;
+}

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";