@anureo/sdk 0.0.0-stage → 0.3.0

package/src/privacy/secrets.d.ts

@@ -0,0 +1,205 @@
+import type { Capabilities, AhpEventPayload, AhpMethod, AhpResultMap, GoalState, HistoryPage, InteractionRequested, InteractionResponse, Item, JsonValue, SessionState } from "@anureo/protocol";
+/**
+ * Register explicitly marked answers before projecting content for public observation.
+ * This root-exported implementation helper is owned by Session, which installs registration in
+ * InteractionRegistry's pre-response callback and projects events and request results. Direct
+ * consumers own the same registration/publication order. Secrets and pending prefixes stay in
+ * memory; the optional synchronous hook owns persistence. No native resources are acquired.
+ */
+export declare class SecretRedactor {
+    private readonly onRemember?;
+    /**
+     * Create an empty in-memory registry with an optional synchronous persistence hook. Session
+     * forwards runtime.onMarkedSecret here; rememberScalar invokes it before accepting each new value.
+     * Construction only retains the hook. The host owns persistence and any effects its hook performs.
+     */
+    constructor(onRemember?: ((secret: string) => void) | undefined);
+    /**
+     * Register answers marked secret/writeOnly by the request before exposing or delivering them.
+     * Marked containers contribute their scalar descendants. Numbers and booleans register by string
+     * value, while empty strings, null and duplicates are ignored. At most 128 distinct values and
+     * 64 KiB of UTF-8 text are retained. Exceeding either cap throws a HarnessSdkError with code
+     * BACKPRESSURE_EXCEEDED. Hook exceptions also propagate, leaving earlier registrations intact.
+     * Schema traversal stops beyond depth 32, with the request schema at depth zero.
+     * Session installs this as InteractionRegistry's pre-response check. InteractionRegistry.respond
+     * invokes it after validation and rejects on failure before looking up a replay or starting native
+     * delivery. Direct consumers own validation and delivery.
+     */
+    rememberResponse(request: InteractionRequested, response: InteractionResponse): void;
+    /**
+     * Replace complete secret matches with [redacted], preferring the longest match at each position.
+     * Unmatched trailing prefixes are emitted without retaining stream state. Session.projectOutput
+     * and Session.projectSubmissionStatus use this before exposure. OutputSession.publishOutput
+     * revalidates JSON returned through projectOutput and converts schema failures into failed turns.
+     */
+    text(value: string): string;
+    /**
+     * Project an ordered text chunk, withholding a possible trailing secret prefix until the next chunk.
+     * Complete matches win even when a longer secret is incomplete. event scopes streams by turn/item
+     * and discards pending prefixes on item/completed, whose snapshot carries authoritative full text.
+     * Direct consumers must use distinct ordered keys; this method has no flush/reset operation, so
+     * they must discard the redactor when they no longer need its retained prefixes and secrets.
+     */
+    delta(stream: string, value: string): string;
+    /**
+     * Return recursively projected JSON without mutating the input. Marked numbers and booleans become
+     * the string [redacted]. If projected keys collide, the last entry in traversal order wins.
+     * Session.projectSubmissionStatus selects receipt and error content. Direct callers should also
+     * pass only content fields to preserve protocol identity.
+     */
+    json(value: JsonValue): JsonValue;
+    /**
+     * Project configuration annotations and values without modifying validation constraints or
+     * property names. Return the original value when no configuration is advertised. state uses this
+     * for session snapshots; the caller owns storing or publishing the result.
+     */
+    capabilities(value: Capabilities): Capabilities;
+    /**
+     * Return a new outer value with projected goal JSON and unchanged native goal metadata.
+     * state and result call this before exposing goal content; no session state is written here.
+     */
+    goal(value: GoalState): GoalState;
+    /**
+     * Project content-bearing state fields while preserving bindings, protocol enums and revisions; no
+     * session bookkeeping is changed. Session.snapshot calls this on reads; event and result use it
+     * for state/config observations. Session freezes reads and validates/stores request results;
+     * direct consumers retain responsibility for validation and publication.
+     */
+    state(value: SessionState): SessionState;
+    /**
+     * Project a validated configuration or goal result according to its method. Other results pass
+     * through by identity. Session.projectRequestResult routes history to history() and calls this
+     * for other projectable results. Session.executeRequest stores projected configuration or goal
+     * state and validates and freezes the returned result. Direct callers own validation and storage.
+     */
+    result<M extends AhpMethod>(method: M, value: AhpResultMap[M]): AhpResultMap[M];
+    /**
+     * Project validated item content without changing protocol identity or registering new secrets.
+     * Tool-call file changes additionally use the shared material/mirror budget. event uses this for
+     * snapshots and validated patches; history applies it to each native entry. Direct consumers
+     * must validate item shape first, as Session and deltaValue do for their respective input paths.
+     */
+    item(item: Item): Item;
+    /**
+     * Project public request content while preserving identifiers, answer keys and protocol alternatives.
+     * event calls this after Session.requestInteraction applies protocol publicInteraction; direct
+     * consumers must likewise apply protocol privacy rules first. If a privatePayload is supplied
+     * directly, this method projects its JSON content and retains the field. InteractionRegistry
+     * retains the native request for response validation and marked-field lookup.
+     */
+    interaction(request: InteractionRequested): InteractionRequested;
+    /**
+     * Project validated events in publication order, clearing an item's buffered prefix on completion.
+     * Supply turnId to isolate reused item IDs across turns. Omission uses an item-only stream key.
+     * Session.publish invokes this after lifecycle admission and before retaining/publishing results.
+     * An invalid Item-shaped patch throws ProtocolValidationError and rejects Session.emit, which
+     * starts observation teardown. Direct consumers own event validation, ordering and publication.
+     * Completed snapshots supply authoritative item content.
+     */
+    event(event: AhpEventPayload, turnId?: string): AhpEventPayload;
+    /**
+     * Project a prevalidated history page using live items' privacy/retention rules, preserving
+     * pagination and execution identities. The input must already be validated; no history is fetched
+     * here. Session.projectRequestResult calls this before executeRequest awaits the optional host
+     * redactHistory hook, validates and freezes the result; host-hook rejection fails that request.
+     */
+    history(page: HistoryPage): HistoryPage;
+    private readonly values;
+    private readonly streams;
+    private secretBytes;
+    /**
+     * rememberResponse and fromSchema call this before a response can be sent. Recursively retain marked
+     * scalar values within session budgets; invoke the host hook before accepting each new value.
+     * Capacity or hook failures throw to InteractionRegistry.respond before native delivery; values
+     * already accepted during the traversal remain registered, with no rollback of host effects.
+     */
+    private remember;
+    /**
+     * Accept a new nonempty scalar only after capacity checks and the synchronous persistence hook
+     * succeed. remember preserves traversal order, so a later failure never rolls back earlier values;
+     * a failed hook leaves this value unregistered and retryable.
+     */
+    private rememberScalar;
+    /**
+     * Resolve a reference beginning with #/ against the original request schema. Decode JSON Pointer
+     * escapes and follow object keys. A missing key or non-object intermediate yields undefined.
+     * fromSchema checks the returned node's shape before visiting it.
+     */
+    private resolveLocalReference;
+    /**
+     * rememberResponse calls this for elicitation/dynamicTool schemas; recursive branches pass marked
+     * values to remember. Collect marked values through bounded local schema traversal, including
+     * referenced and sibling rules; does not validate response values or fetch references. Visit
+     * references before siblings because registration order determines host-hook and budget failures.
+     * Stop beyond depth 32; registration failures propagate without undoing earlier registrations.
+     */
+    private fromSchema;
+    /**
+     * fromSchema calls this between reference and array/composition visits. Register declared
+     * properties before additional ones, sharing the next-depth context and propagating registration
+     * failures. Even a declared non-schema property excludes that key from additionalProperties.
+     */
+    private rememberObjectProperties;
+    /**
+     * fromSchema visits array elements in order under the same items schema and next-depth context.
+     * Tuple arrays and absent items rules contribute no registrations. Registration failures propagate.
+     */
+    private rememberArrayItems;
+    /**
+     * fromSchema visits composition branches after reference, object and array rules. Visit every
+     * schema branch in keyword and array order without selecting a validation match. Registration
+     * failures stop the remaining visits.
+     */
+    private rememberComposedSchemas;
+    /**
+     * text consumes the complete scan; delta stores a stream scan's pending prefix for the next chunk.
+     * Return longest complete matches as redactions. Stream mode withholds an unmatched trailing
+     * prefix so it cannot leak before the next chunk arrives; complete mode emits that prefix.
+     * This scan reads registered secrets but changes no stream or registration state.
+     */
+    private scan;
+    /**
+     * capabilities calls this for config-option schemas before exposing state. Project schema
+     * annotations/defaults recursively while preserving constraints and property names; privacy must not
+     * silently change validation rules. Object schemas are copied and boolean schemas pass through.
+     */
+    private schema;
+    /**
+     * item maps user-message content through this projection. Project content-bearing input block fields
+     * while preserving modality and protocol structure; return a detached outer block without loading
+     * files or fetching URLs. item returns the block in the public user message.
+     */
+    private input;
+    /**
+     * toolCall merges these fields into projected tool-call items before bounding file-change material.
+     * Project tool image paths/prompts only; image identity and other native metadata remain
+     * authoritative. Return only the image field (or no fields) without reading or modifying an image.
+     */
+    private toolImage;
+    /**
+     * toolCall maps fileChanges through this before boundFileChangeItem enforces retention.
+     * Project change paths and material text while preserving source metadata; the caller subsequently
+     * applies the shared retention budget. Return copied text material without applying patches or
+     * changing unavailable-material metadata.
+     */
+    private fileChange;
+    /**
+     * item delegates tool content projection here after extensions have been projected. Redact every
+     * content field before enforcing the shared file-change budget so accounting measures projected
+     * text. Return the bounded snapshot without changing native identity or source material.
+     */
+    private toolCall;
+    /**
+     * itemDelta calls this for JSON-valued payloads before Session retains or publishes the event.
+     * A patch object with type or fileChanges must pass Item validation before item projection.
+     * Item-shaped validation failures throw ProtocolValidationError. Other values receive ordinary
+     * JSON projection.
+     */
+    private deltaValue;
+    /**
+     * event projects delta text before validating/projecting an optional JSON value. A malformed patch
+     * throws after any prefix update, as publication fails through Session.emit; no buffered state is
+     * rolled back. Non-Item JSON still receives ordinary content projection.
+     */
+    private itemDelta;
+}