@aexhq/sdk 0.40.15 → 0.41.0

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 (132) hide show
  1. package/README.md +25 -25
  2. package/dist/_contracts/api-key.d.ts +6 -4
  3. package/dist/_contracts/api-key.js +20 -7
  4. package/dist/_contracts/asset-upload-helper.d.ts +2 -2
  5. package/dist/_contracts/asset-upload-helper.js +2 -2
  6. package/dist/_contracts/connection-ticket.d.ts +5 -5
  7. package/dist/_contracts/connection-ticket.js +7 -7
  8. package/dist/_contracts/error-codes.d.ts +1 -1
  9. package/dist/_contracts/error-codes.js +4 -4
  10. package/dist/_contracts/error-factory.js +1 -1
  11. package/dist/_contracts/event-envelope.d.ts +41 -41
  12. package/dist/_contracts/event-envelope.js +49 -49
  13. package/dist/_contracts/event-stream-client.d.ts +9 -9
  14. package/dist/_contracts/event-stream-client.js +5 -5
  15. package/dist/_contracts/event-view.d.ts +6 -6
  16. package/dist/_contracts/event-view.js +12 -12
  17. package/dist/_contracts/http.js +1 -1
  18. package/dist/_contracts/index.d.ts +10 -10
  19. package/dist/_contracts/index.js +9 -9
  20. package/dist/_contracts/models.d.ts +17 -17
  21. package/dist/_contracts/models.js +14 -14
  22. package/dist/_contracts/operations.d.ts +79 -82
  23. package/dist/_contracts/operations.js +233 -243
  24. package/dist/_contracts/provider-support.d.ts +2 -2
  25. package/dist/_contracts/runner-event.d.ts +8 -8
  26. package/dist/_contracts/runner-event.js +9 -9
  27. package/dist/_contracts/runtime-manifest.d.ts +12 -12
  28. package/dist/_contracts/runtime-manifest.js +1 -1
  29. package/dist/_contracts/runtime-sizes.d.ts +12 -12
  30. package/dist/_contracts/runtime-sizes.js +18 -18
  31. package/dist/_contracts/runtime-types.d.ts +117 -117
  32. package/dist/_contracts/runtime-types.js +2 -2
  33. package/dist/_contracts/sdk-errors.d.ts +3 -3
  34. package/dist/_contracts/sdk-errors.js +4 -4
  35. package/dist/_contracts/sdk-secrets.js +10 -10
  36. package/dist/_contracts/session-artifacts.d.ts +151 -0
  37. package/dist/_contracts/session-artifacts.js +234 -0
  38. package/dist/_contracts/{run-config.d.ts → session-config.d.ts} +29 -29
  39. package/dist/_contracts/{run-config.js → session-config.js} +37 -37
  40. package/dist/_contracts/session-cost.d.ts +140 -0
  41. package/dist/_contracts/{run-cost.js → session-cost.js} +94 -94
  42. package/dist/_contracts/{run-custody.d.ts → session-custody.d.ts} +16 -16
  43. package/dist/_contracts/{run-custody.js → session-custody.js} +42 -42
  44. package/dist/_contracts/session-record.d.ts +112 -0
  45. package/dist/_contracts/{run-record.js → session-record.js} +23 -23
  46. package/dist/_contracts/session-retention.d.ts +209 -0
  47. package/dist/_contracts/{run-retention.js → session-retention.js} +116 -116
  48. package/dist/_contracts/{run-unit.d.ts → session-unit.d.ts} +38 -38
  49. package/dist/_contracts/{run-unit.js → session-unit.js} +33 -33
  50. package/dist/_contracts/side-effect-audit.d.ts +14 -14
  51. package/dist/_contracts/side-effect-audit.js +38 -38
  52. package/dist/_contracts/sse.d.ts +1 -1
  53. package/dist/_contracts/sse.js +0 -0
  54. package/dist/_contracts/stable.d.ts +1 -1
  55. package/dist/_contracts/stable.js +1 -1
  56. package/dist/_contracts/status.d.ts +18 -18
  57. package/dist/_contracts/status.js +19 -19
  58. package/dist/_contracts/submission.d.ts +101 -99
  59. package/dist/_contracts/submission.js +96 -96
  60. package/dist/_contracts/{run-trace.d.ts → turn-trace.d.ts} +1 -1
  61. package/dist/_contracts/webhook-verify.d.ts +1 -1
  62. package/dist/_contracts/webhook-verify.js +1 -1
  63. package/dist/agents-md.d.ts +4 -4
  64. package/dist/agents-md.js +5 -5
  65. package/dist/agents-md.js.map +1 -1
  66. package/dist/bundle.d.ts +1 -1
  67. package/dist/bundle.js +1 -1
  68. package/dist/bundle.js.map +1 -1
  69. package/dist/cli.mjs +580 -623
  70. package/dist/cli.mjs.sha256 +1 -1
  71. package/dist/client.d.ts +141 -155
  72. package/dist/client.js +236 -245
  73. package/dist/client.js.map +1 -1
  74. package/dist/fetch-archive.js +3 -3
  75. package/dist/file.d.ts +7 -7
  76. package/dist/file.js +8 -8
  77. package/dist/file.js.map +1 -1
  78. package/dist/index.d.ts +10 -10
  79. package/dist/index.js +8 -8
  80. package/dist/index.js.map +1 -1
  81. package/dist/mcp-server.d.ts +1 -1
  82. package/dist/retry.d.ts +1 -1
  83. package/dist/secret.d.ts +6 -6
  84. package/dist/secret.js +6 -6
  85. package/dist/secret.js.map +1 -1
  86. package/dist/skill.d.ts +2 -2
  87. package/dist/skill.js +3 -3
  88. package/dist/skill.js.map +1 -1
  89. package/dist/tool.js +2 -2
  90. package/dist/tool.js.map +1 -1
  91. package/dist/version.d.ts +1 -1
  92. package/dist/version.js +1 -1
  93. package/dist/version.js.map +1 -1
  94. package/docs/authentication.md +11 -11
  95. package/docs/billing.md +3 -3
  96. package/docs/cleanup.md +5 -5
  97. package/docs/concepts/agent-tools.md +5 -5
  98. package/docs/concepts/composition.md +3 -3
  99. package/docs/concepts/providers-and-runtimes.md +3 -3
  100. package/docs/concepts/{runs.md → sessions.md} +8 -8
  101. package/docs/concepts/subagents.md +16 -16
  102. package/docs/credentials.md +7 -7
  103. package/docs/defaults.md +14 -14
  104. package/docs/errors.md +10 -10
  105. package/docs/events.md +26 -26
  106. package/docs/files.md +267 -0
  107. package/docs/limits-and-quotas.md +35 -35
  108. package/docs/limits.md +6 -6
  109. package/docs/mcp.md +3 -3
  110. package/docs/networking.md +24 -24
  111. package/docs/provider-runtime-capabilities.md +1 -1
  112. package/docs/public-surface.json +6 -6
  113. package/docs/quickstart.md +13 -13
  114. package/docs/release.md +5 -5
  115. package/docs/retries.md +3 -3
  116. package/docs/secrets.md +16 -16
  117. package/docs/session-config.md +58 -0
  118. package/docs/{run-record.md → session-record.md} +16 -16
  119. package/docs/skills.md +9 -9
  120. package/docs/vision-skills.md +7 -7
  121. package/docs/webhooks.md +11 -11
  122. package/examples/feature-tour.ts +17 -17
  123. package/examples/spike-settle-latency.ts +11 -11
  124. package/package.json +1 -1
  125. package/dist/_contracts/run-artifacts.d.ts +0 -49
  126. package/dist/_contracts/run-artifacts.js +0 -102
  127. package/dist/_contracts/run-cost.d.ts +0 -140
  128. package/dist/_contracts/run-record.d.ts +0 -116
  129. package/dist/_contracts/run-retention.d.ts +0 -209
  130. package/docs/outputs.md +0 -267
  131. package/docs/run-config.md +0 -58
  132. /package/dist/_contracts/{run-trace.js → turn-trace.js} +0 -0
