@oxygen-agent/cli 1.1012.2 → 1.1013.15

package/node_modules/@oxygen/shared/dist/diagnostic-context.js

@@ -0,0 +1,17 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { diagnosticId } from "./diagnostics.js";
+const context = new AsyncLocalStorage();
+export function enterDiagnosticInvocation(value) {
+    const invocationId = diagnosticId(value);
+    if (!invocationId)
+        return;
+    const current = context.getStore();
+    if (current)
+        current.invocationId = invocationId;
+    else
+        context.enterWith({ invocationId });
+}
+export function withDiagnosticInvocation(value, task) {
+    return context.run({ invocationId: value }, task);
+}
+export function activeDiagnosticInvocation() { return context.getStore()?.invocationId; }

package/node_modules/@oxygen/shared/dist/diagnostic-credentials.d.ts

@@ -0,0 +1,4 @@
+/** Credential-bearing tool contracts already excluded by MCP analytics. */
+export declare const MCP_ARGUMENT_DENYLIST_TOOLS: ReadonlySet<string>;
+export declare const MCP_RESPONSE_DENYLIST_TOOLS: ReadonlySet<string>;
+export declare function credentialBearingOperation(operation: string, direction: "input" | "output"): boolean;

package/node_modules/@oxygen/shared/dist/diagnostic-credentials.js

@@ -0,0 +1,12 @@
+/** Credential-bearing tool contracts already excluded by MCP analytics. */
+export const MCP_ARGUMENT_DENYLIST_TOOLS = new Set([
+    "oxygen_integrations_connect", "oxygen_custom_integrations_apply", "oxygen_senders_checkpoint_solve",
+]);
+export const MCP_RESPONSE_DENYLIST_TOOLS = new Set([
+    "oxygen_senders_connect", "oxygen_whatsapp_connect", "oxygen_mailboxes_connect_oauth", "oxygen_integrations_connect",
+]);
+export function credentialBearingOperation(operation, direction) {
+    if (direction === "input")
+        return MCP_ARGUMENT_DENYLIST_TOOLS.has(operation) || /(?:senders|linkedin).*checkpoint.*solve|custom.integrations.apply/.test(operation);
+    return MCP_RESPONSE_DENYLIST_TOOLS.has(operation) || /^(?:senders|whatsapp|mailboxes|integrations) (?:connect|connect-oauth)$/.test(operation);
+}

package/node_modules/@oxygen/shared/dist/diagnostic-lock.d.ts

@@ -0,0 +1,2 @@
+/** Private spool lock. A dead owner is recoverable; age never evicts a live writer. */
+export declare function acquireDiagnosticLock(path: string): Promise<(() => Promise<void>) | null>;

package/node_modules/@oxygen/shared/dist/diagnostic-lock.js

