@aexhq/sdk 0.25.0 → 0.25.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +2 -2
  2. package/dist/_contracts/event-stream-client.js +4 -2
  3. package/dist/_contracts/index.d.ts +0 -1
  4. package/dist/_contracts/index.js +0 -1
  5. package/dist/_contracts/operations.d.ts +11 -3
  6. package/dist/_contracts/operations.js +216 -6
  7. package/dist/_contracts/provider-support.d.ts +2 -13
  8. package/dist/_contracts/provider-support.js +2 -14
  9. package/dist/_contracts/proxy-protocol.d.ts +4 -2
  10. package/dist/_contracts/proxy-protocol.js +10 -3
  11. package/dist/_contracts/run-config.d.ts +7 -5
  12. package/dist/_contracts/run-config.js +10 -7
  13. package/dist/_contracts/run-cost.d.ts +3 -11
  14. package/dist/_contracts/run-cost.js +2 -57
  15. package/dist/_contracts/run-custody.d.ts +1 -52
  16. package/dist/_contracts/run-custody.js +3 -87
  17. package/dist/_contracts/run-retention.d.ts +1 -5
  18. package/dist/_contracts/run-retention.js +2 -14
  19. package/dist/_contracts/run-unit.d.ts +2 -2
  20. package/dist/_contracts/runtime-security-profile.js +1 -1
  21. package/dist/_contracts/runtime-types.d.ts +36 -10
  22. package/dist/_contracts/side-effect-audit.d.ts +4 -5
  23. package/dist/_contracts/side-effect-audit.js +1 -4
  24. package/dist/_contracts/status.d.ts +3 -4
  25. package/dist/_contracts/status.js +3 -8
  26. package/dist/_contracts/submission.d.ts +97 -42
  27. package/dist/_contracts/submission.js +109 -29
  28. package/dist/cli.mjs +256 -48
  29. package/dist/cli.mjs.sha256 +1 -1
  30. package/dist/client.d.ts +25 -17
  31. package/dist/client.js +29 -10
  32. package/dist/client.js.map +1 -1
  33. package/dist/index.d.ts +5 -5
  34. package/dist/index.js +4 -4
  35. package/dist/index.js.map +1 -1
  36. package/dist/version.d.ts +1 -1
  37. package/dist/version.js +1 -1
  38. package/docs/concepts/agent-tools.md +30 -23
  39. package/docs/concepts/runs.md +6 -0
  40. package/docs/credentials.md +5 -3
  41. package/docs/events.md +18 -0
  42. package/docs/limits.md +10 -1
  43. package/docs/outputs.md +58 -0
  44. package/docs/provider-runtime-capabilities.md +1 -1
  45. package/docs/public-surface.json +1 -1
  46. package/docs/release.md +1 -1
  47. package/docs/run-config.md +7 -2
  48. package/docs/skills.md +9 -8
  49. package/docs/vision-skills.md +11 -13
  50. package/package.json +2 -2
  51. package/dist/_contracts/managed-key.d.ts +0 -101
  52. package/dist/_contracts/managed-key.js +0 -181
@@ -1,14 +1,13 @@
1
- import type { CredentialMode } from "./managed-key.js";
2
- import type { RunProvider, RuntimeKind } from "./submission.js";
1
+ import type { CredentialMode, RunProvider, RuntimeKind } from "./submission.js";
3
2
  export declare const RUN_COST_TELEMETRY_SCHEMA_VERSION = 1;
4
3
  export declare const RUN_USAGE_SAMPLE_SCHEMA_VERSION = 1;
5
4
  export declare const RUN_COST_SUMMARY_STATUSES: readonly ["pending", "partial", "complete", "unavailable", "not_applicable"];
6
5
  export type RunCostSummaryStatus = (typeof RUN_COST_SUMMARY_STATUSES)[number];
7
6
  export declare const RUN_USAGE_SAMPLE_UNITS: readonly ["token", "millisecond", "byte", "byte_millisecond", "count", "file", "credit_unit"];
8
7
  export type RunUsageSampleUnit = (typeof RUN_USAGE_SAMPLE_UNITS)[number];
9
- export declare const RUN_USAGE_SAMPLE_SOURCE_TYPES: readonly ["coordinator-event", "run-event", "usage-ledger", "output-object", "proxy-call", "runtime-job", "provider-session", "storage-accrual", "billing-reservation", "billing-settlement", "billing-release", "manual-adjustment"];
8
+ export declare const RUN_USAGE_SAMPLE_SOURCE_TYPES: readonly ["coordinator-event", "run-event", "usage-ledger", "output-object", "proxy-call", "runtime-job", "provider-session", "storage-accrual", "manual-adjustment"];
10
9
  export type RunUsageSampleSourceType = (typeof RUN_USAGE_SAMPLE_SOURCE_TYPES)[number];
11
- export declare const RUN_USAGE_SAMPLE_METRICS: readonly ["provider.input_tokens", "provider.output_tokens", "provider.cache_read_input_tokens", "provider.cache_creation_input_tokens", "provider.total_tokens", "runtime.queued_ms", "runtime.active_ms", "runtime.output_capture_ms", "runtime.cleanup_ms", "run.total_ms", "output.discovered_files", "output.captured_files", "output.failed_files", "output.captured_bytes", "retry.runtime_attempts", "retry.provider_poll", "retry.output_capture", "retry.output_upload", "capture.uploaded_files", "capture.failed_files", "capture.total_bytes", "storage.current_bytes", "storage.byte_milliseconds", "proxy.call_count", "proxy.failed_call_count", "proxy.request_bytes", "proxy.response_bytes", "proxy.duration_ms", "managed_key.reserved_credit_units", "managed_key.charged_credit_units", "managed_key.released_credit_units"];
10
+ export declare const RUN_USAGE_SAMPLE_METRICS: readonly ["provider.input_tokens", "provider.output_tokens", "provider.cache_read_input_tokens", "provider.cache_creation_input_tokens", "provider.total_tokens", "runtime.queued_ms", "runtime.active_ms", "runtime.output_capture_ms", "runtime.cleanup_ms", "run.total_ms", "output.discovered_files", "output.captured_files", "output.failed_files", "output.captured_bytes", "retry.runtime_attempts", "retry.provider_poll", "retry.output_capture", "retry.output_upload", "capture.uploaded_files", "capture.failed_files", "capture.total_bytes", "storage.current_bytes", "storage.byte_milliseconds", "proxy.call_count", "proxy.failed_call_count", "proxy.request_bytes", "proxy.response_bytes", "proxy.duration_ms"];
12
11
  export type RunUsageSampleMetric = (typeof RUN_USAGE_SAMPLE_METRICS)[number];