@@ -4,10 +4,10 @@ import { suggest } from "./suggest.js";
4
4
  * upstream providers that can serve it and the **provider-native** model string
5
5
  * each one expects.
6
6
  *
7
- * `Models.*` / `RUN_MODELS` are aex's own **canonical, provider-neutral**
7
+ * `Models.*` / `SUPPORTED_MODELS` are aex's own **canonical, provider-neutral**
8
8
  * identifiers — they are NOT the strings sent to a provider. The platform
9
9
  * translates a `(canonical model, provider)` pair to the native id via
10
- * {@link resolveProviderModelId} when it builds the run's session manifest. The
10
+ * {@link resolveProviderModelId} when it builds the session's session manifest. The
11
11
  * same canonical model can therefore be served by more than one provider (e.g.
12
12
  * `gpt-4o-mini` via `openai` *or* `openrouter`), with a different native string
13
13
  * per provider.
@@ -45,7 +45,7 @@ export const MODEL_PROVIDER_IDS = {
45
45
  "doubao-cn": "doubao-seed-1-6-flash-250828"
46
46
  }
47
47
  };
48
- export const RUN_MODELS = Object.keys(MODEL_PROVIDER_IDS);
48
+ export const SUPPORTED_MODELS = Object.keys(MODEL_PROVIDER_IDS);
49
49
  /**
50
50
  * Symbol-style accessors for the closed model set. Prefer these over raw
51
51
  * strings so an invalid token is a compile error, not a runtime 400 — e.g.
@@ -109,9 +109,9 @@ const PROVIDERS_BY_MODEL = (() => {
109
109
  /**
110
110
  * Provider → canonical models that provider can serve. Derived from
111
111
  * {@link MODEL_PROVIDER_IDS}; every provider currently serves at least one
112
- * model, so all {@link RunProvider} keys are present.
112
+ * model, so all {@link ProviderName} keys are present.
113
113
  */