@@ -0,0 +1,60 @@
+import { randomUUID } from "node:crypto";
+import { link, open, readFile, unlink } from "node:fs/promises";
+/** Private spool lock. A dead owner is recoverable; age never evicts a live writer. */
+export async function acquireDiagnosticLock(path) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        // Publish only an initialized owner. A crash between exclusive creation and
+        // writing a PID must not leave an empty, permanently unknowable lock.
+        const temporary = path + `.${randomUUID()}.tmp`;
+        const contents = JSON.stringify({ pid: process.pid, nonce: randomUUID(), start: await processStart(process.pid) });
+        const handle = await open(temporary, "wx", 0o600).catch(() => null);
+        if (!handle)
+            return null;
+        let published = false;
+        try {
+            await handle.writeFile(contents);
+            await handle.sync();
+            published = await link(temporary, path).then(() => true, () => false);
+        }
+        finally {
+            await unlink(temporary).catch(() => undefined);
+            if (!published)
+                await handle.close();
+        }
+        if (published) {
+            return async () => {
+                await handle.close();
+                if (await readFile(path, "utf8").catch(() => null) === contents)
+                    await unlink(path).catch(() => undefined);
+            };
+        }
+        const ownerContents = await readFile(path, "utf8").catch(() => null);
+        if (!ownerContents)
+            return null; // Unknown/unfinished owner stays protected.
+        try {
+            const owner = JSON.parse(ownerContents);
+            if (!Number.isInteger(owner.pid) || owner.pid <= 0)
+                return null;
+            let alive = true;
+            try {
+                process.kill(owner.pid, 0);
+            }
+            catch (error) {
+                alive = error.code !== "ESRCH";
+            }
+            const start = alive ? await processStart(owner.pid) : null;
+            if (alive && (!owner.start || !start || owner.start === start))
+                return null;
+            if (await readFile(path, "utf8").catch(() => null) === ownerContents)
+                await unlink(path).catch(() => undefined);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+async function processStart(pid) {
+    const value = await readFile(`/proc/${pid}/stat`, "utf8").catch(() => null);
+    return value ? value.slice(value.lastIndexOf(")") + 2).split(" ")[19] ?? null : null;
+}

package/node_modules/@oxygen/shared/dist/diagnostic-receipt.d.ts

@@ -0,0 +1,6 @@
+import { type DiagnosticRecord } from "./diagnostics.js";
+import type { DiagnosticStoredReceipt } from "./diagnostic-storage.js";
+import type { ProductAnalyticsEventInput } from "./product-analytics-core.js";
+export declare function diagnosticTraffic(record: DiagnosticRecord): "internal" | "customer" | "unknown";
+/** Private contents stay in storage; stable receipt UUIDs deduplicate retries. */
+export declare function diagnosticReceiptEvent(receipt: DiagnosticStoredReceipt): ProductAnalyticsEventInput;

package/node_modules/@oxygen/shared/dist/diagnostic-receipt.js

@@ -0,0 +1,22 @@
+import { diagnosticSummary } from "./diagnostics.js";
+import { PRODUCT_EVENTS } from "./product-analytics-events.js";
+export function diagnosticTraffic(record) {
+    const internal = new Set((process.env.OXYGEN_DIAGNOSTICS_INTERNAL_ORGANIZATIONS ?? "").split(",").map(value => value.trim()).filter(Boolean));
+    if (internal.has(record.organization_id ?? "") || internal.has(String(record.metadata.uploader_organization_id ?? "")))
+        return "internal";
+    return record.identity_verified ? "customer" : "unknown";
+}
+/** Private contents stay in storage; stable receipt UUIDs deduplicate retries. */
+export function diagnosticReceiptEvent(receipt) {
+    const { record } = receipt;
+    return { event: PRODUCT_EVENTS.DIAGNOSTIC_CAPTURE, organizationId: record.organization_id,
+        userId: record.user_id, uuid: record.id, timestamp: new Date(record.ended_at ?? record.started_at),
+        properties: { ...diagnosticSummary(record), request_id: record.id, diagnostic_key: receipt.key, payload_bytes: receipt.bytes,
+            payload_sha256: receipt.sha256, diagnostic_url: `/api/cli/admin/diagnostics/${record.id}?organization=${record.organization_id ?? "unknown"}`,
+            traffic_kind: diagnosticTraffic(record),
+            ...(record.layer === "worker" ? {
+                execution_id: typeof record.metadata.execution_id === "string" ? record.metadata.execution_id : null,
+                execution_attempt: typeof record.metadata.attempt === "number" ? record.metadata.attempt : null,
+            } : {}),
+        } };
+}

package/node_modules/@oxygen/shared/dist/diagnostic-storage-lock.d.ts

@@ -0,0 +1,2 @@
+/** Server mutex for shared host volumes; kernel locks span container PID namespaces. */
+export declare function acquireDiagnosticStorageLock(path: string, waitMs?: number): Promise<(() => Promise<void>) | null>;

package/node_modules/@oxygen/shared/dist/diagnostic-storage-lock.js

@@ -0,0 +1,39 @@
+import { chmod } from "node:fs/promises";
+/** Server mutex for shared host volumes; kernel locks span container PID namespaces. */
+export async function acquireDiagnosticStorageLock(path, waitMs = 0) {
+    // Ask the supported Node runtime directly: server bundlers rewrite even
+    // createRequire calls to an unsupported URL external for node:sqlite.
+    // Browser-side Server Action analysis never needs to resolve this built-in.
+    const { DatabaseSync } = process.getBuiltinModule("node:sqlite");
+    const databasePath = path + ".sqlite";
+    const deadline = performance.now() + waitMs;
+    let database;
+    while (true) {
+        try {
+            // SQLite owns every descriptor: closing a separate descriptor for this inode
+            // would release POSIX locks held by another connection in this process.
+            database = new DatabaseSync(databasePath, { timeout: 0 });
+            await chmod(databasePath, 0o600);
+            database.exec("BEGIN EXCLUSIVE");
+            break;
+        }
+        catch (error) {
+            database?.close();
+            database = undefined;
+            const busy = error && typeof error === "object" && "errcode" in error && (error.errcode === 5 || error.errcode === 6);
+            if (!busy || performance.now() >= deadline)
+                return null;
+            // A synchronous SQLite busy timeout would block the same-process owner
+            // from finishing its asynchronous fsync and releasing this lock.
+            await new Promise(resolve => setTimeout(resolve, Math.min(20, Math.max(1, deadline - performance.now()))));
+        }
+    }
+    const held = database;
+    let closed = false;
+    return async () => {
+        if (!closed) {
+            closed = true;
+            held.close();
+        }
+    };
+}

package/node_modules/@oxygen/shared/dist/diagnostic-storage.d.ts

@@ -0,0 +1,31 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { type DiagnosticRecord } from "./diagnostics.js";
+export type DiagnosticStoredReceipt = {
+    key: string;
+    sha256: string;
+    bytes: number;
+    compressed_bytes: number;
+    record: DiagnosticRecord;
+};
+type Store = {
+    client: S3Client;
+    bucket: string;
+};
+export declare function observeDiagnosticStorage(observer: (receipt: DiagnosticStoredReceipt) => Promise<void>): void;
+export declare function startDiagnosticRetry(): void;
+export declare function diagnosticsConfigured(): boolean;
+export declare function diagnosticStore(): Store;
+export declare function diagnosticObjectKey(record: Pick<DiagnosticRecord, "id" | "organization_id">): string;
+export declare function encodeDiagnostic(record: DiagnosticRecord): {
+    bytes: Buffer;
+    sha256: string;
+    compressed: Buffer;
+};
+export declare function decodeDiagnostic(compressed: Uint8Array, expectedHash?: string): DiagnosticRecord;
+export declare function readDiagnostic(id: string, organizationId: string | null): Promise<DiagnosticStoredReceipt>;
+/** Durable local write precedes upload. Retries replay telemetry bytes only. */
+export declare function storeDiagnostic(record: DiagnosticRecord): Promise<DiagnosticStoredReceipt | null>;
+export declare function flushDiagnosticSpool(): Promise<void>;
+/** A metadata-only fallback for an unsupported value never claims full capture. */
+export declare function partialDiagnostic(record: DiagnosticRecord, reason: string): DiagnosticRecord;
+export {};

package/node_modules/@oxygen/shared/dist/diagnostic-storage.js

@@ -0,0 +1,233 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { gzipSync, gunzipSync } from "node:zlib";
+import { GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { createDiagnosticRecord, credentialSafeDiagnostic, DIAGNOSTIC_MAX_BYTES, DIAGNOSTIC_RECORD_MAX_BYTES, DIAGNOSTIC_RETENTION_MS, diagnosticId, diagnosticSummary, parseDiagnosticRecord, sanitizeDiagnosticContent } from "./diagnostics.js";
+import { acquireDiagnosticStorageLock } from "./diagnostic-storage-lock.js";
+import { log } from "./log.js";
+import { recordTelemetryCounter } from "./telemetry.js";
+let cached;
+let warned = false;
+let flushing = null;
+let timer;
+let onStored;
+export function observeDiagnosticStorage(observer) {
+    onStored = observer;
+    startDiagnosticRetry();
+    void flushDiagnosticSpool();
+}
+export function startDiagnosticRetry() {
+    if (!timer && diagnosticsConfigured()) {
+        timer = setInterval(() => { void flushDiagnosticSpool(); }, 30_000);
+        timer.unref();
+    }
+}
+export function diagnosticsConfigured() {
+    return process.env.OXYGEN_DIAGNOSTICS_ENABLED !== "0" && Boolean(process.env.OXYGEN_DIAGNOSTICS_S3_ENDPOINT
+        && process.env.OXYGEN_DIAGNOSTICS_S3_BUCKET && process.env.OXYGEN_DIAGNOSTICS_S3_ACCESS_KEY_ID
+        && process.env.OXYGEN_DIAGNOSTICS_S3_SECRET_ACCESS_KEY && process.env.OXYGEN_DIAGNOSTICS_SPOOL_DIR);
+}
+export function diagnosticStore() {
+    if (!diagnosticsConfigured())
+        throw new Error("Diagnostics storage is not configured");
+    const endpoint = process.env.OXYGEN_DIAGNOSTICS_S3_ENDPOINT;
+    const bucket = process.env.OXYGEN_DIAGNOSTICS_S3_BUCKET;
+    const accessKeyId = process.env.OXYGEN_DIAGNOSTICS_S3_ACCESS_KEY_ID;
+    const secretAccessKey = process.env.OXYGEN_DIAGNOSTICS_S3_SECRET_ACCESS_KEY;
+    const key = createHash("sha256").update([endpoint, bucket, accessKeyId, secretAccessKey].join("\0")).digest("hex");
+    if (cached?.key !== key)
+        cached = { key, store: { bucket, client: new S3Client({
+                    endpoint, region: "us-east-1", forcePathStyle: true, maxAttempts: 2,
+                    credentials: { accessKeyId, secretAccessKey },
+                }) } };
+    return cached.store;
+}
+export function diagnosticObjectKey(record) {
+    if (!diagnosticId(record.id) || (record.organization_id !== null && !diagnosticId(record.organization_id)))
+        throw new Error("Invalid diagnostic scope");
+    return `records/${record.organization_id ?? "unknown"}/${record.id}.json.gz`;
+}
+export function encodeDiagnostic(record) {
+    const bytes = Buffer.from(JSON.stringify(sanitizeDiagnosticContent(credentialSafeDiagnostic(parseDiagnosticRecord(record)))));
+    if (bytes.length > DIAGNOSTIC_RECORD_MAX_BYTES)
+        throw new Error("Diagnostic record capacity exceeded");
+    return { bytes, sha256: createHash("sha256").update(bytes).digest("hex"), compressed: gzipSync(bytes) };
+}
+export function decodeDiagnostic(compressed, expectedHash) {
+    const bytes = gunzipSync(compressed, { maxOutputLength: DIAGNOSTIC_RECORD_MAX_BYTES });
+    if (expectedHash && createHash("sha256").update(bytes).digest("hex") !== expectedHash)
+        throw new Error("Diagnostic integrity mismatch");
+    const record = parseDiagnosticRecord(JSON.parse(bytes.toString("utf8")));
+    if (Date.now() - Date.parse(record.started_at) >= DIAGNOSTIC_RETENTION_MS)
+        throw Object.assign(new Error("Diagnostic content has expired"), { code: "diagnostic_content_expired" });
+    return record;
+}
+export async function readDiagnostic(id, organizationId) {
+    const { client, bucket } = diagnosticStore();
+    const key = diagnosticObjectKey({ id, organization_id: organizationId });
+    const result = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }), { abortSignal: AbortSignal.timeout(15_000) });
+    if (!result.Body)
+        throw new Error("Diagnostic body missing");
+    const compressed = await result.Body.transformToByteArray();
+    if (!result.Metadata?.sha256 || !/^[0-9a-f]{64}$/.test(result.Metadata.sha256))
+        throw new Error("Diagnostic integrity manifest missing");
+    const record = decodeDiagnostic(compressed, result.Metadata.sha256);
+    const bytes = gunzipSync(compressed, { maxOutputLength: DIAGNOSTIC_RECORD_MAX_BYTES }).length;
+    if (String(bytes) !== result.Metadata.bytes)
+        throw new Error("Diagnostic byte manifest mismatch");
+    if (record.id !== id || record.organization_id !== organizationId)
+        throw new Error("Diagnostic scope mismatch");
+    return { key, sha256: result.Metadata.sha256, bytes, compressed_bytes: compressed.length, record };
+}
+/** Durable local write precedes upload. Retries replay telemetry bytes only. */
+export async function storeDiagnostic(record) {
+    recordTelemetryCounter("oxygen.diagnostics.attempted", 1, { source: record.surface, layer: record.layer });
+    if (!diagnosticsConfigured()) {
+        if (!warned && process.env.NODE_ENV !== "test") {
+            warned = true;
+            log("warn", "diagnostics.not_configured", { capture_state: "unavailable" });
+        }
+        return null;
+    }
+    const directory = process.env.OXYGEN_DIAGNOSTICS_SPOOL_DIR;
+    let path;
+    try {
+        let encoded;
+        try {
+            encoded = encodeDiagnostic(record);
+        }
+        catch {
+            record = partialDiagnostic(record, "unsupported_or_oversized_content");
+            encoded = encodeDiagnostic(record);
+        }
+        record = parseDiagnosticRecord(JSON.parse(encoded.bytes.toString("utf8")));
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        // Admission and expiry share one lock across web/worker processes on a host.
+        const lockPath = join(directory, ".admission.lock");
+        const release = await acquireDiagnosticStorageLock(lockPath, 5_000);
+        if (!release)
+            throw new Error("Diagnostic spool admission busy");
+        try {
+            const { used } = await inspectDiagnosticSpool(directory);
+            if (used + encoded.compressed.length > DIAGNOSTIC_MAX_BYTES)
+                throw new Error("Diagnostic spool is full");
+            path = join(directory, `${record.id}.json.gz`);
+            const temporary = join(directory, `${record.id}.${randomUUID()}.tmp`);
+            const handle = await open(temporary, "wx", 0o600);
+            try {
+                await handle.writeFile(encoded.compressed);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, path);
+        }
+        finally {
+            await release();
+        }
+        startDiagnosticRetry();
+        const receipt = await uploadEncodedDiagnostic(record, encoded);
+        await unlink(path).catch(() => undefined);
+        return receipt;
+    }
+    catch {
+        // Neither storage credentials nor upstream exception text belong in logs.
+        log("warn", path ? "diagnostics.capture_deferred" : "diagnostics.capture_lost", { diagnostic_id: record.id, reason: path ? "upload_failed" : "spool_admission_failed" });
+        recordTelemetryCounter(path ? "oxygen.diagnostics.deferred" : "oxygen.diagnostics.lost", 1, { source: record.surface });
+        return null;
+    }
+}
+async function uploadEncodedDiagnostic(record, encoded) {
+    const captured = Date.parse(record.started_at);
+    const now = Date.now();
+    if (now - captured >= 72 * 60 * 60 * 1000)
+        throw new Error("Diagnostic upload has expired");
+    // S3 day-based expiry rounds to the next UTC midnight. Tagged age bands
+    // leave that final day inside the 30-day deadline measured from capture.
+    const retentionDays = Math.min(29, 29 - (Math.floor(now / 86_400_000) - Math.floor(captured / 86_400_000)));
+    const { client, bucket } = diagnosticStore();
+    const key = diagnosticObjectKey(record);
+    await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: encoded.compressed,
+        ContentType: "application/gzip",
+        Tagging: `diagnostic_retention_days=${retentionDays}`,
+        Metadata: { sha256: encoded.sha256, bytes: String(encoded.bytes.length), expires_at: new Date(Date.parse(record.started_at) + DIAGNOSTIC_RETENTION_MS).toISOString() },
+    }), { abortSignal: AbortSignal.timeout(15_000) });
+    log("info", "diagnostics.capture_stored", { ...diagnosticSummary(record), org_id: record.organization_id, user_id: record.user_id,
+        diagnostic_key: key, bytes: encoded.bytes.length, compressed_bytes: encoded.compressed.length, sha256: encoded.sha256 });
+    recordTelemetryCounter("oxygen.diagnostics.stored", 1, { source: record.surface, layer: record.layer });
+    const receipt = { key, sha256: encoded.sha256, bytes: encoded.bytes.length, compressed_bytes: encoded.compressed.length, record };
+    if (onStored)
+        await onStored(receipt);
+    return receipt;
+}
+export function flushDiagnosticSpool() {
+    if (flushing)
+        return flushing;
+    flushing = (async () => {
+        if (!diagnosticsConfigured())
+            return;
+        const directory = process.env.OXYGEN_DIAGNOSTICS_SPOOL_DIR;
+        const release = await acquireDiagnosticStorageLock(join(directory, ".upload.lock"));
+        if (!release)
+            return;
+        try {
+            // Idle workers enforce the same expiry as new admissions. The admission
+            // lock protects cleanup against a writer replacing an old record path.
+            const admission = await acquireDiagnosticStorageLock(join(directory, ".admission.lock"));
+            if (!admission)
+                return;
+            let files;
+            try {
+                files = (await inspectDiagnosticSpool(directory)).files.slice(0, 20);
+            }
+            finally {
+                await admission();
+            }
+            for (const name of files) {
+                const path = join(directory, name);
+                try {
+                    const compressed = await readFile(path);
+                    const record = decodeDiagnostic(compressed);
+                    await uploadEncodedDiagnostic(record, encodeDiagnostic(record));
+                    await unlink(path).catch(() => undefined);
+                }
+                catch { /* retain failed uploads; admission expires them visibly */ }
+            }
+        }
+        finally {
+            await release();
+        }
+    })().catch(() => undefined).finally(() => { flushing = null; });
+    return flushing;
+}
+/** Caller holds admission lock; count retained bytes and expire actual filenames. */
+async function inspectDiagnosticSpool(directory) {
+    let used = 0;
+    const files = [];
+    for (const name of await readdir(directory)) {
+        const record = /^[0-9a-f-]+\.json\.gz$/.test(name);
+        if (!record && !/^[0-9a-f-]+(?:\.[0-9a-f-]+)?\.tmp$/.test(name))
+            continue;
+        const path = join(directory, name);
+        const info = await stat(path).catch(() => null);
+        if (!info)
+            continue;
+        if (Date.now() - info.mtimeMs >= 72 * 60 * 60 * 1000) {
+            await unlink(path);
+            log("warn", "diagnostics.capture_lost", { reason: "spool_expired", bytes: info.size });
+            recordTelemetryCounter("oxygen.diagnostics.lost", 1, { reason: "spool_expired" });
+        }
+        else {
+            used += info.size;
+            if (record)
+                files.push(name);
+        }
+    }
+    return { used, files };
+}
+/** A metadata-only fallback for an unsupported value never claims full capture. */
+export function partialDiagnostic(record, reason) {
+    return createDiagnosticRecord({ ...record, input: null, output: null, capture_state: "partial", metadata: { capture_reason: reason } });
+}

