@aexhq/sdk 0.46.5-canary → 0.51.0

package/dist/_contracts/side-effect-audit.js

@@ -1,520 +0,0 @@
-import { createForbiddenFieldNamePredicate, isPlatformContentDigest, privateResourceHandlePattern, PUBLIC_SAFE_SECRET_PATTERNS, scanPublicSafePayload, underscoredHighEntropyPattern } from "./sdk-secrets.js";
-import { SideEffectAuditDeletionMetadataSchema, SideEffectAuditMetadataSchema } from "./schemas/side-effect-audit.js";
-import { parseWire } from "./schemas/wire.js";
-export const SIDE_EFFECT_AUDIT_SCHEMA_VERSION = 1;
-export const SIDE_EFFECT_AUDIT_REDACTION_SCANNER_VERSION = 1;
-export const SIDE_EFFECT_AUDIT_KIND = "aex.side_effect_audit.v1";
-export const SIDE_EFFECT_AUDIT_ACTIONS = [
-    "session.submit.accepted",
-    "session.submit.rejected",
-    "session.cancel.requested",
-    "session.delete.requested",
-    "session.delete.completed",
-    "session.delete.failed",
-    "session.download.requested",
-    "session.file.downloaded",
-    "session.log.downloaded",
-    "session.event.downloaded",
-    "workspace.asset.uploaded",
-    "workspace.asset.deleted",
-    "proxy.endpoint.called",
-    "mcp.credential.accessed",
-    "mcp.proxy.called",
-    "provider.proxy.called",
-    "custody.manifest.written",
-    "custody.transition.recorded",
-    "runtime.cleanup.completed",
-    "runtime.cleanup.failed",
-    "terminal_redrive.attempted",
-    "terminal_redrive.completed",
-    "api_key.created",
-    "api_key.deleted",
-    "api_key.used"
-];
-export const SIDE_EFFECT_AUDIT_ACTOR_PRINCIPAL_TYPES = [
-    "user",
-    "api_key",
-    "system",
-    "runtime"
-];
-export const SIDE_EFFECT_AUDIT_SOURCE_PLANES = [
-    "dashboard",
-    "api",
-    "runtime",
-    "system"
-];
-export const SIDE_EFFECT_AUDIT_AUTHENTICATION_KINDS = [
-    "dashboard_auth",
-    "api_key",
-    "runner_token",
-    "system"
-];
-export const SIDE_EFFECT_AUDIT_TARGET_TYPES = [
-    "workspace",
-    "session",
-    "proxy_endpoint",
-    "mcp_credential",
-    "mcp_proxy",
-    "provider_proxy",
-    "file_archive",
-    "session_file",
-    "session_log",
-    "session_event_stream",
-    "workspace_asset",
-    "custody_manifest",
-    "custody_transition",
-    "cleanup",
-    "deletion",
-    "terminal_redrive",
-    "api_key"
-];
-export const SIDE_EFFECT_AUDIT_OUTCOMES = [
-    "accepted",
-    "rejected",
-    "succeeded",
-    "failed",
-    "denied",
-    "canceled",
-    "pending"
-];
-export const SIDE_EFFECT_AUDIT_COUNT_NAMES = [
-    "requestBytes",
-    "responseBytes",
-    "durationMs",
-    "attemptCount",
-    "retryCount",
-    "fileCount",
-    "logCount",
-    "eventCount",
-    "assetCount",
-    "proxyCallCount",
-    "mcpCallCount",
-    "providerProxyCallCount",
-    "secretClassCount",
-    "resourceClassCount",
-    "deletedObjectCount",
-    "retainedObjectCount",
-    "failedObjectCount",
-    "quotaRequestedUnits",
-    "quotaRemainingUnits",
-    "reservationCount"
-];
-export const SIDE_EFFECT_AUDIT_TIMESTAMP_NAMES = [
-    "startedAt",
-    "finishedAt",
-    "observedAt",
-    "decidedAt",
-    "deletedAt",
-    "terminalAt",
-    "expiresAt"
-];
-export const SIDE_EFFECT_AUDIT_METADATA_EXCLUDED_VALUE_CLASSES = [
-    "headers",
-    "bodies",
-    "raw_urls",
-    "raw_paths",
-    "query_strings",
-    "provider_response_bodies",
-    "signed_urls",
-    "object_store_keys",
-    "vault_ids",
-    "resource_handles",
-    "bearer_hashes",
-    "secret_values",
-    "customer_or_agent_identity",
-    "private_pricing_or_provider_deployment"
-];
-export class SideEffectAuditRedactionError extends Error {
-    code = "side_effect_audit_not_public_safe";
-    findings;
-    constructor(findings) {
-        super(`side-effect audit payload contains non-public data at ${formatFindingPaths(findings)}`);
-        this.name = "SideEffectAuditRedactionError";
-        this.findings = Object.freeze([...findings]);
-    }
-}
-export function buildSideEffectAuditEvent(input) {
-    const action = normalizeAction(input.action);
-    const event = Object.freeze({
-        schemaVersion: SIDE_EFFECT_AUDIT_SCHEMA_VERSION,
-        kind: SIDE_EFFECT_AUDIT_KIND,
-        ...(input.auditId ? { auditId: assertSafeIdentifier(input.auditId, "auditId") } : {}),
-        workspaceId: assertSafeIdentifier(input.workspaceId, "workspaceId"),
-        ...(input.sessionId ? { sessionId: assertSafeIdentifier(input.sessionId, "sessionId") } : {}),
-        action,
-        outcome: normalizeOutcome(input.outcome),
-        observedAt: assertTimestamp(input.observedAt, "observedAt"),
-        actor: normalizeActor(input.actor),
-        target: normalizeTarget(input.target),
-        ...(input.correlation ? { correlation: normalizeCorrelation(input.correlation) } : {}),
-        metadata: redactSideEffectAuditMetadata(input.metadata ?? {}, action)
-    });
-    assertPublicSafeSideEffectAuditPayload(event);
-    return event;
-}
-export function buildSessionDeletionRequestedAuditEvent(input) {
-    return buildSessionScopedAuditEvent(input, {
-        action: "session.delete.requested",
-        outcome: "accepted",
-        targetType: "deletion"
-    });
-}
-export function buildSessionDeletionCompletedAuditEvent(input) {
-    return buildSessionScopedAuditEvent(input, {
-        action: "session.delete.completed",
-        outcome: "succeeded",
-        targetType: "deletion"
-    });
-}
-export function buildSessionDeletionFailedAuditEvent(input) {
-    return buildSessionScopedAuditEvent(input, {
-        action: "session.delete.failed",
-        outcome: "failed",
-        targetType: "deletion"
-    });
-}
-export function buildSessionDownloadRequestedAuditEvent(input) {
-    return buildSessionScopedAuditEvent(input, {
-        action: "session.download.requested",
-        outcome: "accepted",
-        targetType: "file_archive"
-    });
-}
-export function buildCustodyManifestWrittenAuditEvent(input) {
-    return buildSessionScopedAuditEvent(input, {
-        action: "custody.manifest.written",
-        outcome: "succeeded",
-        targetType: "custody_manifest"
-    });
-}
-export function redactSideEffectAuditMetadata(input, action) {
-    assertPublicSafeSideEffectAuditPayload(input);
-    assertSupportedMetadata(input, action);
-    const metadata = Object.freeze({
-        ...(input.status ? { status: normalizeStatusMetadata(input.status) } : {}),
-        ...(input.counts ? { counts: normalizeCounts(input.counts) } : {}),
-        ...(input.timestamps ? { timestamps: normalizeTimestamps(input.timestamps) } : {}),
-        ...(input.dimensions && !isDeletionAction(action)
-            ? { dimensions: normalizeDimensions(input.dimensions) }
-            : {}),
-        redaction: Object.freeze({
-            policy: "metadata_only",
-            scannerVersion: SIDE_EFFECT_AUDIT_REDACTION_SCANNER_VERSION,
-            excludes: Object.freeze([...SIDE_EFFECT_AUDIT_METADATA_EXCLUDED_VALUE_CLASSES])
-        })
-    });
-    assertPublicSafeSideEffectAuditPayload(metadata);
-    return metadata;
-}
-export function scanSideEffectAuditPayloadForSensitiveValues(input) {
-    return scanPublicSafePayload(input, {
-        patterns: auditStringPatterns,
-        isForbiddenFieldName: isForbiddenAuditFieldName,
-        isPatternExempt: ({ reason, path, match }) => reason === "high_entropy_token" &&
-            path === "$.target.id" &&
-            isPlatformContentDigest(match)
-    });
-}
-export function assertPublicSafeSideEffectAuditPayload(input) {
-    const findings = scanSideEffectAuditPayloadForSensitiveValues(input);
-    if (findings.length > 0) {
-        throw new SideEffectAuditRedactionError(findings);
-    }
-}
-function normalizeActor(input) {
-    if (!input || typeof input !== "object") {
-        throw new Error("side-effect audit actor must be an object");
-    }
-    return Object.freeze({
-        principal: normalizePrincipal(input.principal),
-        sourcePlane: normalizeSourcePlane(input.sourcePlane),
-        ...(input.authenticatedBy ? { authenticatedBy: normalizeAuthentication(input.authenticatedBy) } : {})
-    });
-}
-function normalizePrincipal(input) {
-    if (!input || typeof input !== "object") {
-        throw new Error("side-effect audit actor principal must be an object");
-    }
-    const type = normalizePrincipalType(input.type);
-    const ref = input.ref ? assertSafePrincipalRef(input.ref, "actor.principal.ref") : undefined;
-    return Object.freeze({
-        type,
-        ...(ref ? { ref } : {})
-    });
-}
-function normalizeTarget(input) {
-    if (!input || typeof input !== "object") {
-        throw new Error("side-effect audit target must be an object");
-    }
-    return Object.freeze({
-        type: normalizeTargetType(input.type),
-        ...(input.id ? { id: assertSafeIdentifier(input.id, "target.id") } : {}),
-        ...(input.name ? { name: assertSafeMetadataString(input.name, "target.name") } : {})
-    });
-}
-function normalizeCorrelation(input) {
-    return Object.freeze({
-        ...(input.requestId ? { requestId: assertSafeIdentifier(input.requestId, "correlation.requestId") } : {}),
-        ...(input.operationId
-            ? { operationId: assertSafeIdentifier(input.operationId, "correlation.operationId") }
-            : {}),
-        ...(input.eventId ? { eventId: assertSafeIdentifier(input.eventId, "correlation.eventId") } : {}),
-        ...(input.parentAuditId
-            ? { parentAuditId: assertSafeIdentifier(input.parentAuditId, "correlation.parentAuditId") }
-            : {}),
-        ...(input.sourceAuditId
-            ? { sourceAuditId: assertSafeIdentifier(input.sourceAuditId, "correlation.sourceAuditId") }
-            : {}),
-        ...(input.idempotencyKeyRef
-            ? {
-                idempotencyKeyRef: assertSafeIdentifier(input.idempotencyKeyRef, "correlation.idempotencyKeyRef")
-            }
-            : {})
-    });
-}
-/**
- * Drop the absent fields of an already-validated `metadata.status`.
- *
- * Shape, supported keys, and the `statusCode` range are settled by
- * `SideEffectAuditStatusMetadataSchema` before this runs. What remains is
- * the public-safety scan, which no schema can perform because it raises
- * {@link SideEffectAuditRedactionError} rather than a parse failure, and the
- * empty-string drop — a falsy value carries no signal and is omitted rather
- * than recorded.
- */
-function normalizeStatusMetadata(input) {
-    return Object.freeze({
-        ...(input.status ? { status: assertSafeMetadataString(input.status, "metadata.status.status") } : {}),
-        ...(input.statusCode !== undefined ? { statusCode: input.statusCode } : {}),
-        ...(input.errorClass
-            ? { errorClass: assertSafeMetadataString(input.errorClass, "metadata.status.errorClass") }
-            : {}),
-        ...(input.denialReason
-            ? { denialReason: assertSafeMetadataString(input.denialReason, "metadata.status.denialReason") }
-            : {}),
-        ...(input.followUpRequired !== undefined ? { followUpRequired: input.followUpRequired } : {})
-    });
-}
-function normalizeCounts(input) {
-    const out = {};
-    for (const [key, value] of Object.entries(input)) {
-        if (!isStringIn(key, SIDE_EFFECT_AUDIT_COUNT_NAMES)) {
-            throw new Error(`side-effect audit metadata.counts.${key} is not supported`);
-        }
-        if (value !== undefined) {
-            out[key] = nonNegativeFinite(value, `metadata.counts.${key}`);
-        }
-    }
-    return Object.freeze(out);
-}
-function normalizeTimestamps(input) {
-    const out = {};
-    for (const [key, value] of Object.entries(input)) {
-        if (!isStringIn(key, SIDE_EFFECT_AUDIT_TIMESTAMP_NAMES)) {
-            throw new Error(`side-effect audit metadata.timestamps.${key} is not supported`);
-        }
-        if (value !== undefined) {
-            out[key] = assertTimestamp(value, `metadata.timestamps.${key}`);
-        }
-    }
-    return Object.freeze(out);
-}
-/**
- * Drop the absent fields of an already-validated `metadata.dimensions`.
- *
- * Sibling of {@link normalizeStatusMetadata}: supported keys and the closed
- * `namespace` / `method` value sets are settled by
- * `SideEffectAuditDimensionsMetadataSchema`, leaving only the scan and the
- * empty-value drop.
- */
-function normalizeDimensions(input) {
-    return Object.freeze({
-        ...(input.provider ? { provider: assertSafeMetadataString(input.provider, "metadata.dimensions.provider") } : {}),
-        ...(input.namespace ? { namespace: input.namespace } : {}),
-        ...(input.method ? { method: input.method } : {}),
-        ...(input.surface ? { surface: assertSafeMetadataString(input.surface, "metadata.dimensions.surface") } : {})
-    });
-}
-/**
- * Reject an envelope a caller may not send, choosing the schema by action.
- *
- * The two schemas differ only in whether `dimensions` is a declared container,
- * so a deletion audit reports it with the same "not supported" wording an
- * invented key gets. Nested containers are validated in the same pass; the
- * shallowest complaint is the one reported, which is the order the hand-written
- * ladder produced.
- */
-function assertSupportedMetadata(input, action) {
-    parseWire(isDeletionAction(action)
-        ? SideEffectAuditDeletionMetadataSchema
-        : SideEffectAuditMetadataSchema, input);
-}
-function buildSessionScopedAuditEvent(input, spec) {
-    return buildSideEffectAuditEvent({
-        workspaceId: input.workspaceId,
-        sessionId: input.sessionId,
-        action: spec.action,
-        outcome: spec.outcome,
-        observedAt: input.observedAt,
-        actor: input.actor,
-        target: { type: spec.targetType, id: input.sessionId },
-        ...(input.correlation ? { correlation: input.correlation } : {}),
-        ...(input.metadata ? { metadata: input.metadata } : {})
-    });
-}
-function normalizeAction(input) {
-    if (!isStringIn(input, SIDE_EFFECT_AUDIT_ACTIONS)) {
-        throw new Error(`side-effect audit action ${String(input)} is not supported`);
-    }
-    return input;
-}
-function normalizeOutcome(input) {
-    if (!isStringIn(input, SIDE_EFFECT_AUDIT_OUTCOMES)) {
-        throw new Error(`side-effect audit outcome ${String(input)} is not supported`);
-    }
-    return input;
-}
-function normalizePrincipalType(input) {
-    if (!isStringIn(input, SIDE_EFFECT_AUDIT_ACTOR_PRINCIPAL_TYPES)) {
-        throw new Error(`side-effect audit principal type ${String(input)} is not supported`);
-    }
-    return input;
-}
-function normalizeSourcePlane(input) {
-    if (!isStringIn(input, SIDE_EFFECT_AUDIT_SOURCE_PLANES)) {
-        throw new Error(`side-effect audit source plane ${String(input)} is not supported`);
-    }
-    return input;
-}
-function normalizeAuthentication(input) {
-    if (!isStringIn(input, SIDE_EFFECT_AUDIT_AUTHENTICATION_KINDS)) {
-        throw new Error(`side-effect audit authentication kind ${String(input)} is not supported`);
-    }
-    return input;
-}
-function normalizeTargetType(input) {
-    if (!isStringIn(input, SIDE_EFFECT_AUDIT_TARGET_TYPES)) {
-        throw new Error(`side-effect audit target type ${String(input)} is not supported`);
-    }
-    return input;
-}
-function isDeletionAction(action) {
-    return action === "session.delete.requested" || action === "session.delete.completed" || action === "session.delete.failed";
-}
-const auditStringPatterns = Object.freeze([
-    ...PUBLIC_SAFE_SECRET_PATTERNS,
-    underscoredHighEntropyPattern(),
-    privateResourceHandlePattern([
-        "machine",
-        "agent",
-        "resource",
-        "handle",
-        "token_hash",
-        "bearer_hash"
-    ]),
-    Object.freeze({ reason: "raw_url", regex: /\bhttps?:\/\/\S+/i }),
-    Object.freeze({
-        reason: "raw_path",
-        regex: /(^|[\s"'`])\/[A-Za-z0-9._~!$&'()*+,;=:@%-]+(?:[/?#][^\s"'`]*)?/
-    })
-]);
-const isForbiddenAuditFieldName = createForbiddenFieldNamePredicate([
-    "authorization",
-    "header",
-    "headers",
-    "requestHeader",
-    "requestHeaders",
-    "responseHeader",
-    "responseHeaders",
-    "body",
-    "requestBody",
-    "responseBody",
-    "rawBody",
-    "prompt",
-    "url",
-    "rawUrl",
-    "href",
-    "query",
-    "queryString",
-    "path",
-    "rawPath",
-    "signedUrl",
-    "objectStoreKey",
-    "objectKey",
-    "vaultId",
-    "providerResponseBody",
-    "providerAccountId",
-    "providerDeployment",
-    "rateCard",
-    "rateCardVersion",
-    "margin",
-    "discount",
-    "calculator",
-    "reconciliation",
-    "resourceHandle",
-    "privateResourceHandle",
-    "bearerHash",
-    "tokenHash",
-    "apiKey",
-    "apiKeys",
-    "secretValue",
-    "providerSessionId",
-    "agentId",
-    "customerId",
-    "endUserId",
-    "identity",
-    "email"
-]);
-function assertSafeIdentifier(value, field) {
-    assertNonEmptyString(value, field);
-    if (!/^[A-Za-z0-9._:-]+$/.test(value)) {
-        throw new Error(`side-effect audit ${field} must be an opaque identifier without path separators`);
-    }
-    if (field === "target.id" && isPlatformContentDigest(value)) {
-        return value;
-    }
-    assertPublicSafeSideEffectAuditPayload(value);
-    return value;
-}
-function assertSafePrincipalRef(value, field) {
-    assertNonEmptyString(value, field);
-    if (!/^[A-Za-z0-9._:-]+$/.test(value)) {
-        throw new Error(`side-effect audit ${field} must be an opaque identifier without path separators`);
-    }
-    const ref = value;
-    if (/^(?:agent|session|customer|end[_-]?user|provider[_-]?session)[_.:-]/i.test(ref)) {
-        throw new Error(`side-effect audit ${field} must not introduce agent, session, or customer identity`);
-    }
-    assertPublicSafeSideEffectAuditPayload(ref);
-    return ref;
-}
-function assertSafeMetadataString(value, field) {
-    assertNonEmptyString(value, field);
-    assertPublicSafeSideEffectAuditPayload(value);
-    return value;
-}
-function assertNonEmptyString(value, field) {
-    if (typeof value !== "string" || value.trim().length === 0) {
-        throw new Error(`side-effect audit ${field} must be a non-empty string`);
-    }
-}
-function assertTimestamp(value, field) {
-    assertSafeMetadataString(value, field);
-    const ms = Date.parse(value);
-    if (!Number.isFinite(ms)) {
-        throw new Error(`side-effect audit ${field} must be an ISO timestamp string`);
-    }
-    return value;
-}
-function nonNegativeFinite(value, field) {
-    if (!Number.isFinite(value) || value < 0) {
-        throw new Error(`side-effect audit ${field} must be a non-negative finite number`);
-    }
-    return value;
-}
-function formatFindingPaths(findings) {
-    return findings.map((finding) => `${finding.path} (${finding.reason})`).join(", ");
-}
-function isStringIn(value, allowed) {
-    return typeof value === "string" && allowed.includes(value);
-}

package/dist/_contracts/sse.d.ts

@@ -1,74 +0,0 @@
-/**
- * Tiny SSE (text/event-stream) parser used by the SDK / CLI to consume
- * the dashboard's `/api/sessions/:id/events/stream` endpoint without
- * pulling in a DOM `EventSource` dependency. Node's `fetch` returns a
- * web `ReadableStream<Uint8Array>` body; this parser turns that into
- * an async iterable of `SseFrame`s.
- *
- * The wire grammar follows the WHATWG HTML spec § Server-sent events:
- *
- *   - Lines are separated by `\n`, `\r`, or `\r\n`.
- *   - A `:` prefix marks a comment — ignored.
- *   - `field: value` (or `field:value`, with no space) — leading space
- *     after the colon is stripped.
- *   - Recognised fields: `event`, `data`, `id`, `retry`.
- *   - Multiple `data:` lines join with `\n`.
- *   - A blank line dispatches the current frame and resets the buffer.
- *   - `event:` defaults to `"message"` when absent.
- *
- * The parser is deliberately a free function so it can be unit-tested
- * against synthesized chunk boundaries (one byte at a time, mid-frame,
- * across UTF-8 multi-byte sequences) without spinning up a real
- * connection.
- */
-export interface SseFrame {
-    readonly id?: string;
-    readonly event: string;
-    readonly data: string;
-    readonly retry?: number;
-}
-/**
- * Stateful parser: feed in chunks (in any size), pull out completed
- * frames. Designed for `for await` consumption — see `iterateSse`.
- */
-export declare class SseParser {
-    #private;
-    /**
-     * Push a chunk of raw bytes through the parser. Returns any frames
-     * that completed during this chunk. Chunks may contain zero, one,
-     * or many frame boundaries — the parser handles partial trailing
-     * data internally.
-     */
-    pushBytes(chunk: Uint8Array): readonly SseFrame[];
-    /**
-     * Push a text chunk directly. Used by the parser tests so they can
-     * exercise byte-boundary edge cases without manufacturing a
-     * `TextDecoder` round-trip.
-     */
-    pushText(text: string): readonly SseFrame[];
-    /**
-     * Indicate end-of-stream. Returns any final frame that the dispatcher
-     * was holding when the stream closed mid-frame (no trailing blank
-     * line). The dispatcher pattern is: blank line dispatches; if the
-     * remote closes after a partial frame, that frame is dropped per the
-     * spec.
-     */
-    flush(): void;
-    /**
-     * Current "last event id" — the cursor the SSE spec instructs the
-     * client to replay on automatic reconnection. Callers use this to
-     * resume after a disconnect.
-     */
-    get lastEventId(): string | undefined;
-}
-/**
- * Convert a web `ReadableStream<Uint8Array>` (the body of a fetch
- * Response) into an async iterable of SSE frames. The stream is
- * consumed exactly once; the caller is responsible for cancelling
- * the underlying reader on abort.
- *
- * The reader is raced against the abort signal so a long-blocked
- * server (no chunks for many seconds) still releases the loop
- * promptly when the consumer aborts.
- */
-export declare function iterateSse(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterable<SseFrame>;