@aexhq/sdk 0.13.6

package/dist/_contracts/run-retention.js

@@ -0,0 +1,484 @@
+import { isTerminalRunStatus } from "./status.js";
+export const RUN_RETENTION_SCHEMA_VERSION = 1;
+export const RUN_DELETION_MANIFEST_KIND = "aex.run_deletion_manifest.v1";
+export const RUN_DELETION_JOB_KIND = "aex.run_deletion_job.v1";
+export const RUN_DELETION_MANIFEST_CONTENT_TYPE = "application/json; charset=utf-8";
+export const RUN_RETENTION_REDACTION_SCANNER_VERSION = 1;
+export const RUN_DELETION_REASONS = ["manual_delete", "retention_gc"];
+export const RUN_DELETION_MANIFEST_MODES = ["dry_run", "final"];
+export const RUN_DELETION_CANDIDATE_STATUSES = ["selected", "blocked"];
+export const RUN_DELETION_BLOCKERS = [
+    "non_terminal",
+    "already_deleted",
+    "concurrent_delete",
+    "retention_policy_disabled",
+    "unexpired",
+    "held",
+    "retention_exempt",
+    "unresolved_cleanup",
+    "unresolved_custody"
+];
+export const RUN_DELETION_COUNT_CLASSES = [
+    "r2_objects",
+    "outputs",
+    "logs",
+    "events",
+    "assets",
+    "db_event_rows",
+    "db_output_rows",
+    "capture_failures",
+    "storage_samples",
+    "custody_manifests"
+];
+export const RUN_DELETION_COUNT_STATUSES = ["counted", "not_counted", "partial", "failed"];
+export const RUN_DELETION_JOB_STATUSES = [
+    "queued",
+    "planning",
+    "blocked",
+    "manifest_written",
+    "deleting",
+    "delete_failed",
+    "completed",
+    "failed"
+];
+export const RUN_DELETION_PROOF_STATUSES = [
+    "not_started",
+    "running",
+    "completed",
+    "failed"
+];
+export const RUN_DELETION_WRITE_STATUSES = ["not_written", "written", "write_failed"];
+export const RUN_RETENTION_EXCLUDED_VALUE_CLASSES = [
+    "raw_paths",
+    "object_keys",
+    "filenames",
+    "object_sizes",
+    "hashes",
+    "provider_ids",
+    "vault_ids",
+    "resource_ids",
+    "resource_handles",
+    "signed_urls"
+];
+export class RunRetentionValidationError extends Error {
+    code = "run_retention_contract_invalid";
+    constructor(message) {
+        super(message);
+        this.name = "RunRetentionValidationError";
+    }
+}
+export class RunRetentionRedactionError extends Error {
+    code = "run_retention_payload_not_public_safe";
+    findings;
+    constructor(findings) {
+        super(`run retention payload contains non-public data at ${formatFindingPaths(findings)}`);
+        this.name = "RunRetentionRedactionError";
+        this.findings = Object.freeze([...findings]);
+    }
+}
+export class FakeRunDeletionManifestObjectStore {
+    #objects = new Map();
+    async putRunDeletionManifestObject(object) {
+        assertPublicSafeRunRetentionPayload(object.manifest);
+        this.#objects.set(object.runId, cloneJson(object.manifest));
+    }
+    getByRunId(runId) {
+        return this.get(runId);
+    }
+    get(runId) {
+        const object = this.#objects.get(runId);
+        return object ? cloneJson(object) : undefined;
+    }
+    listRunIds() {
+        return Object.freeze([...this.#objects.keys()].sort());
+    }
+}
+export function createRunDeletionManifestWriter(store) {
+    return {
+        async writeRunDeletionManifest(input) {
+            return writeRunDeletionManifest(store, input);
+        }
+    };
+}
+export async function writeRunDeletionManifest(store, input) {
+    const manifest = buildRunDeletionManifest(input);
+    await store.putRunDeletionManifestObject({
+        runId: manifest.run.runId,
+        workspaceId: manifest.run.workspaceId,
+        contentType: RUN_DELETION_MANIFEST_CONTENT_TYPE,
+        manifest
+    });
+    return Object.freeze({
+        status: "written",
+        schemaVersion: RUN_RETENTION_SCHEMA_VERSION,
+        runId: manifest.run.runId,
+        workspaceId: manifest.run.workspaceId,
+        writtenAt: manifest.generatedAt,
+        mode: manifest.mode
+    });
+}
+export function buildRunRetentionPolicy(input = {}) {
+    if (input.automaticDeletion) {
+        if (input.retentionDays === undefined) {
+            throw new RunRetentionValidationError("automatic retention deletion requires an explicit positive retentionDays value");
+        }
+        return Object.freeze({
+            mode: "delete_after_days",
+            manualDelete: "enabled",
+            automaticDeletion: "enabled",
+            retentionDays: positiveInteger(input.retentionDays, "policy.retentionDays")
+        });
+    }
+    if (input.retentionDays !== undefined) {
+        throw new RunRetentionValidationError("retentionDays is not allowed when automatic retention deletion is disabled");
+    }
+    return Object.freeze({
+        mode: "retain_indefinitely",
+        manualDelete: "enabled",
+        automaticDeletion: "disabled"
+    });
+}
+export function evaluateRunDeletionCandidate(input) {
+    const now = assertTimestamp(input.now, "candidate.now");
+    const run = normalizeCandidateRun(input.run);
+    const policy = normalizePolicy(input.policy);
+    const blockers = [];
+    addRunBlockers(blockers, run, now);
+    let eligibleAt;
+    if (input.reason === "retention_gc") {
+        if (policy.mode !== "delete_after_days" || policy.retentionDays === undefined) {
+            blockers.push(blocker("retention_policy_disabled", now));
+        }
+        else if (run.terminalAt) {
+            eligibleAt = addDaysIso(run.terminalAt, policy.retentionDays);
+            if (Date.parse(now) < Date.parse(eligibleAt)) {
+                blockers.push(blocker("unexpired", now));
+            }
+        }
+    }
+    else {
+        eligibleAt = now;
+    }
+    return Object.freeze({
+        status: blockers.length === 0 ? "selected" : "blocked",
+        reason: input.reason,
+        evaluatedAt: now,
+        ...(eligibleAt ? { eligibleAt } : {}),
+        blockers: Object.freeze(blockers)
+    });
+}
+export function buildRunDeletionManifest(input) {
+    const candidate = input.candidate ??
+        evaluateRunDeletionCandidate({
+            run: input.run,
+            reason: input.request.reason,
+            now: input.generatedAt,
+            ...(input.policy ? { policy: input.policy } : {})
+        });
+    const normalizedCandidate = normalizeCandidate(candidate);
+    const run = normalizeManifestRun(input.run, normalizedCandidate.eligibleAt);
+    const summary = buildRunDeletionSummary(input.counts ?? [], normalizedCandidate);
+    const manifest = Object.freeze({
+        schemaVersion: RUN_RETENTION_SCHEMA_VERSION,
+        kind: RUN_DELETION_MANIFEST_KIND,
+        generatedAt: assertTimestamp(input.generatedAt, "manifest.generatedAt"),
+        mode: input.mode,
+        run,
+        request: normalizeRequest(input.request),
+        candidate: normalizedCandidate,
+        summary,
+        redaction: Object.freeze({
+            policy: "counts_status_timestamps_only",
+            scannerVersion: RUN_RETENTION_REDACTION_SCANNER_VERSION,
+            excludes: Object.freeze([...RUN_RETENTION_EXCLUDED_VALUE_CLASSES])
+        })
+    });
+    assertPublicSafeRunRetentionPayload(manifest);
+    return manifest;
+}
+export function assertRunDeletionOrder(proof) {
+    const manifest = normalizeManifestProof(proof.manifest);
+    const purge = normalizePurgeProof(proof.purge);
+    const purgeStarted = purge.status === "running" || purge.status === "completed" || purge.status === "failed";
+    if (purgeStarted && manifest.status !== "written") {
+        throw new RunRetentionValidationError("run deletion cannot purge assets before the deletion manifest is written");
+    }
+    if (purgeStarted && manifest.mode !== "final") {
+        throw new RunRetentionValidationError("run deletion cannot purge assets from a dry-run deletion manifest");
+    }
+}
+export function buildRunDeletionJob(input) {
+    assertRunDeletionOrder(input.order);
+    const job = Object.freeze({
+        schemaVersion: RUN_RETENTION_SCHEMA_VERSION,
+        kind: RUN_DELETION_JOB_KIND,
+        jobId: assertSafeIdentifier(input.jobId, "job.jobId"),
+        runId: assertSafeIdentifier(input.runId, "job.runId"),
+        workspaceId: assertSafeIdentifier(input.workspaceId, "job.workspaceId"),
+        reason: input.reason,
+        mode: input.mode,
+        status: input.status,
+        createdAt: assertTimestamp(input.createdAt, "job.createdAt"),
+        ...(input.updatedAt ? { updatedAt: assertTimestamp(input.updatedAt, "job.updatedAt") } : {}),
+        order: normalizeOrderProof(input.order),
+        ...(input.candidate ? { candidate: normalizeCandidate(input.candidate) } : {}),
+        ...(input.summary ? { summary: normalizeSummary(input.summary) } : {})
+    });
+    assertPublicSafeRunRetentionPayload(job);
+    return job;
+}
+export function scanRunRetentionPayloadForSensitiveValues(input) {
+    const findings = [];
+    visitRetentionValue(input, "$", findings);
+    return Object.freeze(findings);
+}
+export function assertPublicSafeRunRetentionPayload(input) {
+    const findings = scanRunRetentionPayloadForSensitiveValues(input);
+    if (findings.length > 0) {
+        throw new RunRetentionRedactionError(findings);
+    }
+}
+function normalizePolicy(input) {
+    if (!input) {
+        return buildRunRetentionPolicy();
+    }
+    if ("mode" in input) {
+        if (input.mode === "delete_after_days") {
+            if (input.retentionDays === undefined) {
+                throw new RunRetentionValidationError("delete_after_days retention policy requires an explicit retentionDays value");
+            }
+            return buildRunRetentionPolicy({
+                automaticDeletion: true,
+                retentionDays: input.retentionDays
+            });
+        }
+        if (input.retentionDays !== undefined) {
+            throw new RunRetentionValidationError("retain_indefinitely retention policy cannot include retentionDays");
+        }
+        return buildRunRetentionPolicy();
+    }
+    return buildRunRetentionPolicy(input);
+}
+function normalizeCandidateRun(input) {
+    return Object.freeze({
+        runId: assertSafeIdentifier(input.runId, "run.runId"),
+        workspaceId: assertSafeIdentifier(input.workspaceId, "run.workspaceId"),
+        status: assertSafeMetadataString(input.status, "run.status"),
+        ...(input.createdAt ? { createdAt: assertTimestamp(input.createdAt, "run.createdAt") } : {}),
+        ...(input.terminalAt ? { terminalAt: assertTimestamp(input.terminalAt, "run.terminalAt") } : {}),
+        ...(input.pendingDeleteAt ? { pendingDeleteAt: assertTimestamp(input.pendingDeleteAt, "run.pendingDeleteAt") } : {}),
+        ...(input.deletedAt ? { deletedAt: assertTimestamp(input.deletedAt, "run.deletedAt") } : {}),
+        ...(input.held !== undefined ? { held: input.held } : {}),
+        ...(input.retentionExempt !== undefined ? { retentionExempt: input.retentionExempt } : {}),
+        ...(input.unresolvedCleanup !== undefined ? { unresolvedCleanup: input.unresolvedCleanup } : {}),
+        ...(input.unresolvedCustody !== undefined ? { unresolvedCustody: input.unresolvedCustody } : {})
+    });
+}
+function normalizeManifestRun(input, eligibleAt) {
+    const run = normalizeCandidateRun(input);
+    return Object.freeze({
+        runId: run.runId,
+        workspaceId: run.workspaceId,
+        status: run.status,
+        ...(run.createdAt ? { createdAt: run.createdAt } : {}),
+        ...(run.terminalAt ? { terminalAt: run.terminalAt } : {}),
+        ...(eligibleAt ? { eligibleAt: assertTimestamp(eligibleAt, "run.eligibleAt") } : {}),
+        ...(run.pendingDeleteAt ? { pendingDeleteAt: run.pendingDeleteAt } : {}),
+        ...(run.deletedAt ? { deletedAt: run.deletedAt } : {})
+    });
+}
+function normalizeRequest(input) {
+    return Object.freeze({
+        reason: input.reason,
+        actorClass: input.actorClass
+    });
+}
+function normalizeCandidate(input) {
+    return Object.freeze({
+        status: input.status,
+        reason: input.reason,
+        evaluatedAt: assertTimestamp(input.evaluatedAt, "candidate.evaluatedAt"),
+        ...(input.eligibleAt ? { eligibleAt: assertTimestamp(input.eligibleAt, "candidate.eligibleAt") } : {}),
+        blockers: Object.freeze(input.blockers.map(normalizeBlocker))
+    });
+}
+function normalizeBlocker(input) {
+    return Object.freeze({
+        code: input.code,
+        observedAt: assertTimestamp(input.observedAt, "candidate.blocker.observedAt")
+    });
+}
+function normalizeCount(input) {
+    return Object.freeze({
+        class: assertSafeMetadataString(input.class, "summary.count.class"),
+        count: nonNegativeInteger(input.count, "summary.count.count"),
+        status: input.status,
+        ...(input.countedAt ? { countedAt: assertTimestamp(input.countedAt, "summary.count.countedAt") } : {}),
+        ...(input.errorClass ? { errorClass: assertSafeMetadataString(input.errorClass, "summary.count.errorClass") } : {})
+    });
+}
+function buildRunDeletionSummary(input, candidate) {
+    const counts = Object.freeze(input.map(normalizeCount));
+    return Object.freeze({
+        totalCount: counts.reduce((sum, item) => sum + item.count, 0),
+        failedCountClasses: counts.filter((item) => item.status === "failed").length,
+        partialCountClasses: counts.filter((item) => item.status === "partial").length,
+        blockerCount: candidate.blockers.length,
+        counts
+    });
+}
+function normalizeSummary(input) {
+    return Object.freeze({
+        totalCount: nonNegativeInteger(input.totalCount, "summary.totalCount"),
+        failedCountClasses: nonNegativeInteger(input.failedCountClasses, "summary.failedCountClasses"),
+        partialCountClasses: nonNegativeInteger(input.partialCountClasses, "summary.partialCountClasses"),
+        blockerCount: nonNegativeInteger(input.blockerCount, "summary.blockerCount"),
+        counts: Object.freeze(input.counts.map(normalizeCount))
+    });
+}
+function normalizeOrderProof(input) {
+    return Object.freeze({
+        manifest: normalizeManifestProof(input.manifest),
+        purge: normalizePurgeProof(input.purge)
+    });
+}
+function normalizeManifestProof(input) {
+    return Object.freeze({
+        status: input.status,
+        ...(input.mode ? { mode: input.mode } : {}),
+        ...(input.writtenAt ? { writtenAt: assertTimestamp(input.writtenAt, "proof.manifest.writtenAt") } : {})
+    });
+}
+function normalizePurgeProof(input) {
+    return Object.freeze({
+        status: input.status,
+        ...(input.startedAt ? { startedAt: assertTimestamp(input.startedAt, "proof.purge.startedAt") } : {}),
+        ...(input.completedAt ? { completedAt: assertTimestamp(input.completedAt, "proof.purge.completedAt") } : {}),
+        ...(input.deletedObjectCount !== undefined
+            ? { deletedObjectCount: nonNegativeInteger(input.deletedObjectCount, "proof.purge.deletedObjectCount") }
+            : {})
+    });
+}
+function addRunBlockers(blockers, run, observedAt) {
+    if (run.status === "deleted") {
+        blockers.push(blocker("already_deleted", observedAt));
+    }
+    else if (run.status === "pending_delete" || run.pendingDeleteAt) {
+        blockers.push(blocker("concurrent_delete", observedAt));
+    }
+    else if (!isTerminalStatusLike(run.status)) {
+        blockers.push(blocker("non_terminal", observedAt));
+    }
+    if (run.held) {
+        blockers.push(blocker("held", observedAt));
+    }
+    if (run.retentionExempt) {
+        blockers.push(blocker("retention_exempt", observedAt));
+    }
+    if (run.unresolvedCleanup) {
+        blockers.push(blocker("unresolved_cleanup", observedAt));
+    }
+    if (run.unresolvedCustody) {
+        blockers.push(blocker("unresolved_custody", observedAt));
+    }
+}
+function blocker(code, observedAt) {
+    return Object.freeze({ code, observedAt });
+}
+function isTerminalStatusLike(status) {
+    return isTerminalRunStatus(status);
+}
+function addDaysIso(timestamp, days) {
+    const start = Date.parse(assertTimestamp(timestamp, "candidate.run.terminalAt"));
+    const end = start + positiveInteger(days, "policy.retentionDays") * 24 * 60 * 60 * 1000;
+    return new Date(end).toISOString();
+}
+function visitRetentionValue(input, path, findings) {
+    if (typeof input === "string") {
+        scanStringValue(input, path, findings);
+        return;
+    }
+    if (Array.isArray(input)) {
+        input.forEach((value, index) => visitRetentionValue(value, `${path}[${index}]`, findings));
+        return;
+    }
+    if (!input || typeof input !== "object") {
+        return;
+    }
+    for (const [key, value] of Object.entries(input)) {
+        const childPath = `${path}.${key}`;
+        if (isForbiddenRetentionFieldName(key)) {
+            findings.push(Object.freeze({ path: childPath, reason: "forbidden_field_name" }));
+        }
+        visitRetentionValue(value, childPath, findings);
+    }
+}
+function scanStringValue(value, path, findings) {
+    for (const pattern of forbiddenStringPatterns) {
+        if (pattern.regex.test(value)) {
+            findings.push(Object.freeze({
+                path,
+                reason: pattern.reason,
+                valueLength: value.length
+            }));
+        }
+    }
+}
+const forbiddenStringPatterns = Object.freeze([
+    { reason: "signed_url", regex: /[?&](?:X-Amz-Signature|X-Amz-Credential|X-Amz-Algorithm|AWSAccessKeyId)=/i },
+    { reason: "r2_object_key", regex: /(^|[\s"'`])(?:runs|assets)\/[^?<#\s"'`]+/i },
+    { reason: "vault_id", regex: /\b(?:vault|vlt|secret)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i },
+    {
+        reason: "private_resource_handle",
+        regex: /\b(?:machine|session|resource|handle|provider|asset)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i
+    },
+    { reason: "hash_like_value", regex: /\b(?:sha256|hash)[:_-][A-Fa-f0-9]{16,}\b/ }
+]);
+function isForbiddenRetentionFieldName(key) {
+    return /^(path|paths|objectKey|objectKeys|r2Key|r2Keys|fileName|filename|filenames|size|sizes|bytes|byteCount|hash|hashes|providerId|providerIds|vaultId|vaultIds|resourceId|resourceIds|handle|handles|signedUrl|signedUrls|url|urls)$/i.test(key);
+}
+function assertSafeIdentifier(value, field) {
+    assertNonEmptyString(value, field);
+    if (!/^[A-Za-z0-9._:-]+$/.test(value)) {
+        throw new RunRetentionValidationError(`run retention ${field} must be an opaque identifier without path separators`);
+    }
+    assertPublicSafeRunRetentionPayload(value);
+    return value;
+}
+function assertSafeMetadataString(value, field) {
+    assertNonEmptyString(value, field);
+    assertPublicSafeRunRetentionPayload(value);
+    return value;
+}
+function assertNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new RunRetentionValidationError(`run retention ${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 RunRetentionValidationError(`run retention ${field} must be an ISO timestamp string`);
+    }
+    return value;
+}
+function nonNegativeInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RunRetentionValidationError(`run retention ${field} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function positiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RunRetentionValidationError(`run retention ${field} must be a positive safe integer`);
+    }
+    return value;
+}
+function formatFindingPaths(findings) {
+    return findings.map((finding) => `${finding.path} (${finding.reason})`).join(", ");
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+//# sourceMappingURL=run-retention.js.map

package/dist/_contracts/run-unit.d.ts

@@ -0,0 +1,194 @@
+/**
+ * RunUnit — the self-contained read shape of a run.
+ *
+ * One canonical struct that captures every non-secret artifact persisted
+ * for a single run: parsed submission inputs, status/lifecycle, attempts,
+ * indexed events, raw-event Storage manifest, outputs (+ capture
+ * failures), proxy-call audit log, pinned workspace skills, provider
+ * built-in skills, and transient (Anthropic Files) skill records.
+ *
+ * Wire contract for `GET /api/runs/:runId`, the per-run archive's
+ * `run.json`/`submission.json`/`caps.json`, and the SDK/CLI
+ * `client.runs.get(runId)` return type.
+ *
+ * Immutability: every field here is read-only. Edit endpoints do not
+ * exist by design.
+ *
+ * Raw event payloads are not embedded in this struct. They live in
+ * private object storage as gzipped JSONL pages and are listed via
+ * `rawEventPages` (manifest only; bytes downloaded out-of-band so the
+ * detail response stays bounded). The archive zip carries the bytes.
+ */
+import type { CleanupStatus } from "./status.js";
+import type { JsonValue, PlatformSubmission, PlatformProxyEndpoint } from "./submission.js";
+/**
+ * Parsed view of the legacy run snapshot jsonb. Stored shape is
+ * `{kind:"submission", submission}` written by the hosted API's
+ * server-side run creation for all runs.
+ */
+export type RunUnitSubmission = RunUnitFlatSubmission;
+export interface RunUnitFlatSubmission {
+    readonly kind: "submission";
+    readonly submission: PlatformSubmission;
+}
+export interface RunUnitAttempt {
+    readonly id: string;
+    readonly attemptNumber: number;
+    readonly status: string;
+    readonly providerSessionId?: string;
+    readonly errorClass?: string;
+    readonly errorCode?: string;
+    readonly errorMessage?: string;
+    readonly startedAt?: string;
+    readonly terminalAt?: string;
+    readonly createdAt: string;
+}
+/**
+ * Indexed event metadata (dedupe-key + summary). Raw payload bytes for
+ * each event are NOT here — they ride in `rawEventPages`. This struct
+ * stays small so the detail response is bounded.
+ */
+export interface RunUnitEvent {
+    readonly id: string;
+    readonly attemptId?: string;
+    readonly providerEventId?: string;
+    readonly type: string;
+    readonly summary?: string;
+    readonly occurredAt?: string;
+    readonly processedAt: string;
+    readonly usageDelta?: Record<string, JsonValue>;
+}
+/**
+ * Inline slice of events plus an optional cursor for the tail. Most
+ * runs fit entirely inline; long-running ones overflow and the
+ * consumer paginates via `GET /api/runs/:runId/events?cursor=...`.
+ */
+export interface RunUnitEventPage {
+    readonly entries: readonly RunUnitEvent[];
+    readonly totalCount: number;
+    readonly truncated: boolean;
+    readonly nextCursor?: string;
+}
+/**
+ * One gzipped JSONL page of raw provider events captured to Storage.
+ * Bytes are downloaded via signed URL or surfaced inside the per-run
+ * archive zip. `storagePath` is bucket-relative; the BFF turns it
+ * into a signed URL for clients.
+ */
+export interface RunUnitRawEventPage {
+    readonly attempt: number;
+    readonly page: number;
+    readonly byteSize: number;
+    readonly eventCount: number;
+    readonly storagePath: string;
+    readonly contentEncoding: "gzip";
+    readonly createdAt: string;
+}
+export interface RunUnitOutput {
+    readonly id: string;
+    readonly fileName: string;
+    readonly byteSize: number;
+    readonly contentType?: string;
+}
+export interface RunUnitOutputCaptureFailure {
+    readonly id: string;
+    readonly providerFileId?: string;
+    readonly filename?: string;
+    readonly byteSize?: number;
+    readonly reason: string;
+    readonly errorMessage?: string;
+    readonly createdAt: string;
+}
+export interface RunUnitProxyCall {
+    readonly id: string;
+    readonly endpointName: string;
+    readonly method: string;
+    readonly requestPathRedacted: string | null;
+    readonly requestByteSize: number;
+    readonly responseStatus: number | null;
+    readonly responseByteSize: number;
+    readonly outcome: string;
+    readonly errorClass: string | null;
+    readonly startedAt: string;
+    readonly finishedAt: string | null;
+    readonly durationMs: number | null;
+}
+export interface RunUnitProxyCallPage {
+    readonly entries: readonly RunUnitProxyCall[];
+    readonly totalCount: number;
+    readonly truncated: boolean;
+    readonly nextCursor?: string;
+}
+/**
+ * Workspace skill bundle pinned at submission. `liveSkillId` is `null`
+ * when the corresponding `skill_bundles` row has been soft-deleted —
+ * the UI uses that to render a tombstoned link.
+ */
+export interface RunUnitSkillSnapshot {
+    readonly skillId: string;
+    readonly name: string;
+    readonly hash: string;
+    readonly sizeBytes: number;
+    readonly fileCount: number;
+    readonly liveSkillId: string | null;
+}
+export interface RunUnitProviderSkill {
+    readonly vendor: string;
+    readonly skillId: string;
+    readonly version?: string;
+}
+export interface RunUnitInlineSkill {
+    readonly id: string;
+    readonly slotId: string;
+    readonly skillName: string;
+    readonly contentHash: string;
+    readonly anthropicFileId: string | null;
+    readonly status: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface RunUnit {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly status: string;
+    readonly lifecyclePhase?: string;
+    readonly cleanupStatus: CleanupStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly startedAt?: string;
+    readonly terminalAt?: string;
+    readonly deletedAt?: string;
+    readonly attemptCount: number;
+    readonly submission: RunUnitSubmission;
+    readonly capsSnapshot?: Record<string, JsonValue>;
+    readonly proxyEndpointsSnapshot?: readonly PlatformProxyEndpoint[];
+    readonly attempts: readonly RunUnitAttempt[];
+    readonly events: RunUnitEventPage;
+    readonly rawEventPages: readonly RunUnitRawEventPage[];
+    readonly outputs: readonly RunUnitOutput[];
+    readonly outputCaptureFailures: readonly RunUnitOutputCaptureFailure[];
+    readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
+    readonly proxyCalls: RunUnitProxyCallPage;
+    readonly skillSnapshots: readonly RunUnitSkillSnapshot[];
+    readonly providerSkills: readonly RunUnitProviderSkill[];
+    readonly inlineSkills: readonly RunUnitInlineSkill[];
+    /**
+     * Per-run, per-provider runtime manifest — derived from the validated
+     * submission + the chosen provider (`buildRuntimeManifest`). Tells
+     * SDK consumers where aex placed things in-container and what
+     * env vars the agent will see. Undefined on responses from BFFs
+     * that predate Phase 2 of the runtime-environment rollout.
+     */
+    readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
+}
+/**
+ * Parse a legacy run snapshot jsonb payload into the typed flat
+ * submission. Never throws on minor unknown keys so we can
+ * forward-compat with worker-side enrichment.
+ *
+ * Returns a typed shape even for malformed snapshots — the worst case
+ * is `{kind: "submission", submission: {model: "", ...}}` with empty
+ * defaults — because the dashboard must still render *something* for a
+ * buggy historical row rather than 500ing the whole detail page.
+ */
+export declare function parseRunUnitSubmission(input: unknown): RunUnitSubmission;