package/node_modules/@oxygen/shared/dist/diagnostics.d.ts

@@ -0,0 +1,49 @@
+/** Internal diagnostic evidence, distinct from customer run state and usage counts. */
+export declare const DIAGNOSTIC_VERSION = 1;
+export declare const DIAGNOSTIC_RETENTION_MS: number;
+export declare const DIAGNOSTIC_INVOCATION_HEADER = "X-Oxygen-Invocation-Id";
+export declare const DIAGNOSTIC_UPLOAD_CHUNK_BYTES: number;
+export declare const DIAGNOSTIC_MAX_BYTES: number;
+export declare const DIAGNOSTIC_RECORD_MAX_BYTES: number;
+export declare const DIAGNOSTIC_UPLOAD_MAX_CHUNKS = 17;
+export type DiagnosticOutcome = "ok" | "invalid_input" | "refused" | "platform_error" | "network_error" | "cancelled" | "pending";
+export type DiagnosticRecord = {
+    version: 1;
+    id: string;
+    invocation_id: string;
+    parent_id: string | null;
+    layer: "invocation" | "api" | "worker" | "protocol";
+    surface: "cli" | "mcp" | "web" | "worker";
+    operation: string;
+    started_at: string;
+    ended_at: string | null;
+    outcome: DiagnosticOutcome;
+    error_code: string | null;
+    status: number | null;
+    organization_id: string | null;
+    user_id: string | null;
+    identity_verified: boolean;
+    client_version: string | null;
+    trace_id: string | null;
+    traceparent: string | null;
+    capture_state: "complete" | "partial";
+    input: unknown;
+    output: unknown;
+    metadata: Record<string, unknown>;
+};
+export declare function diagnosticId(value: unknown): string | null;
+export declare function diagnosticOutcome(ok: boolean, status?: number | null, code?: string | null): DiagnosticOutcome;
+export declare function createDiagnosticRecord(input: {
+    [K in keyof DiagnosticRecord]?: DiagnosticRecord[K] | undefined;
+} & Pick<DiagnosticRecord, "surface" | "operation">): DiagnosticRecord;
+export declare function sanitizeDiagnosticText(value: string, knownSecrets?: readonly string[]): string;
+/** No business-content, array, string, field-count or depth truncation. */
+export declare function sanitizeDiagnosticContent(value: unknown, knownSecrets?: readonly string[]): unknown;
+export declare function sanitizeDiagnosticArgv(argv: string[]): string[];
+export declare function parseDiagnosticRecord(value: unknown): DiagnosticRecord;
+export declare function diagnosticSummary(record: DiagnosticRecord): Record<string, string | number | boolean | null>;
+export declare function credentialSafeDiagnostic(record: DiagnosticRecord): DiagnosticRecord;
+/** Bound the diagnostic branch of a response tee without delaying its consumer. */
+export declare function readDiagnosticProtocolText(body: ReadableStream<Uint8Array> | null): Promise<string | null>;
+/** Finite POST SSE is decoded before credential/binary filtering, like JSON. */
+export declare function parseDiagnosticProtocolBody(text: string | null, contentType?: string | null): unknown;