13
12
  export interface RunUsageSampleSource {
14
13
  readonly type: RunUsageSampleSourceType;
@@ -86,12 +85,6 @@ export interface RunCostProxyTelemetry {
86
85
  readonly responseBytes?: number;
87
86
  readonly durationMs?: number;
88
87
  }
89
- export interface RunCostManagedKeyBudgetTelemetry {
90
- readonly credentialMode?: CredentialMode;
91
- readonly reservedCreditUnits?: number;
92
- readonly chargedCreditUnits?: number;
93
- readonly releasedCreditUnits?: number;
94
- }
95
88
  /**
96
89
  * The basis for a {@link RunCostTelemetry.billedCostUsd}: an honest marker of
97
90
  * whether the figure is a settle-time ESTIMATE or has been RECONCILED against
@@ -122,7 +115,6 @@ export interface RunCostTelemetry {
122
115
  readonly providerUsage?: readonly RunCostProviderUsage[];
123
116
  readonly storage?: RunCostStorageTelemetry;
124
117
  readonly proxy?: RunCostProxyTelemetry;
125
- readonly managedKey?: RunCostManagedKeyBudgetTelemetry;
126
118
  /**
127
119
  * Customer-facing AEX cost of serving this run, USD — a REPORTED ESTIMATE,
128
120
  * not a charge (telemetry/showback only; no invoicing or credit deduction).
@@ -25,9 +25,6 @@ export const RUN_USAGE_SAMPLE_SOURCE_TYPES = [
25
25
  "runtime-job",
26
26
  "provider-session",
27
27
  "storage-accrual",
28
- "billing-reservation",
29
- "billing-settlement",
30
- "billing-release",
31
28
  "manual-adjustment"
32
29
  ];
33
30
  export const RUN_USAGE_SAMPLE_METRICS = [
@@ -58,10 +55,7 @@ export const RUN_USAGE_SAMPLE_METRICS = [
58
55
  "proxy.failed_call_count",
59
56
  "proxy.request_bytes",
60
57
  "proxy.response_bytes",
61
- "proxy.duration_ms",
62
- "managed_key.reserved_credit_units",
63
- "managed_key.charged_credit_units",
64
- "managed_key.released_credit_units"
58
+ "proxy.duration_ms"
65
59
  ];
66
60
  const RUN_USAGE_SAMPLE_METRIC_UNITS = {
67
61
  "provider.input_tokens": "token",
@@ -91,10 +85,7 @@ const RUN_USAGE_SAMPLE_METRIC_UNITS = {
91
85
  "proxy.failed_call_count": "count",
92
86
  "proxy.request_bytes": "byte",
93
87
  "proxy.response_bytes": "byte",
94
- "proxy.duration_ms": "millisecond",
95
- "managed_key.reserved_credit_units": "credit_unit",
96
- "managed_key.charged_credit_units": "credit_unit",
97
- "managed_key.released_credit_units": "credit_unit"
88
+ "proxy.duration_ms": "millisecond"
98
89
  };
99
90
  /**
100
91
  * The basis for a {@link RunCostTelemetry.billedCostUsd}: an honest marker of
@@ -144,7 +135,6 @@ export function buildRunCostTelemetry(input) {
144
135
  ...(input.providerUsage ? { providerUsage: input.providerUsage.map(normalizeProviderUsage) } : {}),
145
136
  ...(input.storage ? { storage: normalizeStorage(input.storage) } : {}),
146
137
  ...(input.proxy ? { proxy: normalizeProxy(input.proxy) } : {}),
147
- ...(input.managedKey ? { managedKey: normalizeManagedKey(input.managedKey) } : {}),
148
138
  ...(input.billedCostUsd !== undefined ? { billedCostUsd: nonNegativeFinite(input.billedCostUsd, "billedCostUsd") } : {}),
149
139
  ...(input.costBasis ? { costBasis: normalizeCostBasis(input.costBasis) } : {})
150
140
  });
@@ -170,10 +160,8 @@ export function buildRunCostTelemetryFromUsageSamples(input) {
170
160
  const capture = {};
171
161
  const storage = {};
172
162
  const proxy = {};
173
- const managedKey = {};
174
163
  const providerUsage = new Map();
175
164
  let captureAttempted = false;
176
- let managedKeyCredentialMode;
177
165
  for (const sample of samples) {
178
166
  switch (sample.metric) {
179
167
  case "provider.input_tokens":
@@ -263,18 +251,6 @@ export function buildRunCostTelemetryFromUsageSamples(input) {
263
251
  case "proxy.duration_ms":
264
252
  addDraftNumber(proxy, "durationMs", sample.quantity);
265
253
  break;
266
- case "managed_key.reserved_credit_units":
267
- managedKeyCredentialMode = sample.credentialMode ?? managedKeyCredentialMode;
268
- addDraftNumber(managedKey, "reservedCreditUnits", sample.quantity);
269
- break;
270
- case "managed_key.charged_credit_units":
271
- managedKeyCredentialMode = sample.credentialMode ?? managedKeyCredentialMode;
272
- addDraftNumber(managedKey, "chargedCreditUnits", sample.quantity);
273
- break;
274
- case "managed_key.released_credit_units":
275
- managedKeyCredentialMode = sample.credentialMode ?? managedKeyCredentialMode;
276
- addDraftNumber(managedKey, "releasedCreditUnits", sample.quantity);
277
- break;
278
254
  }
279
255
  }
280
256
  if (Object.keys(durations).length > 0)
@@ -293,12 +269,6 @@ export function buildRunCostTelemetryFromUsageSamples(input) {
293
269
  telemetry.storage = storage;
294
270
  if (Object.keys(proxy).length > 0)
295
271
  telemetry.proxy = proxy;
296
- if (Object.keys(managedKey).length > 0 || managedKeyCredentialMode) {
297
- telemetry.managedKey = {
298
- ...(managedKeyCredentialMode ? { credentialMode: managedKeyCredentialMode } : {}),
299
- ...managedKey
300
- };
301
- }
302
272
  return buildRunCostTelemetry(telemetry);
303
273
  }
304
274
  export function summarizeUsageSamples(samples) {
@@ -329,7 +299,6 @@ export function mergeRunCostTelemetry(base, next) {
329
299
  const providerUsage = [...(base.providerUsage ?? []), ...(patch.providerUsage ?? [])];
330
300
  const storage = sumStorage(base.storage, patch.storage);
331
301
  const proxy = sumProxy(base.proxy, patch.proxy);
332
- const managedKey = mergeManagedKey(base.managedKey, patch.managedKey);
333
302
  // Derived cost fields are LAST-WRITER-WINS (a re-derivation supersedes the
334
303
  // prior estimate), not summed — they are projections of the whole sample set,
335
304
  // not additive metrics.
@@ -361,8 +330,6 @@ export function mergeRunCostTelemetry(base, next) {
361
330
  merged.storage = storage;
362
331
  if (proxy)
363
332
  merged.proxy = proxy;
364
- if (managedKey)
365
- merged.managedKey = managedKey;
366
333
  if (billedCostUsd !== undefined)
367
334
  merged.billedCostUsd = billedCostUsd;
368
335
  if (costBasis)
@@ -435,16 +402,6 @@ function normalizeProxy(input) {
435
402
  durationMs: input.durationMs
436
403
  });
437
404
  }
438
- function normalizeManagedKey(input) {
439
- return Object.freeze({
440
- ...(input.credentialMode ? { credentialMode: input.credentialMode } : {}),
441
- ...freezeOptionalNumbers({
442
- reservedCreditUnits: input.reservedCreditUnits,
443
- chargedCreditUnits: input.chargedCreditUnits,
444
- releasedCreditUnits: input.releasedCreditUnits
445
- })
446
- });
447
- }
448
405
  function normalizeSourceSummary(input) {
449
406
  return Object.freeze({
450
407
  sampleCount: nonNegativeFinite(input.sampleCount, "sourceSummary.sampleCount"),
@@ -599,18 +556,6 @@ function mergeCapture(base, next) {
599
556
  ...(failureReasons.length > 0 ? { failureReasons } : {})
600
557
  });
601
558
  }
602
- function mergeManagedKey(base, next) {
603
- if (!base && !next) {
604
- return undefined;
605
- }
606
- const credentialMode = next?.credentialMode ?? base?.credentialMode;
607
- return normalizeManagedKey({
608
- ...(credentialMode ? { credentialMode } : {}),
609
- reservedCreditUnits: (base?.reservedCreditUnits ?? 0) + (next?.reservedCreditUnits ?? 0),
610
- chargedCreditUnits: (base?.chargedCreditUnits ?? 0) + (next?.chargedCreditUnits ?? 0),
611
- releasedCreditUnits: (base?.releasedCreditUnits ?? 0) + (next?.releasedCreditUnits ?? 0)
612
- });
613
- }
614
559
  function mergeSourceSummary(base, next) {
615
560
  if (!base && !next) {
616
561
  return undefined;
@@ -1,11 +1,8 @@
1
- import type { CredentialMode } from "./managed-key.js";
2
1
  import type { RunStatus } from "./status.js";
3
- import type { RunProvider, RuntimeKind } from "./submission.js";
2
+ import type { CredentialMode, RunProvider, RuntimeKind } from "./submission.js";
4
3
  export declare const CUSTODY_MANIFEST_SCHEMA_VERSION = 1;
5
- export declare const CUSTODY_TOMBSTONE_SCHEMA_VERSION = 1;
6
4
  export declare const CUSTODY_REDACTION_SCANNER_VERSION = 1;
7
5
  export declare const CUSTODY_MANIFEST_KIND = "aex.custody_manifest.v1";
8
- export declare const CUSTODY_TOMBSTONE_KIND = "aex.custody_tombstone.v1";
9
6
  export declare const CUSTODY_MANIFEST_CONTENT_TYPE = "application/json; charset=utf-8";
10
7
  export declare const CUSTODY_MANIFEST_RUN_REL_PATH = "metadata/custody.json";
11
8
  export declare const CUSTODY_SECRET_CLASSES: readonly ["provider_api_key", "mcp_credential", "proxy_endpoint_auth", "runner_bearer", "managed_system_credential"];
@@ -26,10 +23,6 @@ export declare const CUSTODY_EVIDENCE_SOURCES: readonly ["run_row", "runtime_man
26
23
  export type CustodyEvidenceSource = (typeof CUSTODY_EVIDENCE_SOURCES)[number];
27
24
  export declare const CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES: readonly ["raw_secret_values", "bearer_hashes", "provider_response_bodies", "signed_urls", "object_store_keys", "vault_ids", "private_resource_handles"];
28
25
  export type CustodyManifestExcludedValueClass = (typeof CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES)[number];
29
- export declare const CUSTODY_TOMBSTONE_MANIFEST_STATUSES: readonly ["written", "not_written", "write_failed", "purged"];
30
- export type CustodyTombstoneManifestStatus = (typeof CUSTODY_TOMBSTONE_MANIFEST_STATUSES)[number];
31
- export declare const CUSTODY_TOMBSTONE_DELETION_STATUSES: readonly ["not_deleted", "pending_delete", "deleted"];
32
- export type CustodyTombstoneDeletionStatus = (typeof CUSTODY_TOMBSTONE_DELETION_STATUSES)[number];
33
26
  export interface CustodyManifestRunV1 {
34
27
  readonly runId: string;
35
28
  readonly workspaceId: string;
@@ -137,48 +130,6 @@ export interface CustodyManifestInput {
137
130
  readonly resources?: readonly CustodyManifestResourceClassInput[];
138
131
  readonly cleanup?: CustodyManifestCleanupInput;
139
132
  }
140
- export interface CustodyTombstoneRunV1 {
141
- readonly runId: string;
142
- readonly workspaceId: string;
143
- readonly terminalStatus: RunStatus | string;
144
- readonly terminalAt?: string;
145
- }
146
- export interface CustodyTombstoneManifestV1 {
147
- readonly schemaVersion: typeof CUSTODY_MANIFEST_SCHEMA_VERSION;
148
- readonly status: CustodyTombstoneManifestStatus;
149
- readonly generatedAt?: string;
150
- readonly finalizedAt?: string;
151
- readonly tombstonedAt: string;
152
- }
153
- export interface CustodyTombstoneDeletionV1 {
154
- readonly status: CustodyTombstoneDeletionStatus;
155
- readonly pendingAt?: string;
156
- readonly deletedAt?: string;
157
- }
158
- export interface CustodyTombstoneRetentionV1 {
159
- readonly defaultPolicy: "retain_indefinitely";
160
- readonly userAction: "purge_or_anonymize_later";
161
- }
162
- export interface CustodyTombstoneV1 {
163
- readonly schemaVersion: typeof CUSTODY_TOMBSTONE_SCHEMA_VERSION;
164
- readonly kind: typeof CUSTODY_TOMBSTONE_KIND;
165
- readonly run: CustodyTombstoneRunV1;
166
- readonly manifest: CustodyTombstoneManifestV1;
167
- readonly summary: CustodyManifestSummaryV1;
168
- readonly deletion: CustodyTombstoneDeletionV1;
169
- readonly retention: CustodyTombstoneRetentionV1;
170
- }
171
- export interface CustodyTombstoneInput {
172
- readonly run: CustodyTombstoneRunV1;
173
- readonly manifest: Omit<CustodyTombstoneManifestV1, "schemaVersion">;
174
- readonly summary: CustodyManifestSummaryV1;
175
- readonly deletion?: CustodyTombstoneDeletionV1;
176
- }
177
- export interface CustodyTombstoneFromManifestInput {
178
- readonly manifestStatus?: CustodyTombstoneManifestStatus;
179
- readonly tombstonedAt: string;
180
- readonly deletion?: CustodyTombstoneDeletionV1;
181
- }
182
133
  export interface CustodyManifestWriteObject {
183
134
  readonly key: string;
184
135
  readonly contentType: typeof CUSTODY_MANIFEST_CONTENT_TYPE;
@@ -220,7 +171,5 @@ export declare function custodyManifestObjectKey(runId: string): string;
220
171
  export declare function createCustodyManifestWriter(store: CustodyManifestObjectStore): CustodyManifestWriter;
221
172
  export declare function writeCustodyManifest(store: CustodyManifestObjectStore, input: CustodyManifestInput): Promise<CustodyManifestWriteResult>;
222
173
  export declare function buildCustodyManifest(input: CustodyManifestInput): CustodyManifestV1;
223
- export declare function buildCustodyTombstone(input: CustodyTombstoneInput): CustodyTombstoneV1;
224
- export declare function buildCustodyTombstoneFromManifest(manifest: CustodyManifestV1, input: CustodyTombstoneFromManifestInput): CustodyTombstoneV1;
225
174
  export declare function scanCustodyPayloadForSensitiveValues(input: unknown): readonly CustodyRedactionFinding[];
226
175
  export declare function assertPublicSafeCustodyPayload(input: unknown): void;
@@ -1,8 +1,6 @@
1
1
  export const CUSTODY_MANIFEST_SCHEMA_VERSION = 1;
2
- export const CUSTODY_TOMBSTONE_SCHEMA_VERSION = 1;
3
2
  export const CUSTODY_REDACTION_SCANNER_VERSION = 1;
4
3
  export const CUSTODY_MANIFEST_KIND = "aex.custody_manifest.v1";
5
- export const CUSTODY_TOMBSTONE_KIND = "aex.custody_tombstone.v1";
6
4
  export const CUSTODY_MANIFEST_CONTENT_TYPE = "application/json; charset=utf-8";
7
5
  export const CUSTODY_MANIFEST_RUN_REL_PATH = "metadata/custody.json";
8
6
  export const CUSTODY_SECRET_CLASSES = [
@@ -88,17 +86,6 @@ export const CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES = [
88
86
  "vault_ids",
89
87
  "private_resource_handles"
90
88
  ];
91
- export const CUSTODY_TOMBSTONE_MANIFEST_STATUSES = [
92
- "written",
93
- "not_written",
94
- "write_failed",
95
- "purged"
96
- ];
97
- export const CUSTODY_TOMBSTONE_DELETION_STATUSES = [
98
- "not_deleted",
99
- "pending_delete",
100
- "deleted"
101
- ];
102
89
  export class CustodyManifestRedactionError extends Error {
103
90
  code = "custody_manifest_not_public_safe";
104
91
  findings;
@@ -176,40 +163,6 @@ export function buildCustodyManifest(input) {
176
163
  assertPublicSafeCustodyPayload(manifest);
177
164
  return manifest;
178
165
  }
179
- export function buildCustodyTombstone(input) {
180
- const tombstone = Object.freeze({
181
- schemaVersion: CUSTODY_TOMBSTONE_SCHEMA_VERSION,
182
- kind: CUSTODY_TOMBSTONE_KIND,
183
- run: normalizeTombstoneRun(input.run),
184
- manifest: normalizeTombstoneManifest(input.manifest),
185
- summary: normalizeSummary(input.summary),
186
- deletion: normalizeTombstoneDeletion(input.deletion ?? { status: "not_deleted" }),
187
- retention: Object.freeze({
188
- defaultPolicy: "retain_indefinitely",
189
- userAction: "purge_or_anonymize_later"
190
- })
191
- });
192
- assertPublicSafeCustodyPayload(tombstone);
193
- return tombstone;
194
- }
195
- export function buildCustodyTombstoneFromManifest(manifest, input) {
196
- return buildCustodyTombstone({
197
- run: {
198
- runId: manifest.run.runId,
199
- workspaceId: manifest.run.workspaceId,
200
- terminalStatus: manifest.run.terminalStatus,
201
- ...(manifest.run.terminalAt ? { terminalAt: manifest.run.terminalAt } : {})
202
- },
203
- manifest: {
204
- status: input.manifestStatus ?? "written",
205
- generatedAt: manifest.generatedAt,
206
- ...(manifest.finalizedAt ? { finalizedAt: manifest.finalizedAt } : {}),
207
- tombstonedAt: input.tombstonedAt
208
- },
209
- summary: manifest.summary,
210
- ...(input.deletion ? { deletion: input.deletion } : {})
211
- });
212
- }
213
166
  export function scanCustodyPayloadForSensitiveValues(input) {
214
167
  const findings = [];
215
168
  visitCustodyValue(input, "$", findings);
@@ -351,30 +304,6 @@ function normalizeSummary(input) {
351
304
  ])))
352
305
  });
353
306
  }
354
- function normalizeTombstoneRun(input) {
355
- return Object.freeze({
356
- runId: assertSafeIdentifier(input.runId, "tombstone.run.runId"),
357
- workspaceId: assertSafeIdentifier(input.workspaceId, "tombstone.run.workspaceId"),
358
- terminalStatus: assertSafeMetadataString(input.terminalStatus, "tombstone.run.terminalStatus"),
359
- ...(input.terminalAt ? { terminalAt: assertTimestamp(input.terminalAt, "tombstone.run.terminalAt") } : {})
360
- });
361
- }
362
- function normalizeTombstoneManifest(input) {
363
- return Object.freeze({
364
- schemaVersion: CUSTODY_MANIFEST_SCHEMA_VERSION,
365
- status: input.status,
366
- ...(input.generatedAt ? { generatedAt: assertTimestamp(input.generatedAt, "tombstone.manifest.generatedAt") } : {}),
367
- ...(input.finalizedAt ? { finalizedAt: assertTimestamp(input.finalizedAt, "tombstone.manifest.finalizedAt") } : {}),
368
- tombstonedAt: assertTimestamp(input.tombstonedAt, "tombstone.manifest.tombstonedAt")
369
- });
370
- }
371
- function normalizeTombstoneDeletion(input) {
372
- return Object.freeze({
373
- status: input.status,
374
- ...(input.pendingAt ? { pendingAt: assertTimestamp(input.pendingAt, "tombstone.deletion.pendingAt") } : {}),
375
- ...(input.deletedAt ? { deletedAt: assertTimestamp(input.deletedAt, "tombstone.deletion.deletedAt") } : {})
376
- });
377
- }
378
307
  function visitCustodyValue(input, path, findings) {
379
308
  if (typeof input === "string") {
380
309
  scanStringValue(input, path, findings);
@@ -446,13 +375,9 @@ const forbiddenStringPatterns = Object.freeze([
446
375
  {
447
376
  reason: "private_resource_handle",
448
377
  // `<keyword><sep><id>` opaque handles (`session_a1B2c3D4e5`, `file_9f8e7d…`).
449
- // The keyword set overlaps ordinary English (agent/file/skill/resource/…), so
450
- // the bare shape also matched documentation prose that simply chains those
451
- // words with `_`/`-` (`agent_decision_failure`, `file_grounded`,
452
- // `session_handoff_contract`, `agent-judgment` — read straight out of a
453
- // skill-pack doc in tool-result text). The `accept` predicate keeps the shape
454
- // but requires the id segment to look minted rather than spelled — i.e. carry
455
- // a digit — so genuine handles stay flagged while dictionary-word prose does not.
378
+ // The keyword set overlaps ordinary prose, so require the id segment to
379
+ // carry a digit. That keeps genuine minted handles flagged while avoiding
380
+ // dictionary-word chains such as `agent_decision_failure`.
456
381
  regex: /\b(?:machine|session|agent|file|skill|env|resource|handle|token_hash|bearer_hash)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i,
457
382
  accept: isMintedResourceHandle
458
383
  },
@@ -496,15 +421,6 @@ function isHighEntropySecretRun(run) {
496
421
  }
497
422
  return highEntropyShannonBits(run) >= 3.0;
498
423
  }
499
- /**
500
- * Decide whether a `<keyword><sep><id>` shape-match is a genuinely minted private
501
- * handle rather than dictionary-word prose. The id segment (everything after the
502
- * first `_`/`-`/`:`) must carry a digit — the property that separates a minted
503
- * opaque handle (`session_a1B2c3D4e5`, `file_9f8e7d6c5b4a`, `machine_1234567890`)
504
- * from a chain of English words (`agent_decision_failure`, `file_grounded`). This
505
- * mirrors `isHighEntropySecretRun`'s letter+digit requirement: a prefixless secret
506
- * blob and a minted handle both carry digits; prose does not.
507
- */
508
424
  function isMintedResourceHandle(match) {
509
425
  const separatorIndex = match.search(/[_:-]/);
510
426
  const id = match.slice(separatorIndex + 1);
@@ -10,7 +10,7 @@ export declare const RUN_DELETION_MANIFEST_MODES: readonly ["dry_run", "final"];
10
10
  export type RunDeletionManifestMode = (typeof RUN_DELETION_MANIFEST_MODES)[number];
11
11
  export declare const RUN_DELETION_CANDIDATE_STATUSES: readonly ["selected", "blocked"];
12
12
  export type RunDeletionCandidateStatus = (typeof RUN_DELETION_CANDIDATE_STATUSES)[number];
13
- export declare const RUN_DELETION_BLOCKERS: readonly ["non_terminal", "already_deleted", "concurrent_delete", "retention_policy_disabled", "unexpired", "held", "retention_exempt", "unresolved_cleanup", "unresolved_custody"];
13
+ export declare const RUN_DELETION_BLOCKERS: readonly ["non_terminal", "retention_policy_disabled", "unexpired", "held", "retention_exempt", "unresolved_cleanup", "unresolved_custody"];
14
14
  export type RunDeletionBlocker = (typeof RUN_DELETION_BLOCKERS)[number];
15
15
  export declare const RUN_DELETION_COUNT_CLASSES: readonly ["object_store_objects", "outputs", "logs", "events", "assets", "db_event_rows", "db_output_rows", "capture_failures", "storage_samples", "custody_manifests"];
16
16
  export type RunDeletionCountClass = (typeof RUN_DELETION_COUNT_CLASSES)[number];
@@ -40,8 +40,6 @@ export interface RunDeletionCandidateRunV1 {
40
40
  readonly status: RunStatus | string;
41
41
  readonly createdAt?: string;
42
42
  readonly terminalAt?: string;
43
- readonly pendingDeleteAt?: string;
44
- readonly deletedAt?: string;
45
43
  readonly held?: boolean;
46
44
  readonly retentionExempt?: boolean;
47
45
  readonly unresolvedCleanup?: boolean;
@@ -78,8 +76,6 @@ export interface RunDeletionManifestRunV1 {
78
76
  readonly createdAt?: string;
79
77
  readonly terminalAt?: string;
80
78
  readonly eligibleAt?: string;
81
- readonly pendingDeleteAt?: string;
82
- readonly deletedAt?: string;
83
79
  }
84
80
  export interface RunDeletionManifestRequestV1 {
85
81
  readonly reason: RunDeletionReason;
@@ -9,8 +9,6 @@ export const RUN_DELETION_MANIFEST_MODES = ["dry_run", "final"];
9
9
  export const RUN_DELETION_CANDIDATE_STATUSES = ["selected", "blocked"];
10
10
  export const RUN_DELETION_BLOCKERS = [
11
11
  "non_terminal",
12
- "already_deleted",
13
- "concurrent_delete",
14
12
  "retention_policy_disabled",
15
13
  "unexpired",
16
14
  "held",
@@ -266,8 +264,6 @@ function normalizeCandidateRun(input) {
266
264
  status: assertSafeMetadataString(input.status, "run.status"),
267
265
  ...(input.createdAt ? { createdAt: assertTimestamp(input.createdAt, "run.createdAt") } : {}),
268
266
  ...(input.terminalAt ? { terminalAt: assertTimestamp(input.terminalAt, "run.terminalAt") } : {}),
269
- ...(input.pendingDeleteAt ? { pendingDeleteAt: assertTimestamp(input.pendingDeleteAt, "run.pendingDeleteAt") } : {}),
270
- ...(input.deletedAt ? { deletedAt: assertTimestamp(input.deletedAt, "run.deletedAt") } : {}),
271
267
  ...(input.held !== undefined ? { held: input.held } : {}),
272
268
  ...(input.retentionExempt !== undefined ? { retentionExempt: input.retentionExempt } : {}),
273
269
  ...(input.unresolvedCleanup !== undefined ? { unresolvedCleanup: input.unresolvedCleanup } : {}),
@@ -282,9 +278,7 @@ function normalizeManifestRun(input, eligibleAt) {
282
278
  status: run.status,
283
279
  ...(run.createdAt ? { createdAt: run.createdAt } : {}),
284
280
  ...(run.terminalAt ? { terminalAt: run.terminalAt } : {}),
285
- ...(eligibleAt ? { eligibleAt: assertTimestamp(eligibleAt, "run.eligibleAt") } : {}),
286
- ...(run.pendingDeleteAt ? { pendingDeleteAt: run.pendingDeleteAt } : {}),
287
- ...(run.deletedAt ? { deletedAt: run.deletedAt } : {})
281
+ ...(eligibleAt ? { eligibleAt: assertTimestamp(eligibleAt, "run.eligibleAt") } : {})
288
282
  });
289
283
  }
290
284
  function normalizeRequest(input) {
@@ -360,13 +354,7 @@ function normalizePurgeProof(input) {
360
354
  });
361
355
  }
362
356
  function addRunBlockers(blockers, run, observedAt) {
363
- if (run.status === "deleted") {
364
- blockers.push(blocker("already_deleted", observedAt));
365
- }
366
- else if (run.status === "pending_delete" || run.pendingDeleteAt) {
367
- blockers.push(blocker("concurrent_delete", observedAt));
368
- }
369
- else if (!isTerminalStatusLike(run.status)) {
357
+ if (!isTerminalStatusLike(run.status)) {
370
358
  blockers.push(blocker("non_terminal", observedAt));
371
359
  }
372
360
  if (run.held) {
@@ -120,8 +120,8 @@ export interface RunUnitProxyCallPage {
120
120
  }
121
121
  /**
122
122
  * Workspace skill bundle pinned at submission. `liveSkillId` is `null`
123
- * when the corresponding `skill_bundles` row has been soft-deleted
124
- * the UI uses that to render a tombstoned link.
123
+ * when the corresponding `skill_bundles` row no longer exists after a
124
+ * hard delete; run snapshots keep the submitted metadata.
125
125
  */
126
126
  export interface RunUnitSkillSnapshot {
127
127
  readonly skillId: string;
@@ -11,7 +11,7 @@ export const RUNTIME_SECURITY_PROFILE_CONFIG = Object.freeze({
11
11
  }),
12
12
  standard: Object.freeze({
13
13
  name: "standard",
14
- defaultNetworkingMode: "limited",
14
+ defaultNetworkingMode: "open",
15
15
  allowOpenNetworking: true,
16
16
  allowRuntimePackages: true,
17
17
  allowCustomerEnvVars: true,
@@ -90,7 +90,7 @@ export interface ProviderEvent {
90
90
  }
91
91
  /**
92
92
  * One captured output file as the dashboard reports it. Use
93
- * `createOutputLink` to get a short-lived signed URL for download.
93
+ * `outputLink` / `createOutputLink` to get a temporary direct URL for download.
94
94
  */
95
95
  export interface Output {
96
96
  readonly id: string;
@@ -101,6 +101,25 @@ export interface Output {
101
101
  readonly [key: string]: unknown;
102
102
  }
103
103
  export type OutputFilePathMatch = "exact" | "suffix";
104
+ export type OutputFileType = "text" | "json" | "image" | "audio" | "video" | "pdf" | "archive" | "binary" | "unknown";
105
+ export interface OutputQuery {
106
+ /** Exact normalized output path. Leading `/` and `outputs/` are ignored. */
107
+ readonly path?: string;
108
+ /** Basename match. A RegExp is tested against the basename only. */
109
+ readonly filename?: string | RegExp;
110
+ /**
111
+ * Directory prefix. Leading `/` and `outputs/` are ignored.
112
+ * `recursive` defaults to true.
113
+ */
114
+ readonly dir?: string;
115
+ readonly recursive?: boolean;
116
+ /** File extension, with or without a leading dot. Case-insensitive. */
117
+ readonly extension?: string;
118
+ /** Exact content type or a prefix wildcard such as `image/*`. */
119
+ readonly contentType?: string;
120
+ /** High-level type inferred from content type first, then extension. */
121
+ readonly type?: OutputFileType;
122
+ }
104
123
  export interface OutputFilePathSelector {
105
124
  readonly path: string;
106
125
  readonly match?: OutputFilePathMatch;
@@ -113,11 +132,20 @@ export interface OutputFileDownload {
113
132
  readonly output: Output;
114
133
  readonly bytes: Uint8Array;
115
134
  }
116
- export interface SignedOutputLink {
135
+ export type OutputLinkExpiresIn = number | "15m" | "1h" | "1d";
136
+ export interface OutputLinkOptions {
137
+ /** Seconds or one of the documented presets. Defaults to `"1h"`. */
138
+ readonly expiresIn?: OutputLinkExpiresIn;
139
+ }
140
+ export interface OutputLink {
117
141
  readonly url: string;
118
142
  readonly expiresAt?: string;
143
+ readonly expiresInSeconds?: number;
144
+ readonly output?: Output;
119
145
  readonly [key: string]: unknown;
120
146
  }
147
+ /** @deprecated Renamed to {@link OutputLink}. */
148
+ export type SignedOutputLink = OutputLink;
121
149
  export interface WhoAmI {
122
150
  readonly principalType: "api_token" | "user";
123
151
  readonly workspaceId?: string;
@@ -129,15 +157,16 @@ export interface WhoAmI {
129
157
  * Surfaced so consumers (e.g. broll's app-side admission gate) can
130
158
  * decide whether to keep their own gate or rely on platform headers.
131
159
  * All fields optional — older BFFs may omit. Numbers are concrete
132
- * snapshots at the time of the `whoami` call.
160
+ * snapshots at the time of the `whoami` call; `null` means no app-visible
161
+ * cap is applied for that field.
133
162
  */
134
163
  readonly caps?: {
135
164
  /** Token-bucket cap on POST /api/runs per minute, per workspace. */
136
165
  readonly runSubmitPerMinute?: number;
137
166
  /** Hard cap on concurrent non-terminal runs the workspace may hold. */
138
167
  readonly maxConcurrentRuns?: number;
139
- /** Storage cap (bytes) on captured output objects, workspace-wide. */
140
- readonly storageCapBytes?: number;
168
+ /** Storage cap (bytes) on captured output objects, workspace-wide. `null` means unlimited. */
169
+ readonly storageCapBytes?: number | null;
141
170
  /** Current captured-output usage in bytes. */
142
171
  readonly storageUsedBytes?: number;
143
172
  /**
@@ -154,8 +183,8 @@ export interface WhoAmI {
154
183
  * Workspace skill bundle as the dashboard BFF returns it. Mirrors a row
155
184
  * of `skill_bundles` joined with its computed manifest. `state` is the
156
185
  * upload lifecycle (`pending` -> `ready`); only `ready` rows are
157
- * referenceable from a run. `deletedAt` is the soft-delete tombstone
158
- * (`null` for live bundles).
186
+ * referenceable from a run. Delete is hard; historical runs keep their
187
+ * submit-time snapshots rather than depending on this row.
159
188
  *
160
189
  * See the public architecture notes and server-side persistence schema for
161
190
  * the authoritative shape.
@@ -176,7 +205,6 @@ export interface Skill {
176
205
  readonly createdAt?: string;
177
206
  readonly updatedAt?: string;
178
207
  readonly finalizedAt?: string | null;
179
- readonly deletedAt?: string | null;
180
208
  readonly [key: string]: unknown;
181
209
  }
182
210
  /**
@@ -199,7 +227,6 @@ export interface AgentsMdRecord {
199
227
  readonly createdAt?: string;
200
228
  readonly updatedAt?: string;
201
229
  readonly finalizedAt?: string | null;
202
- readonly deletedAt?: string | null;
203
230
  readonly [key: string]: unknown;
204
231
  }
205
232
  /**
@@ -223,7 +250,6 @@ export interface FileRecord {
223
250
  readonly createdAt?: string;
224
251
  readonly updatedAt?: string;
225
252
  readonly finalizedAt?: string | null;
226
- readonly deletedAt?: string | null;
227
253
  readonly [key: string]: unknown;
228
254
  }
229
255
  /**
@@ -1,9 +1,8 @@
1
- import type { CredentialMode } from "./managed-key.js";
2
- import type { RunProvider, RuntimeKind } from "./submission.js";
1
+ import type { CredentialMode, RunProvider, RuntimeKind } from "./submission.js";
3
2
  export declare const SIDE_EFFECT_AUDIT_SCHEMA_VERSION = 1;
4
3
  export declare const SIDE_EFFECT_AUDIT_REDACTION_SCANNER_VERSION = 1;
5
4
  export declare const SIDE_EFFECT_AUDIT_KIND = "aex.side_effect_audit.v1";
6
- export declare const SIDE_EFFECT_AUDIT_ACTIONS: readonly ["run.submit.accepted", "run.submit.rejected", "run.cancel.requested", "run.delete.requested", "run.delete.completed", "run.delete.failed", "run.download.requested", "run.output.downloaded", "run.log.downloaded", "run.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", "managed_key.quota.denied", "terminal_redrive.attempted", "terminal_redrive.completed", "api_token.created", "api_token.revoked", "api_token.used"];
5
+ export declare const SIDE_EFFECT_AUDIT_ACTIONS: readonly ["run.submit.accepted", "run.submit.rejected", "run.cancel.requested", "run.delete.requested", "run.delete.completed", "run.delete.failed", "run.download.requested", "run.output.downloaded", "run.log.downloaded", "run.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_token.created", "api_token.deleted", "api_token.used"];
7
6
  export type SideEffectAuditAction = (typeof SIDE_EFFECT_AUDIT_ACTIONS)[number];
8
7
  export declare const SIDE_EFFECT_AUDIT_ACTOR_PRINCIPAL_TYPES: readonly ["user", "api_token", "system", "runtime"];
9
8
  export type SideEffectAuditActorPrincipalType = (typeof SIDE_EFFECT_AUDIT_ACTOR_PRINCIPAL_TYPES)[number];
@@ -11,13 +10,13 @@ export declare const SIDE_EFFECT_AUDIT_SOURCE_PLANES: readonly ["dashboard", "wo
11
10
  export type SideEffectAuditSourcePlane = (typeof SIDE_EFFECT_AUDIT_SOURCE_PLANES)[number];
12
11
  export declare const SIDE_EFFECT_AUDIT_AUTHENTICATION_KINDS: readonly ["dashboard_auth", "api_token", "runner_token", "system"];
13
12
  export type SideEffectAuditAuthenticationKind = (typeof SIDE_EFFECT_AUDIT_AUTHENTICATION_KINDS)[number];
14
- export declare const SIDE_EFFECT_AUDIT_TARGET_TYPES: readonly ["workspace", "run", "proxy_endpoint", "mcp_credential", "mcp_proxy", "provider_proxy", "output_archive", "run_output", "run_log", "run_event_stream", "workspace_asset", "custody_manifest", "custody_transition", "cleanup", "deletion", "managed_key_gate", "terminal_redrive", "api_token"];
13
+ export declare const SIDE_EFFECT_AUDIT_TARGET_TYPES: readonly ["workspace", "run", "proxy_endpoint", "mcp_credential", "mcp_proxy", "provider_proxy", "output_archive", "run_output", "run_log", "run_event_stream", "workspace_asset", "custody_manifest", "custody_transition", "cleanup", "deletion", "terminal_redrive", "api_token"];
15
14
  export type SideEffectAuditTargetType = (typeof SIDE_EFFECT_AUDIT_TARGET_TYPES)[number];
16
15
  export declare const SIDE_EFFECT_AUDIT_OUTCOMES: readonly ["accepted", "rejected", "succeeded", "failed", "denied", "canceled", "pending"];
17
16
  export type SideEffectAuditOutcome = (typeof SIDE_EFFECT_AUDIT_OUTCOMES)[number];
18
17
  export declare const SIDE_EFFECT_AUDIT_COUNT_NAMES: readonly ["requestBytes", "responseBytes", "durationMs", "attemptCount", "retryCount", "outputCount", "logCount", "eventCount", "assetCount", "proxyCallCount", "mcpCallCount", "providerProxyCallCount", "secretClassCount", "resourceClassCount", "deletedObjectCount", "retainedObjectCount", "failedObjectCount", "quotaRequestedUnits", "quotaRemainingUnits", "reservationCount"];
19
18
  export type SideEffectAuditCountName = (typeof SIDE_EFFECT_AUDIT_COUNT_NAMES)[number];
20
- export declare const SIDE_EFFECT_AUDIT_TIMESTAMP_NAMES: readonly ["startedAt", "finishedAt", "observedAt", "decidedAt", "deletedAt", "tombstonedAt", "terminalAt", "expiresAt"];
19
+ export declare const SIDE_EFFECT_AUDIT_TIMESTAMP_NAMES: readonly ["startedAt", "finishedAt", "observedAt", "decidedAt", "deletedAt", "terminalAt", "expiresAt"];
21
20
  export type SideEffectAuditTimestampName = (typeof SIDE_EFFECT_AUDIT_TIMESTAMP_NAMES)[number];
22
21
  export declare const SIDE_EFFECT_AUDIT_METADATA_EXCLUDED_VALUE_CLASSES: readonly ["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"];
23
22
  export type SideEffectAuditMetadataExcludedValueClass = (typeof SIDE_EFFECT_AUDIT_METADATA_EXCLUDED_VALUE_CLASSES)[number];
@@ -22,11 +22,10 @@ export const SIDE_EFFECT_AUDIT_ACTIONS = [
22
22
  "custody.transition.recorded",
23
23
  "runtime.cleanup.completed",
24
24
  "runtime.cleanup.failed",
25
- "managed_key.quota.denied",
26
25
  "terminal_redrive.attempted",
27
26
  "terminal_redrive.completed",
28
27
  "api_token.created",
29
- "api_token.revoked",
28
+ "api_token.deleted",
30
29
  "api_token.used"
31
30
  ];
32
31
  export const SIDE_EFFECT_AUDIT_ACTOR_PRINCIPAL_TYPES = [
@@ -63,7 +62,6 @@ export const SIDE_EFFECT_AUDIT_TARGET_TYPES = [
63
62
  "custody_transition",
64
63
  "cleanup",
65
64
  "deletion",
66
- "managed_key_gate",
67
65
  "terminal_redrive",
68
66
  "api_token"
69
67
  ];
@@ -104,7 +102,6 @@ export const SIDE_EFFECT_AUDIT_TIMESTAMP_NAMES = [
104
102
  "observedAt",
105
103
  "decidedAt",
106
104
  "deletedAt",
107
- "tombstonedAt",
108
105
  "terminalAt",
109
106
  "expiresAt"
110
107
  ];