clinkx 0.3.0 → 1.0.0

package/dist/elaris/client.js

@@ -0,0 +1,825 @@
+import { AgentSessionArtifactsPageSchema, AgentSessionCancelResponseSchema, AgentSessionCleanupResponseSchema, AgentSessionLogsPageSchema, AgentSessionMessageResponseSchema, AgentSessionRawArtifactMetadataSchema, AgentSessionResultContentSchema, AgentSessionResultMetadataSchema, AgentSessionStatusResponseSchema, AgentSessionURLResponseSchema, } from "./types.js";
+import { CancellationError, InvalidParamsError } from "../errors.js";
+import { MAX_AGGREGATE_BYTES, MAX_PAGES, MAX_RESPONSE_BYTES, MAX_TEXT_CHARS, MAX_TOTAL_ITEMS, PAGE_LIMIT, POLL_MAX_MS, POLL_MIN_MS, } from "./config.js";
+import { detectCredentials, redact, redactPreservingLocators, redactPreservingLocatorsWithMetadata, redactWithMetadata, scrubOwnCredentials, } from "./redact.js";
+const AGENT_SESSIONS_PATH = "/api/v1/agent-sessions";
+const MAX_RAW_BODY_BYTES_FOR_BASE64 = Math.floor((MAX_RESPONSE_BYTES - 4096) * 3 / 4);
+export class ElarisHttpError extends Error {
+    status;
+    payload;
+    rawPayload;
+    retryAfterMs;
+    retryClass;
+    constructor(status, payload, rawPayload, retryAfterMs, retryClass) {
+        super(`Elaris HTTP request failed with status ${status}`);
+        this.status = status;
+        this.payload = payload;
+        this.rawPayload = rawPayload;
+        this.retryAfterMs = retryAfterMs;
+        this.retryClass = retryClass;
+        this.name = "ElarisHttpError";
+    }
+}
+export function isElarisHttpError(err) {
+    return err instanceof ElarisHttpError;
+}
+export class ElarisClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async createSession(request, options = {}) {
+        return this.requestJson(AgentSessionURLResponseSchema, {
+            method: "POST",
+            path: AGENT_SESSIONS_PATH,
+            body: request,
+            signal: options.signal,
+            expectedStatus: 202,
+        }, true);
+    }
+    async postMessage(sessionId, request, options = {}) {
+        return this.requestJson(AgentSessionMessageResponseSchema, {
+            method: "POST",
+            path: `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/messages`,
+            body: request,
+            signal: options.signal,
+            expectedStatus: 202,
+        }, true);
+    }
+    async getStatusBySessionId(sessionId, options = {}) {
+        return this.requestJson(AgentSessionStatusResponseSchema, {
+            method: "GET",
+            path: `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}`,
+            signal: options.signal,
+            expectedStatus: 200,
+        }, true);
+    }
+    async getStatusByHandle(statusUrl, options = {}) {
+        const resolved = resolveHandle(this.options.baseUrl, statusUrl);
+        return this.requestJson(AgentSessionStatusResponseSchema, {
+            method: "GET",
+            path: resolved.path,
+            signal: options.signal,
+            expectedStatus: 200,
+        }, true);
+    }
+    async getResult(sessionId, options = {}) {
+        const value = await this.requestJsonRecord({
+            method: "GET",
+            path: `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/result`,
+            signal: options.signal,
+            expectedStatus: 200,
+        });
+        return parseRedactedDeepCounted(AgentSessionResultMetadataSchema, value);
+    }
+    async getResultContent(sessionId, options = {}) {
+        const response = await this.fetchRaw({
+            method: "GET",
+            path: `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/result/content`,
+            signal: options.signal,
+            expectedStatus: 200,
+            responseCapBytes: MAX_RESPONSE_BYTES,
+        });
+        const text = decodeUtf8Lossy(response.body.bytes);
+        const { value: redacted, redaction_count } = redactWithMetadata({
+            text,
+            content_type: response.response.headers.get("content-type"),
+            bytes_returned: response.body.bytes.length,
+            result_bytes: parseNullablePositiveInt(response.response.headers.get("content-length")),
+            truncated: response.body.tooLarge,
+            local_response_too_large: response.body.tooLarge ? response.body.tooLargeReason : undefined,
+        });
+        return AgentSessionResultContentSchema.parse(attachRedactionCount(redacted, redaction_count));
+    }
+    async getLogsPage(sessionId, options = {}) {
+        const page = await this.requestJsonRecord({
+            method: "GET",
+            path: withQuery(`${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/logs`, {
+                cursor: options.cursor ?? "0",
+                limit: String(normalizePageLimit(options.limit)),
+            }),
+            signal: options.signal,
+            expectedStatus: 200,
+        });
+        const normalized = normalizeLogsPage(page);
+        return parseRedactedDeepCounted(AgentSessionLogsPageSchema, normalized);
+    }
+    async getAllLogs(sessionId, options = {}) {
+        return this.collectPages({
+            firstCursor: "0",
+            fetchPage: (cursor) => this.getLogsPage(sessionId, { ...options, cursor, limit: normalizePageLimit(options.limit) }),
+            getItems: (page) => readItems(page),
+            getNextCursor: (page) => readNextCursor(page),
+            getRedactionCount: (page) => readPageRedactionCount(page),
+            makePage: (items, lastPage, metadata, redactionTotal) => parseAggregatedRedactedPage(AgentSessionLogsPageSchema, {
+                ...lastPage,
+                items,
+                next_cursor: metadata.resume_cursor,
+                ...metadata,
+            }, redactionTotal),
+        });
+    }
+    async getArtifactsPage(sessionId, options = {}) {
+        const value = await this.requestJsonRecord({
+            method: "GET",
+            path: withQuery(`${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/artifacts`, {
+                cursor: options.cursor ?? "0",
+                limit: String(normalizePageLimit(options.limit)),
+            }),
+            signal: options.signal,
+            expectedStatus: 200,
+        });
+        return parseRedactedDeepCounted(AgentSessionArtifactsPageSchema, value);
+    }
+    async getAllArtifacts(sessionId, options = {}) {
+        return this.collectPages({
+            firstCursor: "0",
+            fetchPage: (cursor) => this.getArtifactsPage(sessionId, { ...options, cursor, limit: normalizePageLimit(options.limit) }),
+            getItems: (page) => readItems(page),
+            getNextCursor: (page) => readNextCursor(page),
+            getRedactionCount: (page) => readPageRedactionCount(page),
+            makePage: (items, lastPage, metadata, redactionTotal) => parseAggregatedRedactedPage(AgentSessionArtifactsPageSchema, {
+                ...lastPage,
+                items,
+                next_cursor: metadata.resume_cursor,
+                ...metadata,
+            }, redactionTotal),
+        });
+    }
+    async getArtifactRaw(sessionId, filePath, options = {}) {
+        const artifactPath = buildArtifactRawPath(sessionId, filePath);
+        const headers = {};
+        if (options.range)
+            headers["Range"] = formatRange(options.range);
+        const response = await this.fetchRaw({
+            method: "GET",
+            path: artifactPath,
+            signal: options.signal,
+            headers,
+            expectedStatus: [200, 206],
+            responseCapBytes: MAX_RESPONSE_BYTES,
+        });
+        const contentType = response.response.headers.get("content-type");
+        const base = {
+            status_code: response.response.status,
+            content_type: contentType,
+            content_length: parseNullablePositiveInt(response.response.headers.get("content-length")),
+            content_range: response.response.headers.get("content-range"),
+            accept_ranges: response.response.headers.get("accept-ranges"),
+            bytes_returned: response.body.bytes.length,
+            truncated: response.body.tooLarge,
+            local_response_too_large: response.body.tooLarge ? response.body.tooLargeReason : undefined,
+            range_guidance: response.body.tooLarge ? "Retry with a smaller Range header." : undefined,
+        };
+        const serialized = serializeRawArtifact(base, response.body.bytes);
+        return AgentSessionRawArtifactMetadataSchema.parse(scrubRawArtifactFields(serialized));
+    }
+    async cancel(sessionId, options = {}) {
+        return this.requestJson(AgentSessionCancelResponseSchema, {
+            method: "POST",
+            path: `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/cancel`,
+            signal: options.signal,
+            expectedStatus: 200,
+        }, true);
+    }
+    async cleanup(sessionId, options = {}) {
+        return this.requestJson(AgentSessionCleanupResponseSchema, {
+            method: "DELETE",
+            path: `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}`,
+            signal: options.signal,
+            expectedStatus: 200,
+        }, true);
+    }
+    async healthProbe(options = {}) {
+        if (!this.options.apiKey.trim()) {
+            return {
+                ok: false,
+                key_present: false,
+                router: "not_checked",
+                detail: "Elaris API key is not configured.",
+            };
+        }
+        try {
+            const probeId = "00000000-0000-0000-0000-000000000000";
+            const probe = await this.fetchRaw({
+                method: "GET",
+                path: `${AGENT_SESSIONS_PATH}/${probeId}`,
+                signal: options.signal,
+                expectedStatus: [200, 401, 403, 404],
+                responseCapBytes: MAX_RESPONSE_BYTES,
+            });
+            const status = probe.response.status;
+            if (status === 401) {
+                return redact({
+                    ok: false,
+                    key_present: true,
+                    router: "auth_failed",
+                    detail: "Elaris rejected the API key (HTTP 401).",
+                });
+            }
+            if (status === 403) {
+                return redact({
+                    ok: false,
+                    key_present: true,
+                    router: "insufficient_scope",
+                    detail: "Elaris API key lacks the required scope (HTTP 403).",
+                });
+            }
+            // 200 or a nil-UUID 404 both mean the router is reachable and the key authenticates.
+            return { ok: true, key_present: true, router: "reachable", status_code: status };
+        }
+        catch (err) {
+            const retry = err instanceof ElarisHttpError ? {
+                retry_after_ms: err.retryAfterMs,
+                retry_class: err.retryClass,
+            } : {};
+            return redact({
+                ok: false,
+                key_present: true,
+                router: "indeterminate",
+                detail: err instanceof Error ? err.message : "Unknown Elaris health probe failure",
+                ...retry,
+            });
+        }
+    }
+    async requestJson(schema, config, deep = false) {
+        const value = await this.requestJsonRecord(config);
+        return deep ? parseRedactedDeep(schema, value) : parseRedacted(schema, value);
+    }
+    async requestJsonRecord(config) {
+        const response = await this.fetchRaw({
+            ...config,
+            responseCapBytes: config.responseCapBytes ?? MAX_RESPONSE_BYTES,
+        });
+        if (response.body.tooLarge) {
+            const localMarker = {
+                error: "local_response_too_large",
+                detail: response.body.tooLargeReason,
+            };
+            throw new ElarisHttpError(response.response.status, localMarker, localMarker);
+        }
+        const text = decodeUtf8Lossy(response.body.bytes);
+        try {
+            const parsed = text ? JSON.parse(text) : {};
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch (err) {
+            throw new Error("Elaris returned invalid JSON");
+        }
+        throw new Error("Elaris returned a non-object JSON response");
+    }
+    async fetchRaw(config) {
+        const url = new URL(config.path, this.options.baseUrl);
+        const controller = new AbortController();
+        const signals = [controller.signal, AbortSignal.timeout(this.options.requestTimeoutMs)];
+        if (config.signal)
+            signals.push(config.signal);
+        const signal = AbortSignal.any(signals);
+        const headers = this.buildHeaders(config.headers, config.body !== undefined, config.includeAuth ?? true);
+        const init = {
+            method: config.method,
+            headers,
+            signal,
+        };
+        if (config.body !== undefined)
+            init.body = JSON.stringify(config.body);
+        const response = await this.options.fetch(url, init);
+        const expected = Array.isArray(config.expectedStatus)
+            ? config.expectedStatus
+            : [config.expectedStatus ?? 200];
+        const body = await readBoundedBody(response, config.responseCapBytes ?? MAX_RESPONSE_BYTES, () => controller.abort());
+        if (!expected.includes(response.status)) {
+            const retry = parseRetryAfter(response.headers.get("retry-after"));
+            const parsedError = parseErrorPayload(body);
+            throw new ElarisHttpError(response.status, parsedError.payload, parsedError.rawPayload, retry?.retry_after_ms, retry?.retry_class);
+        }
+        return { response, body };
+    }
+    buildHeaders(extra, hasBody, includeAuth) {
+        const headers = new Headers(extra);
+        headers.set("Accept", "application/json");
+        if (hasBody)
+            headers.set("Content-Type", "application/json");
+        if (includeAuth && this.options.apiKey.trim()) {
+            headers.set("Authorization", `Bearer ${this.options.apiKey}`);
+        }
+        return headers;
+    }
+    async collectPages(options) {
+        const items = [];
+        const seenCursors = new Set();
+        let cursor = options.firstCursor;
+        let lastPage = null;
+        let bytesReturned = 0;
+        let pagesFetched = 0;
+        // Authoritative aggregate: sum each fetched page's OWN per-page redaction_count.
+        // Re-redacting already-scrubbed assembled items finds ~0, so this running total
+        // is the true count that overrides the near-zero recomputation in makePage.
+        let redactionTotal = 0;
+        while (cursor !== null) {
+            if (seenCursors.has(cursor)) {
+                return options.makePage(items, lastPage ?? emptyPage(), {
+                    truncated: true,
+                    truncation_reason: "repeated_cursor",
+                    resume_cursor: cursor,
+                    items_returned: items.length,
+                    bytes_returned: bytesReturned,
+                    pages_fetched: pagesFetched,
+                }, redactionTotal);
+            }
+            if (pagesFetched >= MAX_PAGES) {
+                return options.makePage(items, lastPage ?? emptyPage(), {
+                    truncated: true,
+                    truncation_reason: "max_pages",
+                    resume_cursor: cursor,
+                    items_returned: items.length,
+                    bytes_returned: bytesReturned,
+                    pages_fetched: pagesFetched,
+                }, redactionTotal);
+            }
+            seenCursors.add(cursor);
+            let page;
+            try {
+                page = await options.fetchPage(cursor);
+            }
+            catch (err) {
+                if (err instanceof ElarisHttpError && err.status === 410 && items.length > 0) {
+                    return options.makePage(items, lastPage ?? emptyPage(), {
+                        truncated: true,
+                        truncation_reason: "resource_gone_partial",
+                        resume_cursor: cursor,
+                        items_returned: items.length,
+                        bytes_returned: bytesReturned,
+                        pages_fetched: pagesFetched,
+                    }, redactionTotal);
+                }
+                throw err;
+            }
+            lastPage = page;
+            pagesFetched += 1;
+            redactionTotal += options.getRedactionCount(page);
+            for (const item of options.getItems(page)) {
+                const itemBytes = JSON.stringify(item).length;
+                if (items.length + 1 > MAX_TOTAL_ITEMS) {
+                    return options.makePage(items, page, capMetadata("max_total_items", cursor, items.length, bytesReturned, pagesFetched), redactionTotal);
+                }
+                if (bytesReturned + itemBytes > MAX_AGGREGATE_BYTES) {
+                    return options.makePage(items, page, capMetadata("max_aggregate_bytes", cursor, items.length, bytesReturned, pagesFetched), redactionTotal);
+                }
+                items.push(item);
+                bytesReturned += itemBytes;
+            }
+            const next = options.getNextCursor(page);
+            if (next === cursor) {
+                return options.makePage(items, page, capMetadata("non_advancing_cursor", next, items.length, bytesReturned, pagesFetched), redactionTotal);
+            }
+            cursor = next;
+        }
+        return options.makePage(items, lastPage ?? emptyPage(), {
+            truncated: false,
+            resume_cursor: null,
+            items_returned: items.length,
+            bytes_returned: bytesReturned,
+            pages_fetched: pagesFetched,
+        }, redactionTotal);
+    }
+}
+export async function waitForNextElarisPoll(options) {
+    const now = options.nowMs ?? (() => Date.now());
+    const random = options.random ?? Math.random;
+    const sleep = options.sleep ?? defaultSleep;
+    const base = clamp(options.pollIntervalMs ?? POLL_MIN_MS, POLL_MIN_MS, POLL_MAX_MS);
+    const jittered = Math.floor(base * (0.8 + random() * 0.4));
+    const requested = options.retryAfterMs !== undefined && options.retryAfterMs > POLL_MAX_MS
+        ? options.retryAfterMs
+        : Math.max(jittered, Math.min(options.retryAfterMs ?? 0, POLL_MAX_MS));
+    const delayMs = clamp(requested, POLL_MIN_MS, Math.max(POLL_MAX_MS, requested));
+    if (now() + delayMs > options.deadlineMs)
+        return false;
+    await sleep(delayMs, options.signal);
+    return true;
+}
+export function resolveHandle(baseUrl, rawPath) {
+    if (!rawPath || rawPath.includes("\0")) {
+        throw new InvalidParamsError("Elaris handle path must be non-empty");
+    }
+    if (rawPath.includes("?") || rawPath.includes("#")) {
+        throw new InvalidParamsError("Elaris handle path must not include a query or fragment");
+    }
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(rawPath) || rawPath.startsWith("//")) {
+        throw new InvalidParamsError("Elaris handle path must not be an absolute URL");
+    }
+    const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+    if (!path.startsWith(`${AGENT_SESSIONS_PATH}/`)) {
+        throw new InvalidParamsError("Elaris handle path must be rooted under /api/v1/agent-sessions/");
+    }
+    for (const segment of path.split("/")) {
+        const decoded = safeDecodeURIComponent(segment);
+        if (decoded === "..") {
+            throw new InvalidParamsError("Elaris handle path must not contain traversal");
+        }
+    }
+    return { path: rawPath, url: new URL(path, baseUrl) };
+}
+function parseRedacted(schema, value) {
+    const parsed = schema.parse(value);
+    if (typeof parsed === "object" && parsed !== null && "raw" in parsed) {
+        const withRaw = parsed;
+        if (withRaw.raw !== undefined)
+            withRaw.raw = redact(withRaw.raw);
+    }
+    return parsed;
+}
+/**
+ * Uniform success-path redaction for ALL JSON responses — both read responses
+ * (result metadata, log/artifact pages including their `items`) and
+ * control-plane responses (create/status/message/cancel/cleanup, whose
+ * schema-typed free-text fields like `status_reason` and nested `error.detail`
+ * the provider may echo secrets into). The WHOLE payload is deep-redacted BEFORE
+ * schema parsing — like getResultContent — so provider-echoed secrets are
+ * scrubbed, while control-plane locators (cursors, URLs, ids, ranges) pass
+ * through verbatim.
+ */
+function parseRedactedDeep(schema, value) {
+    return schema.parse(redactPreservingLocators(value));
+}
+/**
+ * Reserved envelope control keys that are OWNED by ClinkX, never legitimate
+ * provider payload. A provider MUST NOT be able to inject either — see
+ * {@link stripReservedRedactionKeys}.
+ */
+const RESERVED_REDACTION_KEYS = new Set(["redaction_count", "redacted"]);
+/**
+ * Deep-strip the reserved envelope control keys (`redaction_count`, `redacted`)
+ * from a PROVIDER-ORIGINATED value at EVERY depth (walking objects and arrays).
+ * These fields are stamped locally by ClinkX and are never legitimate provider
+ * data, so removing them anywhere is safe.
+ *
+ * This MUST run BEFORE the redaction/count pass on the read paths. Doing so
+ * closes two spoofs:
+ *   A) A provider-supplied credential-SHAPED `redaction_count` string (e.g.
+ *      `"Authorization: Bearer …"`) can no longer be matched by the redaction
+ *      walk and inflate the locally-computed count (which also feeds the
+ *      `fetch_all` aggregate via {@link readPageRedactionCount}).
+ *   B) No nested provider `redaction_count`/`redacted` (in `items[*]`, `extra`,
+ *      etc.) survives into the parsed result — including values that would
+ *      otherwise land in a schema `.raw` bucket, because the strip happens
+ *      before `withRaw` buckets unknown keys.
+ */
+function stripReservedRedactionKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => stripReservedRedactionKeys(entry));
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (RESERVED_REDACTION_KEYS.has(key))
+                continue;
+            out[key] = stripReservedRedactionKeys(entry);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Read-path variant of {@link parseRedactedDeep}: deep-redacts (preserving
+ * locators) AND surfaces how many redactions fired as a first-class
+ * `redaction_count` field so it can bubble to the tool envelope. Counting rides
+ * the single existing walk. A zero count is omitted to keep clean responses
+ * byte-identical to before. Used only for read responses (result metadata, log
+ * and artifact pages); control-plane responses keep {@link parseRedactedDeep}.
+ *
+ * Reserved control keys are deep-stripped from the provider value FIRST, so a
+ * spoofed/nested `redaction_count`/`redacted` can neither inflate the local
+ * count nor survive into the parsed result.
+ */
+function parseRedactedDeepCounted(schema, value) {
+    const sanitized = stripReservedRedactionKeys(value);
+    const { value: redacted, redaction_count } = redactPreservingLocatorsWithMetadata(sanitized);
+    return schema.parse(attachRedactionCount(redacted, redaction_count));
+}
+/**
+ * fetch_all aggregate variant: deep-redacts the ASSEMBLED page (defensively —
+ * the per-page items are already scrubbed) but takes `redactionTotal` (the sum of
+ * every fetched page's own per-page `redaction_count`) as the AUTHORITATIVE count.
+ * Re-scanning already-redacted items would find ~0 and lose the earlier pages'
+ * real redactions, so we do NOT recount here; {@link attachRedactionCount} strips
+ * any carried-over per-page/provider count and stamps the aggregate (omitted at 0).
+ * Reserved control keys are deep-stripped from the assembled value FIRST (covering
+ * the `...lastPage`/`...metadata` spread) so no nested provider `redaction_count`/
+ * `redacted` survives, and the authoritative aggregate is the only stamped count.
+ */
+function parseAggregatedRedactedPage(schema, value, redactionTotal) {
+    const sanitized = stripReservedRedactionKeys(value);
+    return schema.parse(attachRedactionCount(redactPreservingLocators(sanitized), redactionTotal));
+}
+/**
+ * Attach the LOCALLY-COMPUTED `redaction_count` to a plain object before schema
+ * parsing, authoritatively. Any incoming `redaction_count` (e.g. a provider-echoed
+ * value) is ALWAYS stripped first so a malicious or buggy upstream cannot spoof
+ * `redacted:true` or an arbitrary count; the local `count` is then attached only
+ * when it is > 0 (omitted at 0 so clean responses stay byte-identical). A
+ * non-object/array/null value is returned untouched.
+ */
+function attachRedactionCount(value, count) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return value;
+    const rest = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (key === "redaction_count")
+            continue;
+        rest[key] = entry;
+    }
+    if (count > 0)
+        rest["redaction_count"] = count;
+    return rest;
+}
+/**
+ * Per-field scrub for the explicit raw-inspection path (`artifact_raw`).
+ *
+ * FAIL-CLOSED: the shared high-confidence detector runs over the emitted inline
+ * `text` AND over the DECODED `data_base64` bytes. If ANY credential is detected
+ * the payload body is WITHHELD entirely — `text`/`data_base64` are dropped and a
+ * `withheld: "credential_detected"` marker plus `redaction_count` is surfaced
+ * (both are now FIRST-CLASS fields declared on
+ * `AgentSessionRawArtifactMetadataSchema` in `types.ts`, not `.raw` passthrough),
+ * while all metadata (status, ranges, encoding label, bytes_returned) is
+ * preserved so the caller can re-request a narrower Range. We do NOT inline-scrub a detected body: a
+ * caller-requested raw blob mixing a credential with legitimate token-shaped
+ * content cannot be safely partially-redacted, so we fail closed.
+ *
+ * When CLEAN, behavior is byte-identical to the prior scrub: own credentials are
+ * removed from string metadata fields, `data_base64` passes through verbatim,
+ * and numeric/boolean metadata is untouched.
+ */
+function scrubRawArtifactFields(record) {
+    let count = 0;
+    const text = record["text"];
+    if (typeof text === "string")
+        count += detectCredentials(text).count;
+    const dataBase64 = record["data_base64"];
+    if (typeof dataBase64 === "string") {
+        const decoded = decodeUtf8Lossy(Buffer.from(dataBase64, "base64"));
+        count += detectCredentials(decoded).count;
+    }
+    if (count > 0) {
+        const withheld = {};
+        for (const [key, value] of Object.entries(record)) {
+            if (key === "text" || key === "data_base64")
+                continue;
+            withheld[key] = typeof value === "string" ? scrubOwnCredentials(value) : value;
+        }
+        withheld["withheld"] = "credential_detected";
+        withheld["redaction_count"] = count;
+        return withheld;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key === "data_base64") {
+            out[key] = value;
+        }
+        else if (typeof value === "string") {
+            out[key] = scrubOwnCredentials(value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+async function readBoundedBody(response, capBytes, abortFetch) {
+    const contentLength = parseNullablePositiveInt(response.headers.get("content-length"));
+    if (contentLength !== null && contentLength > capBytes) {
+        abortFetch();
+        return {
+            bytes: new Uint8Array(),
+            bytesRead: 0,
+            tooLarge: true,
+            tooLargeReason: "content_length_exceeded",
+        };
+    }
+    if (!response.body) {
+        return { bytes: new Uint8Array(), bytesRead: 0, tooLarge: false };
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytesRead = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            bytesRead += value.byteLength;
+            if (bytesRead > capBytes) {
+                const remaining = Math.max(0, capBytes - chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0));
+                if (remaining > 0)
+                    chunks.push(value.slice(0, remaining));
+                await reader.cancel().catch(() => undefined);
+                abortFetch();
+                return {
+                    bytes: concatChunks(chunks, capBytes),
+                    bytesRead,
+                    tooLarge: true,
+                    tooLargeReason: "stream_cap_exceeded",
+                };
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return { bytes: concatChunks(chunks, bytesRead), bytesRead, tooLarge: false };
+}
+function concatChunks(chunks, totalBytes) {
+    const out = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+function parseErrorPayload(body) {
+    if (body.tooLarge) {
+        const marker = { error: "local_response_too_large", detail: body.tooLargeReason };
+        return { payload: marker, rawPayload: marker };
+    }
+    const text = decodeUtf8Lossy(body.bytes);
+    if (!text)
+        return { payload: {}, rawPayload: {} };
+    try {
+        const rawPayload = JSON.parse(text);
+        return { payload: redact(rawPayload), rawPayload };
+    }
+    catch {
+        const rawPayload = { detail: text };
+        return { payload: redact(rawPayload), rawPayload };
+    }
+}
+function normalizeLogsPage(page) {
+    if (!Array.isArray(page["items"]) && Array.isArray(page["entries"])) {
+        return { ...page, items: page["entries"] };
+    }
+    return page;
+}
+function serializeRawArtifact(base, body) {
+    if (base["truncated"] === true) {
+        return { ...base, bytes_returned: body.length, encoding: "base64" };
+    }
+    const decoded = decodeUtf8Strict(body);
+    if (decoded !== null && decoded.length <= MAX_TEXT_CHARS) {
+        const candidate = { ...base, bytes_returned: body.length, encoding: "text", text: decoded };
+        if (JSON.stringify(candidate).length <= MAX_RESPONSE_BYTES)
+            return candidate;
+    }
+    if (body.length <= MAX_RAW_BODY_BYTES_FOR_BASE64) {
+        const candidate = { ...base, bytes_returned: body.length, encoding: "base64", data_base64: Buffer.from(body).toString("base64") };
+        if (JSON.stringify(candidate).length <= MAX_RESPONSE_BYTES)
+            return candidate;
+    }
+    return {
+        ...base,
+        bytes_returned: body.length,
+        truncated: true,
+        encoding: "base64",
+        local_response_too_large: "serialized_json_cap_exceeded",
+        range_guidance: "Retry with a smaller Range header.",
+    };
+}
+function buildArtifactRawPath(sessionId, filePath) {
+    if (!filePath || filePath.includes("\0") || filePath.startsWith("/") || filePath.startsWith("\\") || /^[a-z][a-z0-9+.-]*:/i.test(filePath)) {
+        throw new InvalidParamsError("Artifact file_path must be a relative path");
+    }
+    const encoded = filePath.split("/").map((segment) => {
+        const decoded = safeDecodeURIComponent(segment);
+        if (!segment || decoded === "." || decoded === "..") {
+            throw new InvalidParamsError("Artifact file_path must not contain empty, current, or parent path segments");
+        }
+        return encodeURIComponent(decoded);
+    }).join("/");
+    return `${AGENT_SESSIONS_PATH}/${encodePathSegment(sessionId)}/artifacts/raw/${encoded}`;
+}
+function formatRange(range) {
+    if (!Number.isInteger(range.start) || range.start < 0) {
+        throw new InvalidParamsError("Artifact range.start must be a non-negative integer");
+    }
+    if (range.end !== undefined && (!Number.isInteger(range.end) || range.end < range.start)) {
+        throw new InvalidParamsError("Artifact range.end must be an integer greater than or equal to range.start");
+    }
+    return `bytes=${range.start}-${range.end ?? ""}`;
+}
+function withQuery(path, params) {
+    const query = new URLSearchParams(params);
+    return `${path}?${query.toString()}`;
+}
+function normalizePageLimit(limit) {
+    if (limit === undefined)
+        return PAGE_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new InvalidParamsError("Elaris page limit must be a positive integer");
+    return Math.min(limit, PAGE_LIMIT);
+}
+function capMetadata(reason, resumeCursor, itemsReturned, bytesReturned, pagesFetched) {
+    return {
+        truncated: true,
+        truncation_reason: reason,
+        resume_cursor: resumeCursor,
+        items_returned: itemsReturned,
+        bytes_returned: bytesReturned,
+        pages_fetched: pagesFetched,
+    };
+}
+function emptyPage() {
+    return { items: [], next_cursor: null };
+}
+function readItems(page) {
+    if (typeof page === "object" && page !== null && "items" in page) {
+        const value = page.items;
+        if (Array.isArray(value))
+            return value;
+    }
+    return [];
+}
+function readNextCursor(page) {
+    if (typeof page === "object" && page !== null && "next_cursor" in page) {
+        const value = page.next_cursor;
+        return typeof value === "string" ? value : null;
+    }
+    return null;
+}
+function readPageRedactionCount(page) {
+    if (typeof page === "object" && page !== null && "redaction_count" in page) {
+        const value = page.redaction_count;
+        if (typeof value === "number" && Number.isFinite(value) && value > 0)
+            return value;
+    }
+    return 0;
+}
+function parseNullablePositiveInt(value) {
+    if (!value)
+        return null;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+function decodeUtf8Lossy(bytes) {
+    return new TextDecoder("utf-8").decode(bytes);
+}
+function decodeUtf8Strict(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+function encodePathSegment(segment) {
+    if (!segment || segment.includes("/") || segment.includes("\0")) {
+        throw new InvalidParamsError("Elaris path segment must be non-empty and must not contain slashes");
+    }
+    return encodeURIComponent(segment);
+}
+function safeDecodeURIComponent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new InvalidParamsError("Elaris path contains invalid percent encoding");
+    }
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return { retry_after_ms: Number(trimmed) * 1000, retry_class: "retry_after_delta" };
+    }
+    const dateMs = Date.parse(trimmed);
+    if (Number.isFinite(dateMs)) {
+        return { retry_after_ms: Math.max(0, dateMs - Date.now()), retry_class: "retry_after_date" };
+    }
+    return null;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function defaultSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(new CancellationError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(new CancellationError());
+        };
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=client.js.map