114
- export const RUN_MODELS_BY_PROVIDER = (() => {
114
+ export const SUPPORTED_MODELS_BY_PROVIDER = (() => {
115
115
  const map = {};
116
116
  for (const [model, providers] of Object.entries(MODEL_PROVIDER_IDS)) {
117
117
  for (const provider of Object.keys(providers)) {
@@ -130,7 +130,7 @@ export function providersForModel(model) {
130
130
  /**
131
131
  * The default upstream provider for a model id — the first provider declared
132
132
  * for it in {@link MODEL_PROVIDER_IDS}. Returns `undefined` when the input is
133
- * not a known {@link RunModel} (so the SDK can fall back to the default and let
133
+ * not a known {@link ModelName} (so the SDK can fall back to the default and let
134
134
  * the server reject the model).
135
135
  */
136
136
  export function providerForModel(model) {
@@ -162,7 +162,7 @@ export function resolveProviderModelId(model, provider) {
162
162
  * declared). An UNKNOWN model with no provider throws a `did you mean?`
163
163
  * hint — you must name a provider to run a model this client doesn't know.
164
164
  *
165
- * Returns the resolved {@link RunProvider}.
165
+ * Returns the resolved {@link ProviderName}.
166
166
  */
167
167
  export function resolveModelProvider(model, provider) {
168
168
  const providers = providersForModel(model);
@@ -175,23 +175,23 @@ export function resolveModelProvider(model, provider) {
175
175
  }
176
176
  const inferred = providers[0];
177
177
  if (inferred === undefined) {
178
- const hint = suggest(model, RUN_MODELS);
178
+ const hint = suggest(model, SUPPORTED_MODELS);
179
179
  throw new Error(`${JSON.stringify(model)} is not a known model id` +
180
180
  (hint ? ` (did you mean ${JSON.stringify(hint)}?)` : "") +
181
181
  "; pass provider explicitly to run it");
182
182
  }
183
183
  return inferred;
184
184
  }
185
- export function isRunModel(input) {
186
- return typeof input === "string" && RUN_MODELS.includes(input);
185
+ export function isModelName(input) {
186
+ return typeof input === "string" && SUPPORTED_MODELS.includes(input);
187
187
  }
188
- export function parseRunModel(input, field = "submission.model") {
189
- if (!isRunModel(input)) {
190
- throw new Error(`${field} must be one of: ${RUN_MODELS.join(", ")}`);
188
+ export function parseModelName(input, field = "submission.model") {
189
+ if (!isModelName(input)) {
190
+ throw new Error(`${field} must be one of: ${SUPPORTED_MODELS.join(", ")}`);
191
191
  }
192
192
  return input;
193
193
  }
194
- export function assertRunModelMatchesProvider(provider, model, field = "submission.model") {
194
+ export function assertModelNameMatchesProvider(provider, model, field = "submission.model") {
195
195
  const providers = providersForModel(model);
196
196
  if (!providers.includes(provider)) {
197
197
  throw new Error(`${field} ${JSON.stringify(model)} is not supported for provider ${provider}; ` +
@@ -1,8 +1,8 @@
1
1
  import type { HttpClient } from "./http.js";
2
2
  import type { AexEvent } from "./event-envelope.js";
3
- import type { RunUnit } from "./run-unit.js";
4
- import type { AgentsMdRecord, BillingCheckoutRequest, BillingHostedSession, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, ChildRunRef, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, RunListPage, RunListQuery, Session, SessionCreateRequest, SessionEvent, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionStateChangeAccepted, RunWebhookDelivery, SecretRecord, SecretReveal, SkillRecord, WebhookSigningSecret, WhoAmI } from "./runtime-types.js";
5
- import type { PlatformRunSubmissionInput } from "./submission.js";
3
+ import type { SessionUnit } from "./session-unit.js";
4
+ import type { AgentsMdRecord, BillingCheckoutRequest, BillingHostedSession, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, ChildSessionRef, FileRecord, SessionFile, SessionFileLink, SessionFileLinkOptions, SessionFileDownload, SessionFileSelector, SessionFileType, SessionFileQuery, SessionFileText, ReadSessionFileTextOptions, SessionRecord, SessionRecordListPage, SessionRecordListQuery, Session, SessionCreateRequest, SessionEvent, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionStateChangeAccepted, SessionWebhookDelivery, SecretRecord, SecretReveal, SkillRecord, WebhookSigningSecret, WhoAmI } from "./runtime-types.js";
5
+ import type { PlatformSessionSubmissionInput } from "./submission.js";
6
6
  /**
7
7
  * The single source of truth for SDK<->BFF transport. The SDK class
8
8
  * AND the CLI subcommands both call these functions; neither
@@ -14,29 +14,29 @@ import type { PlatformRunSubmissionInput } from "./submission.js";
14
14
  * Workspace identity is derived server-side from the API key on
15
15
  * every request; callers do not pass `workspaceId`.
16
16
  */
17
- export declare function getRun(http: HttpClient, runId: string): Promise<Run>;
17
+ export declare function getSessionRecord(http: HttpClient, sessionId: string): Promise<SessionRecord>;
18
18
  /**
19
- * Strongly-typed accessor for the full self-contained run unit:
19
+ * Strongly-typed accessor for the full self-contained session unit:
20
20
  * parsed submission inputs, attempts, indexed events (with
21
- * pagination cursor for large runs), raw-event Storage manifest,
22
- * outputs, capture failures, and the proxy-call audit.
21
+ * pagination cursor for large sessions), raw-event Storage manifest,
22
+ * files, capture failures, and the proxy-call audit.
23
23
  *
24
- * Backed by the same `GET /api/runs/:runId` endpoint that
25
- * `getRun` calls; this variant just narrows the return type to
26
- * the documented wire shape. Prefer this for new code; `getRun`
24
+ * Backed by the same `GET /api/sessions/:sessionId` endpoint that
25
+ * `getSessionRecord` calls; this variant just narrows the return type to
26
+ * the documented wire shape. Prefer this for new code; `getSessionRecord`
27
27
  * stays for callers that only need the loose record.
28
28
  */
29
- export declare function getRunUnit(http: HttpClient, runId: string): Promise<RunUnit>;
29
+ export declare function getSessionUnit(http: HttpClient, sessionId: string): Promise<SessionUnit>;
30
30
  /**
31
- * List the runs in the token's workspace, most-recent first, one page at a time.
32
- * Backed by `GET /api/runs` (workspace-token gated; the bare collection path, NOT
33
- * the run-keyed `GET /api/runs/:runId`). The server clamps `limit` to [1, 100] and
31
+ * List the sessions in the token's workspace, most-recent first, one page at a time.
32
+ * Backed by `GET /api/sessions` (workspace-token gated; the bare collection path, NOT
33
+ * the session-keyed `GET /api/sessions/:sessionId`). The server clamps `limit` to [1, 100] and
34
34
  * returns an opaque `nextCursor` for the next page (absent on the last page).
35
35
  *
36
- * Returns public-safe {@link RunSummary} rows only — never the submission snapshot.
37
- * For a single page; callers wanting every run loop on `nextCursor` themselves.
36
+ * Returns public-safe {@link SessionRecordSummary} rows only — never the submission snapshot.
37
+ * For a single page; callers wanting every session loop on `nextCursor` themselves.
38
38
  */
39
- export declare function listRuns(http: HttpClient, query?: RunListQuery): Promise<RunListPage>;
39
+ export declare function listSessionRecords(http: HttpClient, query?: SessionRecordListQuery): Promise<SessionRecordListPage>;
40
40
  export interface IdempotencyOptions {
41
41
  readonly idempotencyKey?: string;
42
42
  }
@@ -46,22 +46,22 @@ export interface SubmitOptions extends IdempotencyOptions {
46
46
  /**
47
47
  * Resolve a caller-supplied idempotency key to the value that ships on the
48
48
  * request. FAIL-FAST: an empty or whitespace-only key THROWS
49
- * {@link RunConfigValidationError} — a footgun that silently disabled dedup
49
+ * {@link SessionConfigValidationError} — a footgun that silently disabled dedup
50
50
  * (`?? generate()` kept `''`, then a downstream truthy header-drop shipped no
51
51
  * `Idempotency-Key`). An absent key generates a fresh one; a real key is
52
52
  * returned verbatim. The single choke point every send/create/run entry uses.
53
53
  */
54
54
  export declare function resolveIdempotencyKey(key?: string): string;
55
55
  export declare function createSession(http: HttpClient, request: SessionCreateRequest, options?: IdempotencyOptions): Promise<Session>;
56
- /** The result of a non-blocking {@link submit}: the run id + the created session. */
56
+ /** The result of a non-blocking {@link submit}: the session id + the created session. */
57
57
  export interface SubmitResult {
58
- readonly runId: string;
58
+ readonly sessionId: string;
59
59
  readonly session: Session;
60
60
  }
61
61
  /**
62
62
  * Fire-and-forget submit — create the session and post its first turn WITHOUT
63
- * awaiting the turn to settle (the honest counterpart to await-settle `run()`).
64
- * Returns the `runId` immediately; observe the run via a `webhook`, the event
63
+ * awaiting the turn to settle (the honest counterpart to await-settle `start()`).
64
+ * Returns the `sessionId` immediately; observe the session via a `webhook`, the event
65
65
  * stream, or by re-opening the session. Mirrors {@link createSession}'s
66
66
  * idempotency handling.
67
67
  */
@@ -85,15 +85,15 @@ export declare function approveSession(http: HttpClient, sessionId: string, opti
85
85
  export declare function denySession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
86
86
  export declare function deleteSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted | void>;
87
87
  export declare function listSessionEvents(http: HttpClient, sessionId: string): Promise<readonly SessionEvent[]>;
88
- export declare function listSessionOutputs(http: HttpClient, sessionId: string, query?: OutputQuery): Promise<readonly Output[]>;
88
+ export declare function listSessionFiles(http: HttpClient, sessionId: string, query?: SessionFileQuery): Promise<readonly SessionFile[]>;
89
89
  export declare function getSessionCoordinatorTicket(http: HttpClient, sessionId: string): Promise<CoordinatorTicket>;
90
90
  /**
91
- * List a run's events. The read endpoint is PAGED (bounded per response so a
91
+ * List a session's events. The read endpoint is PAGED (bounded per response so a
92
92
  * long run can't return an unbounded body); this follows `nextCursor` across
93
93
  * pages and returns the FULL accumulated list, preserving the prior single-call
94
94
  * contract for callers (download/*, CLI, streamEvents polling).
95
95
  */
96
- export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly AexEvent[]>;
96
+ export declare function listSessionRecordEvents(http: HttpClient, sessionId: string): Promise<readonly AexEvent[]>;
97
97
  /** A coordinator WS connection grant minted by the hosted API's ticket broker. */
98
98
  export interface CoordinatorTicket {
99
99
  readonly wsUrl: string;
@@ -102,67 +102,64 @@ export interface CoordinatorTicket {
102
102
  }
103
103
  /**
104
104
  * Mint a short-lived coordinator WS ticket via the workspace-token-gated
105
- * broker (`/api/runs/:id/events/ticket`). The returned `wsUrl` + `ticket`
105
+ * broker (`/api/sessions/:id/events/ticket`). The returned `wsUrl` + `ticket`
106
106
  * open the live event stream directly against the coordinator. Throws if no
107
107
  * coordinator is configured for the deployment (HTTP 503).
108
108
  */
109
- export declare function getCoordinatorTicket(http: HttpClient, runId: string): Promise<CoordinatorTicket>;
110
- export declare function listOutputs(http: HttpClient, runId: string, query?: OutputQuery): Promise<readonly Output[]>;
111
- export declare function findOutputs(http: HttpClient, runId: string, query: OutputQuery): Promise<readonly Output[]>;
112
- export declare function findOutput(http: HttpClient, runId: string, query: OutputQuery): Promise<Output | null>;
113
- export type OutputLinkSelector = string | OutputFileSelector | OutputQuery;
114
- export declare function outputLink(http: HttpClient, runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
115
- export declare function createOutputLink(http: HttpClient, runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
116
- export declare function eventArchiveLink(http: HttpClient, runId: string, options?: OutputLinkOptions): Promise<OutputLink>;
117
- export declare function resolveOutputFileSelector(outputs: readonly Output[], selector: OutputFileSelector, runId?: string): Output;
118
- export declare function downloadOutput(http: HttpClient, runId: string, selector: OutputFileSelector, options?: OutputTransferOptions): Promise<OutputFileDownload>;
119
- /** Byte ceiling for {@link readOutputText} — a hard cap even if a caller asks for more. */
120
- export declare const READ_OUTPUT_TEXT_MAX_BYTES = 10000000;
121
- /** Default `maxBytes` for {@link readOutputText} — a chat-sized preview. */
122
- export declare const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50000;
123
- /** Default per-attempt timeout while fetching or reading one output body. */
124
- export declare const OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 30000;
125
- /** Idempotent output GETs retry once on a transfer timeout. */
126
- export declare const OUTPUT_FILE_TRANSFER_ATTEMPTS = 2;
127
- export interface OutputTransferOptions {
109
+ export declare function getCoordinatorTicket(http: HttpClient, sessionId: string): Promise<CoordinatorTicket>;
110
+ export declare function findSessionFiles(http: HttpClient, sessionId: string, query: SessionFileQuery): Promise<readonly SessionFile[]>;
111
+ export declare function findSessionFile(http: HttpClient, sessionId: string, query: SessionFileQuery): Promise<SessionFile | null>;
112
+ export type SessionFileLinkSelector = string | SessionFileSelector | SessionFileQuery;
113
+ export declare function sessionFileLink(http: HttpClient, sessionId: string, selectorOrQuery: SessionFileLinkSelector, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
114
+ export declare function createSessionFileLink(http: HttpClient, sessionId: string, selectorOrQuery: SessionFileLinkSelector, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
115
+ export declare function eventArchiveLink(http: HttpClient, sessionId: string, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
116
+ export declare function resolveSessionFileSelector(files: readonly SessionFile[], selector: SessionFileSelector, sessionId?: string): SessionFile;
117
+ export declare function downloadSessionFile(http: HttpClient, sessionId: string, selector: SessionFileSelector, options?: SessionFileTransferOptions): Promise<SessionFileDownload>;
118
+ /** Byte ceiling for {@link readSessionFileText} a hard cap even if a caller asks for more. */
119
+ export declare const READ_SESSION_FILE_TEXT_MAX_BYTES = 10000000;
120
+ /** Default `maxBytes` for {@link readSessionFileText} — a chat-sized preview. */
121
+ export declare const READ_SESSION_FILE_TEXT_DEFAULT_BYTES = 50000;
122
+ /** Default per-attempt timeout while fetching or reading one session file body. */
123
+ export declare const SESSION_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 30000;
124
+ /** Idempotent file GETs retry once on a transfer timeout. */
125
+ export declare const SESSION_FILE_TRANSFER_ATTEMPTS = 2;
126
+ export interface SessionFileTransferOptions {
128
127
  readonly timeoutMs?: number;
129
128
  }
130
129
  /**
131
- * Read ONE output file as byte-capped, decoded UTF-8 text. Built for handing a run
130
+ * Read ONE session file as byte-capped, decoded UTF-8 text. Built for handing a session
132
131
  * deliverable to an LLM tool: it streams the file body and STOPS at `maxBytes`, so
133
132
  * a 200 MB artifact never fully buffers in memory or context. `truncated` is true
134
133
  * when the file is larger than the cap. Optionally `grep` keeps only matching lines.
135
134
  *
136
- * Selector is the same `{ path }` / `{ id }` shape as `downloadOutput`. A path
137
- * selector lists the run's outputs to resolve the id; an id selector skips that.
135
+ * Selector is the same `{ path }` / `{ id }` shape as `downloadSessionFile`. A path
136
+ * selector lists the session's files to resolve the id; an id selector skips that.
138
137
  */
139
- export declare function readOutputText(http: HttpClient, runId: string, selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
138
+ export declare function readSessionFileText(http: HttpClient, sessionId: string, selector: SessionFileSelector, options?: ReadSessionFileTextOptions): Promise<SessionFileText>;
140
139
  /**
141
- * List a run's subagent CHILD runs (`GET /runs/:id/children`). Each row is a
142
- * {@link ChildRunRef} whose `id` resolves through the run facade (getRun /
143
- * events / outputs) — so every child the platform hands you is resolvable. An
144
- * empty array means the run spawned no children.
140
+ * List a session's subagent child sessions (`GET /sessions/:id/children`). Each row is a
141
+ * {@link ChildSessionRef} whose `id` resolves through the session record facade (getSessionRecord /
142
+ * events / files) — so every child the platform hands you is resolvable. An
143
+ * empty array means the session spawned no children.
145
144
  */
146
- export declare function listRunChildren(http: HttpClient, runId: string): Promise<readonly ChildRunRef[]>;
147
- export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
148
- export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
145
+ export declare function listSessionChildren(http: HttpClient, sessionId: string): Promise<readonly ChildSessionRef[]>;
149
146
  /**
150
- * List a run's webhook delivery attempts (the per-run delivery ledger). Returns
151
- * the rows surfaced by `GET /api/runs/:id/webhook-deliveries`; an empty array
152
- * means the run carried no `webhook` or has not reached a terminal state yet.
147
+ * List a session's webhook delivery attempts (the per-session delivery ledger). Returns
148
+ * the rows surfaced by `GET /api/sessions/:id/webhook-deliveries`; an empty array
149
+ * means the session carried no `webhook` or has not reached a terminal state yet.
153
150
  */
154
- export declare function getRunWebhookDeliveries(http: HttpClient, runId: string): Promise<readonly RunWebhookDelivery[]>;
151
+ export declare function getSessionWebhookDeliveries(http: HttpClient, sessionId: string): Promise<readonly SessionWebhookDelivery[]>;
155
152
  /**
156
- * Manually re-trigger a run's webhook delivery: resets the row to `pending` and
153
+ * Manually re-trigger a session's webhook delivery: resets the row to `pending` and
157
154
  * re-sends the frozen payload with the SAME `webhook-id` so the consumer
158
155
  * dedupes. Idempotent from the caller's view.
159
156
  */
160
- export declare function redeliverRunWebhook(http: HttpClient, runId: string, deliveryId: string): Promise<void>;
157
+ export declare function redeliverSessionWebhook(http: HttpClient, sessionId: string, deliveryId: string): Promise<void>;
161
158
  /**
162
159
  * Delete a workspace asset cache entry. Accepts an `asset_<id>` value,
163
160
  * `sha256:<hex>`, or a bare 64-hex digest. Workspace is derived server-side
164
161
  * from the token; idempotent.
165
- * Does NOT affect runs that already snapshotted the asset.
162
+ * Does NOT affect sessions that already snapshotted the asset.
166
163
  */
167
164
  export declare function deleteWorkspaceAsset(http: HttpClient, hash: string): Promise<void>;
168
165
  export declare function whoami(http: HttpClient): Promise<WhoAmI>;
@@ -195,44 +192,44 @@ export declare function getBillingLedger(http: HttpClient, query?: BillingLedger
195
192
  * Pass the returned `whsec` to `verifyAexWebhook` as `secret`.
196
193
  */
197
194
  export declare function getWebhookSigningSecret(http: HttpClient): Promise<WebhookSigningSecret>;
198
- export declare function filterOutputs(outputs: readonly Output[], query: OutputQuery): readonly Output[];
195
+ export declare function filterSessionFiles(files: readonly SessionFile[], query: SessionFileQuery): readonly SessionFile[];
199
196
  /**
200
- * The single filename-matcher for cross-run / per-session output SEARCH. A
197
+ * The single filename-matcher for cross-session / per-session file SEARCH. A
201
198
  * string is a case-insensitive SUBSTRING match; a RegExp is tested as given (and
202
199
  * reset to `lastIndex = 0` so a reused `/g` regex is safe). Sharing this SSoT is
203
- * what closes the T16 crash class: `searchOutputs` no longer assumes `filename`
200
+ * what closes the T16 crash class: session-file search no longer assumes `filename`
204
201
  * is a string and passes a RegExp into `escapeRegExp(...).replace(...)`.
205
202
  */
206
203
  export declare function toFilenameMatcher(filename: string | RegExp): (name: string) => boolean;
207
- export declare function classifyOutput(output: Pick<Output, "filename" | "contentType">): OutputFileType;
208
- export declare function normalizeOutputLinkExpiresIn(input?: OutputLinkOptions["expiresIn"]): number;
204
+ export declare function classifySessionFile(file: Pick<SessionFile, "filename" | "contentType">): SessionFileType;
205
+ export declare function normalizeSessionFileLinkExpiresIn(input?: SessionFileLinkOptions["expiresIn"]): number;
209
206
  /**
210
- * Download EVERYTHING public about a run as one zip, organised into the three
207
+ * Download EVERYTHING public about a session as one zip, organised into the three
211
208
  * namespace folders:
212
209
  *
213
- * metadata/run.json — the run record.
210
+ * metadata/session.json — the session record.
214
211
  * events/events.jsonl — typed event-channel records.
215
- * outputs/<rel> — the run's deliverables.
216
- * manifest.json — `RunRecordManifestV1`.
212
+ * files/<rel> — the session's captured files.
213
+ * manifest.json — `SessionRecordManifestV1`.
217
214
  */
218
- export declare function download(http: HttpClient, runId: string): Promise<Uint8Array>;
215
+ export declare function download(http: HttpClient, sessionId: string): Promise<Uint8Array>;
219
216
  /**
220
- * Download only the run's deliverables (the `outputs` namespace). Zip
217
+ * Download only the session's captured files (the `files` namespace). Zip
221
218
  * layout: `<rel>` per file plus a `manifest.json`
222
- * (`{ runId, namespace: "outputs", outputs[], errors[] }`).
219
+ * (`{ sessionId, namespace: "files", files[], errors[] }`).
223
220
  */
224
- export declare function downloadOutputs(http: HttpClient, runId: string, options?: OutputTransferOptions): Promise<Uint8Array>;
221
+ export declare function downloadSessionFiles(http: HttpClient, sessionId: string, options?: SessionFileTransferOptions): Promise<Uint8Array>;
225
222
  /**
226
223
  * Download only the event archive (the `events` namespace). Always includes
227
224
  * typed `events.jsonl` plus `manifest.json`.
228
225
  */
229
- export declare function downloadEvents(http: HttpClient, runId: string): Promise<Uint8Array>;
226
+ export declare function downloadEvents(http: HttpClient, sessionId: string): Promise<Uint8Array>;
230
227
  /**
231
- * Download only the run record (the `metadata` namespace) as a zip
232
- * containing `run.json` plus `manifest.json`.
228
+ * Download only the session record (the `metadata` namespace) as a zip
229
+ * containing `session.json` plus `manifest.json`.
233
230
  */
234
- export declare function downloadMetadata(http: HttpClient, runId: string): Promise<Uint8Array>;
235
- export declare function submitRun(http: HttpClient, request: PlatformRunSubmissionInput): Promise<Run>;
231
+ export declare function downloadMetadata(http: HttpClient, sessionId: string): Promise<Uint8Array>;
232
+ export declare function startSessionRecord(http: HttpClient, request: PlatformSessionSubmissionInput): Promise<SessionRecord>;
236
233
  export declare function listAgentsMd(http: HttpClient): Promise<readonly AgentsMdRecord[]>;
237
234
  export declare function getAgentsMd(http: HttpClient, agentsMdId: string): Promise<AgentsMdRecord>;
238
235
  export declare function deleteAgentsMd(http: HttpClient, agentsMdId: string): Promise<void>;
@@ -284,7 +281,7 @@ export interface AssetUploadResult {
284
281
  /**
285
282
  * Upload bytes to the hosted API's content-addressable asset endpoint.
286
283
  * Returns a storage-neutral asset id suitable for `kind:"asset"` refs in a
287
- * later run submission.
284
+ * later session submission.
288
285
  */
289
286
  export declare function uploadWorkspaceAsset(http: HttpClient, input: {
290
287
  readonly bytes: Uint8Array;