@aexhq/sdk 0.40.15 → 0.41.0

package/dist/_contracts/operations.js

@@ -1,8 +1,8 @@
 import { strToU8, zipSync } from "fflate";
 import { randomUUID } from "node:crypto";
-import { normalizeRunUnit } from "./run-unit.js";
-import { AexNetworkError, RunConfigValidationError, RunStateError } from "./sdk-errors.js";
-import { assertRunRecordArchivePublicSafeV1, buildRunRecordDownloadManifestV1 } from "./run-record.js";
+import { normalizeSessionUnit } from "./session-unit.js";
+import { AexNetworkError, SessionConfigValidationError, SessionStateError } from "./sdk-errors.js";
+import { assertSessionRecordArchivePublicSafeV1, buildSessionRecordDownloadManifestV1 } from "./session-record.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
  * AND the CLI subcommands both call these functions; neither
@@ -14,38 +14,38 @@ import { assertRunRecordArchivePublicSafeV1, buildRunRecordDownloadManifestV1 }
  * Workspace identity is derived server-side from the API key on
  * every request; callers do not pass `workspaceId`.
  */
-export async function getRun(http, runId) {
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}`);
-    return hasRun(result) ? result.run : result;
+export async function getSessionRecord(http, sessionId) {
+    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}`);
+    return hasSessionRecord(result) ? result.session : result;
 }
 /**
- * Strongly-typed accessor for the full self-contained run unit:
+ * Strongly-typed accessor for the full self-contained session unit:
  * parsed submission inputs, attempts, indexed events (with
- * pagination cursor for large runs), raw-event Storage manifest,
- * outputs, capture failures, and the proxy-call audit.
+ * pagination cursor for large sessions), raw-event Storage manifest,
+ * files, capture failures, and the proxy-call audit.
  *
- * Backed by the same `GET /api/runs/:runId` endpoint that
- * `getRun` calls; this variant just narrows the return type to
- * the documented wire shape. Prefer this for new code; `getRun`
+ * Backed by the same `GET /api/sessions/:sessionId` endpoint that
+ * `getSessionRecord` calls; this variant just narrows the return type to
+ * the documented wire shape. Prefer this for new code; `getSessionRecord`
  * stays for callers that only need the loose record.
  */
-export async function getRunUnit(http, runId) {
-    // Normalize so the RunUnit type contract holds at runtime: the managed plane
+export async function getSessionUnit(http, sessionId) {
+    // Normalize so the SessionUnit type contract holds at runtime: the managed plane
     // returns a lean record and omits the aggregate collections (F25). The
-    // aggregates default to empty (safe array/page access) — read outputs()/events()
-    // for the authoritative per-run data on that plane.
-    return normalizeRunUnit(await http.request(`/api/runs/${encodeURIComponent(runId)}`));
+    // aggregates default to empty (safe array/page access) — read files()/events()
+    // for the authoritative per-session data on that plane.
+    return normalizeSessionUnit(await http.request(`/api/sessions/${encodeURIComponent(sessionId)}`));
 }
 /**
- * List the runs in the token's workspace, most-recent first, one page at a time.
- * Backed by `GET /api/runs` (workspace-token gated; the bare collection path, NOT
- * the run-keyed `GET /api/runs/:runId`). The server clamps `limit` to [1, 100] and
+ * List the sessions in the token's workspace, most-recent first, one page at a time.
+ * Backed by `GET /api/sessions` (workspace-token gated; the bare collection path, NOT
+ * the session-keyed `GET /api/sessions/:sessionId`). The server clamps `limit` to [1, 100] and
  * returns an opaque `nextCursor` for the next page (absent on the last page).
  *
- * Returns public-safe {@link RunSummary} rows only — never the submission snapshot.
- * For a single page; callers wanting every run loop on `nextCursor` themselves.
+ * Returns public-safe {@link SessionRecordSummary} rows only — never the submission snapshot.
+ * For a single page; callers wanting every session loop on `nextCursor` themselves.
  */
-export async function listRuns(http, query) {
+export async function listSessionRecords(http, query) {
     const params = {};
     if (query?.status !== undefined)
         params.status = query.status;
@@ -55,39 +55,39 @@ export async function listRuns(http, query) {
         params.limit = String(query.limit);
     if (query?.cursor !== undefined)
         params.cursor = query.cursor;
-    const page = await http.request("/api/runs", {}, params);
-    // Defensive contract enforcement: some deployed planes leak non-run marker
-    // rows (settle-time ledger/spendmark items) into the run-list index. Those
+    const page = await http.request("/api/sessions", {}, params);
+    // Defensive contract enforcement: some deployed planes leak non-session marker
+    // rows (settle-time ledger/spendmark items) into the session-list index. Those
     // phantoms carry only { id, createdAt } and would surface as duplicate,
-    // status-less RunSummary entries. Drop anything missing the fields
-    // RunSummary declares required, so callers can trust the published type.
+    // status-less SessionRecordSummary entries. Drop anything missing the fields
+    // SessionRecordSummary declares required, so callers can trust the published type.
     // The same enforcement covers `costUsd`: deployed planes serve `null` for
-    // runs with no settled telemetry, but RunSummary declares `costUsd?: number`
+    // sessions with no settled telemetry, but SessionRecordSummary declares `costUsd?: number`
     // — normalize `null` to absent so typed callers never see it.
     let changed = false;
-    const runs = [];
-    for (const run of page.runs) {
-        if (typeof run.id !== "string" ||
-            typeof run.status !== "string" ||
-            typeof run.createdAt !== "string" ||
-            typeof run.updatedAt !== "string") {
+    const sessions = [];
+    for (const session of page.sessions) {
+        if (typeof session.id !== "string" ||
+            typeof session.status !== "string" ||
+            typeof session.createdAt !== "string" ||
+            typeof session.updatedAt !== "string") {
             changed = true;
             continue;
         }
-        if (typeof run.costUsd !== "number" && run.costUsd !== undefined) {
-            const { costUsd: _dropped, ...rest } = run;
-            runs.push(rest);
+        if (typeof session.costUsd !== "number" && session.costUsd !== undefined) {
+            const { costUsd: _dropped, ...rest } = session;
+            sessions.push(rest);
             changed = true;
             continue;
         }
-        runs.push(run);
+        sessions.push(session);
     }
-    return changed ? { ...page, runs } : page;
+    return changed ? { ...page, sessions } : page;
 }
 /**
  * Resolve a caller-supplied idempotency key to the value that ships on the
  * request. FAIL-FAST: an empty or whitespace-only key THROWS
- * {@link RunConfigValidationError} — a footgun that silently disabled dedup
+ * {@link SessionConfigValidationError} — a footgun that silently disabled dedup
  * (`?? generate()` kept `''`, then a downstream truthy header-drop shipped no
  * `Idempotency-Key`). An absent key generates a fresh one; a real key is
  * returned verbatim. The single choke point every send/create/run entry uses.
@@ -97,7 +97,7 @@ export function resolveIdempotencyKey(key) {
         return `aex-idem-${randomUUID()}`;
     }
     if (typeof key !== "string" || key.trim().length === 0) {
-        throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+        throw new SessionConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
             field: "idempotencyKey",
             value: key
         });
@@ -113,7 +113,7 @@ function idempotencyHeaders(options) {
     if (options?.idempotencyKey === undefined)
         return undefined;
     if (typeof options.idempotencyKey !== "string" || options.idempotencyKey.trim().length === 0) {
-        throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+        throw new SessionConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
             field: "idempotencyKey",
             value: options.idempotencyKey
         });
@@ -131,8 +131,8 @@ export async function createSession(http, request, options) {
 }
 /**
  * Fire-and-forget submit — create the session and post its first turn WITHOUT
- * awaiting the turn to settle (the honest counterpart to await-settle `run()`).
- * Returns the `runId` immediately; observe the run via a `webhook`, the event
+ * awaiting the turn to settle (the honest counterpart to await-settle `start()`).
+ * Returns the `sessionId` immediately; observe the session via a `webhook`, the event
  * stream, or by re-opening the session. Mirrors {@link createSession}'s
  * idempotency handling.
  */
@@ -147,13 +147,13 @@ export async function submit(http, request, options) {
     const sessionId = created.sessionId ?? created.id;
     const accepted = await sendSessionMessage(http, sessionId, { input }, { idempotencyKey: messageKey });
     const session = accepted.session;
-    return { runId: session.sessionId ?? session.id, session };
+    return { sessionId: session.sessionId ?? session.id, session };
 }
 function assertSubmitInput(input) {
     const ok = (typeof input === "string" && input.length > 0) ||
         (Array.isArray(input) && input.length > 0 && input.every((segment) => typeof segment === "string" && segment.length > 0));
     if (!ok) {
-        throw new RunConfigValidationError("submit: request.input must be a non-empty string or string array", {
+        throw new SessionConfigValidationError("submit: request.input must be a non-empty string or string array", {
             field: "input",
             value: input
         });
@@ -242,25 +242,25 @@ export async function listSessionEvents(http, sessionId) {
     }
     return all;
 }
-export async function listSessionOutputs(http, sessionId, query) {
-    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/outputs`);
-    return query === undefined ? result.outputs : filterOutputs(result.outputs, query);
+export async function listSessionFiles(http, sessionId, query) {
+    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/files`);
+    return query === undefined ? result.files : filterSessionFiles(result.files, query);
 }
 export async function getSessionCoordinatorTicket(http, sessionId) {
     return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/events/ticket`, { method: "POST" });
 }
 // Bound the transparent pager: the read route caps each page at 1000, so this
-// admits up to ~1e6 events before bailing — past any real run, but bounded so a
+// admits up to ~1e6 events before bailing — past any real session, but bounded so a
 // server that never clears `nextCursor` can't loop forever.
 const LIST_EVENTS_PAGE_BUDGET = 1000;
 /**
- * List a run's events. The read endpoint is PAGED (bounded per response so a
+ * List a session's events. The read endpoint is PAGED (bounded per response so a
  * long run can't return an unbounded body); this follows `nextCursor` across
  * pages and returns the FULL accumulated list, preserving the prior single-call
  * contract for callers (download/*, CLI, streamEvents polling).
  */
-export async function listRunEvents(http, runId) {
-    const path = `/api/runs/${encodeURIComponent(runId)}/events`;
+export async function listSessionRecordEvents(http, sessionId) {
+    const path = `/api/sessions/${encodeURIComponent(sessionId)}/events`;
     const all = [];
     let cursor;
     for (let page = 0; page < LIST_EVENTS_PAGE_BUDGET; page++) {
@@ -275,35 +275,31 @@ export async function listRunEvents(http, runId) {
 }
 /**
  * Mint a short-lived coordinator WS ticket via the workspace-token-gated
- * broker (`/api/runs/:id/events/ticket`). The returned `wsUrl` + `ticket`
+ * broker (`/api/sessions/:id/events/ticket`). The returned `wsUrl` + `ticket`
  * open the live event stream directly against the coordinator. Throws if no
  * coordinator is configured for the deployment (HTTP 503).
  */
-export async function getCoordinatorTicket(http, runId) {
-    return http.request(`/api/runs/${encodeURIComponent(runId)}/events/ticket`, { method: "POST" });
-}
-export async function listOutputs(http, runId, query) {
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs`);
-    return query === undefined ? result.outputs : filterOutputs(result.outputs, query);
+export async function getCoordinatorTicket(http, sessionId) {
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/events/ticket`, { method: "POST" });
 }
-export async function findOutputs(http, runId, query) {
-    return listOutputs(http, runId, query);
+export async function findSessionFiles(http, sessionId, query) {
+    return listSessionFiles(http, sessionId, query);
 }
-export async function findOutput(http, runId, query) {
-    const matches = await findOutputs(http, runId, query);
+export async function findSessionFile(http, sessionId, query) {
+    const matches = await findSessionFiles(http, sessionId, query);
     if (matches.length === 0)
         return null;
     if (matches.length === 1)
         return matches[0];
-    throw new RunStateError("outputs.findOne: output query matched multiple files", {
-        runId,
-        matches: matches.map((output) => output.filename ?? output.id)
+    throw new SessionStateError("files.findOne: file query matched multiple files", {
+        sessionId,
+        matches: matches.map((file) => file.filename ?? file.id)
     });
 }
-export async function outputLink(http, runId, selectorOrQuery, options) {
-    const output = await resolveOutputLinkTarget(http, runId, selectorOrQuery);
-    const expiresInSeconds = normalizeOutputLinkExpiresIn(options?.expiresIn);
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/link`, {
+export async function sessionFileLink(http, sessionId, selectorOrQuery, options) {
+    const file = await resolveSessionFileLinkTarget(http, sessionId, selectorOrQuery);
+    const expiresInSeconds = normalizeSessionFileLinkExpiresIn(options?.expiresIn);
+    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/files/${encodeURIComponent(file.id)}/link`, {
         method: "POST",
         body: JSON.stringify({ expiresInSeconds })
     });
@@ -312,7 +308,7 @@ export async function outputLink(http, runId, selectorOrQuery, options) {
         ...result,
         expiresInSeconds: effectiveExpiresIn,
         expiresAt: result.expiresAt ?? syntheticExpiresAt(effectiveExpiresIn),
-        output: result.output ?? output
+        file: result.file ?? file
     };
 }
 /**
@@ -323,12 +319,12 @@ export async function outputLink(http, runId, selectorOrQuery, options) {
 function syntheticExpiresAt(expiresInSeconds) {
     return new Date(Date.now() + expiresInSeconds * 1000).toISOString();
 }
-export async function createOutputLink(http, runId, selectorOrQuery, options) {
-    return outputLink(http, runId, selectorOrQuery, options);
+export async function createSessionFileLink(http, sessionId, selectorOrQuery, options) {
+    return sessionFileLink(http, sessionId, selectorOrQuery, options);
 }
-export async function eventArchiveLink(http, runId, options) {
-    const expiresInSeconds = normalizeOutputLinkExpiresIn(options?.expiresIn);
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/events/link`, {
+export async function eventArchiveLink(http, sessionId, options) {
+    const expiresInSeconds = normalizeSessionFileLinkExpiresIn(options?.expiresIn);
+    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/events/link`, {
         method: "POST",
         body: JSON.stringify({ expiresInSeconds })
     });
@@ -339,16 +335,16 @@ export async function eventArchiveLink(http, runId, options) {
         expiresAt: result.expiresAt ?? syntheticExpiresAt(effectiveExpiresIn)
     };
 }
-export function resolveOutputFileSelector(outputs, selector, runId) {
+export function resolveSessionFileSelector(files, selector, sessionId) {
     if (isPathSelector(selector)) {
-        const target = normalizeOutputLookupPath(selector.path);
+        const target = normalizeSessionFileLookupPath(selector.path);
         if (!target) {
-            throw new RunStateError("outputs.download: output path must be non-empty", { runId, path: selector.path });
+            throw new SessionStateError("files.download: file path must be non-empty", { sessionId, path: selector.path });
         }
-        const matches = outputs.filter((output) => {
-            if (typeof output.filename !== "string")
+        const matches = files.filter((file) => {
+            if (typeof file.filename !== "string")
                 return false;
-            const filename = normalizeOutputLookupPath(output.filename);
+            const filename = normalizeSessionFileLookupPath(file.filename);
             if (selector.match === "suffix") {
                 return filename === target || filename.endsWith(`/${target}`);
             }
@@ -357,80 +353,80 @@ export function resolveOutputFileSelector(outputs, selector, runId) {
         if (matches.length === 1)
             return matches[0];
         if (matches.length > 1) {
-            throw new RunStateError(`outputs.download: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
+            throw new SessionStateError(`files.download: file path "${selector.path}" matched multiple files`, { sessionId, path: selector.path, matches: matches.map((file) => file.filename ?? file.id) });
         }
-        throw new RunStateError(`outputs.download: output path "${selector.path}" was not found`, {
-            runId,
+        throw new SessionStateError(`files.download: file path "${selector.path}" was not found`, {
+            sessionId,
             path: selector.path
         });
     }
     if (typeof selector?.id !== "string" || selector.id.length === 0) {
-        throw new RunStateError("outputs.download: selector must include an output id or path", { runId });
+        throw new SessionStateError("files.download: selector must include a file id or path", { sessionId });
     }
     return { ...selector, id: selector.id };
 }
-export async function downloadOutput(http, runId, selector, options) {
-    const output = isPathSelector(selector)
-        ? resolveOutputFileSelector(await listOutputs(http, runId), selector, runId)
-        : resolveOutputFileSelector([], selector, runId);
-    const timeoutMs = normalizeOutputTransferTimeoutMs(options?.timeoutMs);
-    const path = `/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`;
-    return { output, bytes: await downloadOutputBytesWithRetry(http, path, timeoutMs) };
-}
-/** Byte ceiling for {@link readOutputText} — a hard cap even if a caller asks for more. */
-export const READ_OUTPUT_TEXT_MAX_BYTES = 10_000_000;
-/** Default `maxBytes` for {@link readOutputText} — a chat-sized preview. */
-export const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50_000;
-/** Default per-attempt timeout while fetching or reading one output body. */
-export const OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 30_000;
-/** Idempotent output GETs retry once on a transfer timeout. */
-export const OUTPUT_FILE_TRANSFER_ATTEMPTS = 2;
+export async function downloadSessionFile(http, sessionId, selector, options) {
+    const file = isPathSelector(selector)
+        ? resolveSessionFileSelector(await listSessionFiles(http, sessionId), selector, sessionId)
+        : resolveSessionFileSelector([], selector, sessionId);
+    const timeoutMs = normalizeSessionFileTransferTimeoutMs(options?.timeoutMs);
+    const path = `/api/sessions/${encodeURIComponent(sessionId)}/files/${encodeURIComponent(file.id)}/download`;
+    return { file, bytes: await downloadSessionFileBytesWithRetry(http, path, timeoutMs) };
+}
+/** Byte ceiling for {@link readSessionFileText} — a hard cap even if a caller asks for more. */
+export const READ_SESSION_FILE_TEXT_MAX_BYTES = 10_000_000;
+/** Default `maxBytes` for {@link readSessionFileText} — a chat-sized preview. */
+export const READ_SESSION_FILE_TEXT_DEFAULT_BYTES = 50_000;
+/** Default per-attempt timeout while fetching or reading one session file body. */
+export const SESSION_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 30_000;
+/** Idempotent file GETs retry once on a transfer timeout. */
+export const SESSION_FILE_TRANSFER_ATTEMPTS = 2;
 /**
- * Read ONE output file as byte-capped, decoded UTF-8 text. Built for handing a run
+ * Read ONE session file as byte-capped, decoded UTF-8 text. Built for handing a session
  * deliverable to an LLM tool: it streams the file body and STOPS at `maxBytes`, so
  * a 200 MB artifact never fully buffers in memory or context. `truncated` is true
  * when the file is larger than the cap. Optionally `grep` keeps only matching lines.
  *
- * Selector is the same `{ path }` / `{ id }` shape as `downloadOutput`. A path
- * selector lists the run's outputs to resolve the id; an id selector skips that.
+ * Selector is the same `{ path }` / `{ id }` shape as `downloadSessionFile`. A path
+ * selector lists the session's files to resolve the id; an id selector skips that.
  */
-export async function readOutputText(http, runId, selector, options) {
-    const maxBytes = Math.max(1, Math.min(options?.maxBytes ?? READ_OUTPUT_TEXT_DEFAULT_BYTES, READ_OUTPUT_TEXT_MAX_BYTES));
-    const output = isPathSelector(selector)
-        ? resolveOutputFileSelector(await listOutputs(http, runId), selector, runId)
-        : resolveOutputFileSelector([], selector, runId);
-    const timeoutMs = normalizeOutputTransferTimeoutMs(options?.timeoutMs);
-    const path = `/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`;
-    const capped = await readOutputTextWithRetry(http, path, maxBytes, timeoutMs);
+export async function readSessionFileText(http, sessionId, selector, options) {
+    const maxBytes = Math.max(1, Math.min(options?.maxBytes ?? READ_SESSION_FILE_TEXT_DEFAULT_BYTES, READ_SESSION_FILE_TEXT_MAX_BYTES));
+    const file = isPathSelector(selector)
+        ? resolveSessionFileSelector(await listSessionFiles(http, sessionId), selector, sessionId)
+        : resolveSessionFileSelector([], selector, sessionId);
+    const timeoutMs = normalizeSessionFileTransferTimeoutMs(options?.timeoutMs);
+    const path = `/api/sessions/${encodeURIComponent(sessionId)}/files/${encodeURIComponent(file.id)}/download`;
+    const capped = await readSessionFileTextWithRetry(http, path, maxBytes, timeoutMs);
     const text = options?.grep === undefined ? capped.text : grepLines(capped.text, options.grep);
-    return { output, text, truncated: capped.truncated, totalBytes: capped.totalBytes };
+    return { file, text, truncated: capped.truncated, totalBytes: capped.totalBytes };
 }
-async function downloadOutputBytesWithRetry(http, path, timeoutMs) {
-    return outputTransferWithRetry(path, timeoutMs, async () => {
-        const response = await downloadOutputResponse(http, path, timeoutMs);
+async function downloadSessionFileBytesWithRetry(http, path, timeoutMs) {
+    return sessionFileTransferWithRetry(path, timeoutMs, async () => {
+        const response = await downloadSessionFileResponse(http, path, timeoutMs);
         return readResponseBytes(response, timeoutMs);
     });
 }
-async function readOutputTextWithRetry(http, path, maxBytes, timeoutMs) {
-    return outputTransferWithRetry(path, timeoutMs, async () => {
-        const response = await downloadOutputResponse(http, path, timeoutMs);
+async function readSessionFileTextWithRetry(http, path, maxBytes, timeoutMs) {
+    return sessionFileTransferWithRetry(path, timeoutMs, async () => {
+        const response = await downloadSessionFileResponse(http, path, timeoutMs);
         return readCappedText(response, maxBytes, timeoutMs);
     });
 }
-async function downloadOutputResponse(http, path, timeoutMs) {
+async function downloadSessionFileResponse(http, path, timeoutMs) {
     const controller = new AbortController();
-    const { response } = await withOutputTransferTimeout(http.download(path, { signal: controller.signal }), timeoutMs, () => controller.abort(), "download-open");
+    const { response } = await withSessionFileTransferTimeout(http.download(path, { signal: controller.signal }), timeoutMs, () => controller.abort(), "download-open");
     return response;
 }
-async function outputTransferWithRetry(path, timeoutMs, action) {
+async function sessionFileTransferWithRetry(path, timeoutMs, action) {
     const startedMs = Date.now();
     let lastTimeout;
-    for (let attempt = 1; attempt <= OUTPUT_FILE_TRANSFER_ATTEMPTS; attempt += 1) {
+    for (let attempt = 1; attempt <= SESSION_FILE_TRANSFER_ATTEMPTS; attempt += 1) {
         try {
             return await action();
         }
         catch (err) {
-            if (!(err instanceof OutputTransferTimeoutError))
+            if (!(err instanceof SessionFileTransferTimeoutError))
                 throw err;
             lastTimeout = err;
         }
@@ -439,37 +435,37 @@ async function outputTransferWithRetry(path, timeoutMs, action) {
         method: "GET",
         host: "",
         path,
-        cause: lastTimeout ?? new OutputTransferTimeoutError("unknown", timeoutMs),
-        attempts: OUTPUT_FILE_TRANSFER_ATTEMPTS,
+        cause: lastTimeout ?? new SessionFileTransferTimeoutError("unknown", timeoutMs),
+        attempts: SESSION_FILE_TRANSFER_ATTEMPTS,
         elapsedMs: Date.now() - startedMs
     });
 }
-function normalizeOutputTransferTimeoutMs(value) {
+function normalizeSessionFileTransferTimeoutMs(value) {
     if (value === undefined)
-        return OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS;
+        return SESSION_FILE_TRANSFER_DEFAULT_TIMEOUT_MS;
     if (!Number.isFinite(value) || value <= 0) {
-        throw new RunConfigValidationError("outputs.download: timeoutMs must be a positive finite number", {
+        throw new SessionConfigValidationError("files.download: timeoutMs must be a positive finite number", {
             timeoutMs: value
         });
     }
     return Math.max(1, Math.floor(value));
 }
-class OutputTransferTimeoutError extends Error {
+class SessionFileTransferTimeoutError extends Error {
     code = "ETIMEDOUT";
     phase;
     constructor(phase, timeoutMs) {
-        super(`output transfer phase=${phase} timed out after ${timeoutMs}ms`);
-        this.name = "OutputTransferTimeoutError";
+        super(`file transfer phase=${phase} timed out after ${timeoutMs}ms`);
+        this.name = "SessionFileTransferTimeoutError";
         this.phase = phase;
     }
 }
-async function withOutputTransferTimeout(promise, timeoutMs, abort, phase) {
+async function withSessionFileTransferTimeout(promise, timeoutMs, abort, phase) {
     let timedOut = false;
     let timeout;
     const timeoutPromise = new Promise((_, reject) => {
         timeout = setTimeout(() => {
             timedOut = true;
-            reject(new OutputTransferTimeoutError(phase, timeoutMs));
+            reject(new SessionFileTransferTimeoutError(phase, timeoutMs));
             queueMicrotask(() => {
                 try {
                     abort();
@@ -485,7 +481,7 @@ async function withOutputTransferTimeout(promise, timeoutMs, abort, phase) {
     }
     catch (err) {
         if (timedOut && isAbortLikeError(err))
-            throw new OutputTransferTimeoutError(phase, timeoutMs);
+            throw new SessionFileTransferTimeoutError(phase, timeoutMs);
         throw err;
     }
     finally {
@@ -500,14 +496,14 @@ function isAbortLikeError(err) {
 async function readResponseBytes(response, timeoutMs) {
     const body = response.body;
     if (!body) {
-        const buffer = await withOutputTransferTimeout(response.arrayBuffer(), timeoutMs, () => { }, "body-read");
+        const buffer = await withSessionFileTransferTimeout(response.arrayBuffer(), timeoutMs, () => { }, "body-read");
         return new Uint8Array(buffer);
     }
     const reader = body.getReader();
     const chunks = [];
     try {
         while (true) {
-            const { done, value } = await withOutputTransferTimeout(reader.read(), timeoutMs, () => {
+            const { done, value } = await withSessionFileTransferTimeout(reader.read(), timeoutMs, () => {
                 void reader.cancel().catch(() => { });
             }, "body-read");
             if (done)
@@ -534,7 +530,7 @@ async function readCappedText(response, maxBytes, timeoutMs) {
     const body = response.body;
     if (!body) {
         // No streaming body (some fetch polyfills) — buffer, then slice to the cap.
-        const buf = new Uint8Array(await withOutputTransferTimeout(response.arrayBuffer(), timeoutMs, () => { }, "body-read"));
+        const buf = new Uint8Array(await withSessionFileTransferTimeout(response.arrayBuffer(), timeoutMs, () => { }, "body-read"));
         const total = declared ?? buf.byteLength;
         return {
             text: decoder.decode(buf.subarray(0, maxBytes)),
@@ -548,7 +544,7 @@ async function readCappedText(response, maxBytes, timeoutMs) {
     let sawMore = false;
     try {
         while (read < maxBytes) {
-            const { done, value } = await withOutputTransferTimeout(reader.read(), timeoutMs, () => {
+            const { done, value } = await withSessionFileTransferTimeout(reader.read(), timeoutMs, () => {
                 void reader.cancel().catch(() => { });
             }, "body-read");
             if (done)
@@ -560,7 +556,7 @@ async function readCappedText(response, maxBytes, timeoutMs) {
         }
         if (read >= maxBytes) {
             // We hit the cap; peek once more to learn whether bytes remain, then stop.
-            const next = await withOutputTransferTimeout(reader.read(), timeoutMs, () => {
+            const next = await withSessionFileTransferTimeout(reader.read(), timeoutMs, () => {
                 void reader.cancel().catch(() => { });
             }, "body-read");
             if (!next.done && next.value && next.value.byteLength > 0)
@@ -597,47 +593,41 @@ function grepLines(text, pattern) {
         .join("\n");
 }
 /**
- * List a run's subagent CHILD runs (`GET /runs/:id/children`). Each row is a
- * {@link ChildRunRef} whose `id` resolves through the run facade (getRun /
- * events / outputs) — so every child the platform hands you is resolvable. An
- * empty array means the run spawned no children.
+ * List a session's subagent child sessions (`GET /sessions/:id/children`). Each row is a
+ * {@link ChildSessionRef} whose `id` resolves through the session record facade (getSessionRecord /
+ * events / files) — so every child the platform hands you is resolvable. An
+ * empty array means the session spawned no children.
  */
-export async function listRunChildren(http, runId) {
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/children`);
+export async function listSessionChildren(http, sessionId) {
+    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/children`);
     return Array.isArray(result)
         ? result
         : result.children;
 }
-export async function cancelRun(http, runId) {
-    await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
-}
-export async function deleteRun(http, runId) {
-    await http.request(`/api/runs/${encodeURIComponent(runId)}`, { method: "DELETE" });
-}
 /**
- * List a run's webhook delivery attempts (the per-run delivery ledger). Returns
- * the rows surfaced by `GET /api/runs/:id/webhook-deliveries`; an empty array
- * means the run carried no `webhook` or has not reached a terminal state yet.
+ * List a session's webhook delivery attempts (the per-session delivery ledger). Returns
+ * the rows surfaced by `GET /api/sessions/:id/webhook-deliveries`; an empty array
+ * means the session carried no `webhook` or has not reached a terminal state yet.
  */
-export async function getRunWebhookDeliveries(http, runId) {
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/webhook-deliveries`);
+export async function getSessionWebhookDeliveries(http, sessionId) {
+    const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/webhook-deliveries`);
     return Array.isArray(result)
         ? result
         : result.deliveries;
 }
 /**
- * Manually re-trigger a run's webhook delivery: resets the row to `pending` and
+ * Manually re-trigger a session's webhook delivery: resets the row to `pending` and
  * re-sends the frozen payload with the SAME `webhook-id` so the consumer
  * dedupes. Idempotent from the caller's view.
  */
-export async function redeliverRunWebhook(http, runId, deliveryId) {
-    await http.request(`/api/runs/${encodeURIComponent(runId)}/webhook-deliveries/${encodeURIComponent(deliveryId)}/redeliver`, { method: "POST" });
+export async function redeliverSessionWebhook(http, sessionId, deliveryId) {
+    await http.request(`/api/sessions/${encodeURIComponent(sessionId)}/webhook-deliveries/${encodeURIComponent(deliveryId)}/redeliver`, { method: "POST" });
 }
 /**
  * Delete a workspace asset cache entry. Accepts an `asset_<id>` value,
  * `sha256:<hex>`, or a bare 64-hex digest. Workspace is derived server-side
  * from the token; idempotent.
- * Does NOT affect runs that already snapshotted the asset.
+ * Does NOT affect sessions that already snapshotted the asset.
  */
 export async function deleteWorkspaceAsset(http, hash) {
     const assetId = hash.startsWith("asset_")
@@ -698,23 +688,23 @@ export async function getWebhookSigningSecret(http) {
 }
 /**
  * Download each artifact's bytes into a zip-file map keyed by
- * `<zipPrefix><relative-path>`, fetched from the `outputs`
+ * `<zipPrefix><relative-path>`, fetched from the `files`
  * download route. Best-effort: a per-artifact fetch failure records an
  * `errors[]` entry rather than aborting the rest, so the failure is
  * surfaced (never silent) while a partially-available run still yields a
  * usable zip.
  */
-async function collectArtifactBytes(http, runId, items, zipPrefix, namespace, timeoutMs = OUTPUT_FILE_TRANSFER_DEFAULT_TIMEOUT_MS) {
+async function collectArtifactBytes(http, sessionId, items, zipPrefix, namespace, timeoutMs = SESSION_FILE_TRANSFER_DEFAULT_TIMEOUT_MS) {
     const entries = [];
     const captured = [];
     const errors = [];
     for (const item of items) {
         const rel = item.filename ?? item.id;
         try {
-            const path = `/api/runs/${encodeURIComponent(runId)}/${namespace}/${encodeURIComponent(item.id)}/download`;
+            const path = `/api/sessions/${encodeURIComponent(sessionId)}/${namespace}/${encodeURIComponent(item.id)}/download`;
             entries.push({
                 path: `${zipPrefix}${rel}`,
-                bytes: await downloadOutputBytesWithRetry(http, path, timeoutMs),
+                bytes: await downloadSessionFileBytesWithRetry(http, path, timeoutMs),
                 ...(item.contentType !== undefined ? { contentType: item.contentType } : {}),
                 customerContent: true
             });
@@ -737,17 +727,17 @@ function eventsJsonl(events) {
 function isPathSelector(selector) {
     return Boolean(selector && typeof selector === "object" && "path" in selector);
 }
-function normalizeOutputLookupPath(path) {
+function normalizeSessionFileLookupPath(path) {
     return path.replace(/\\/g, "/").replace(/^\/+/, "");
 }
-export function filterOutputs(outputs, query) {
-    return outputs.filter((output) => outputMatchesQuery(output, query));
+export function filterSessionFiles(files, query) {
+    return files.filter((file) => sessionFileMatchesQuery(file, query));
 }
 /**
- * The single filename-matcher for cross-run / per-session output SEARCH. A
+ * The single filename-matcher for cross-session / per-session file SEARCH. A
  * string is a case-insensitive SUBSTRING match; a RegExp is tested as given (and
  * reset to `lastIndex = 0` so a reused `/g` regex is safe). Sharing this SSoT is
- * what closes the T16 crash class: `searchOutputs` no longer assumes `filename`
+ * what closes the T16 crash class: session-file search no longer assumes `filename`
  * is a string and passes a RegExp into `escapeRegExp(...).replace(...)`.
  */
 export function toFilenameMatcher(filename) {
@@ -760,8 +750,8 @@ export function toFilenameMatcher(filename) {
         return filename.test(name);
     };
 }
-export function classifyOutput(output) {
-    const contentType = normalizeContentType(output.contentType);
+export function classifySessionFile(file) {
+    const contentType = normalizeContentType(file.contentType);
     if (contentType) {
         if (contentType === "application/json" || contentType.endsWith("+json") || contentType.includes("json")) {
             return "json";
@@ -789,7 +779,7 @@ export function classifyOutput(output) {
             return "binary";
         return "unknown";
     }
-    const extension = extensionOf(output.filename);
+    const extension = extensionOf(file.filename);
     if (!extension)
         return "unknown";
     if (["json", "jsonl", "ndjson"].includes(extension))
@@ -812,10 +802,10 @@ export function classifyOutput(output) {
         return "binary";
     return "unknown";
 }
-export function normalizeOutputLinkExpiresIn(input = "1h") {
+export function normalizeSessionFileLinkExpiresIn(input = "1h") {
     if (typeof input === "number") {
         if (!Number.isFinite(input) || input <= 0) {
-            throw new RunStateError("outputLink: expiresIn must be a positive number of seconds", {
+            throw new SessionStateError("sessionFileLink: expiresIn must be a positive number of seconds", {
                 expiresIn: input
             });
         }
@@ -827,34 +817,34 @@ export function normalizeOutputLinkExpiresIn(input = "1h") {
         return 60 * 60;
     if (input === "1d")
         return 24 * 60 * 60;
-    throw new RunStateError("outputLink: expiresIn must be seconds, \"15m\", \"1h\", or \"1d\"", {
+    throw new SessionStateError("sessionFileLink: expiresIn must be seconds, \"15m\", \"1h\", or \"1d\"", {
         expiresIn: input
     });
 }
-async function resolveOutputLinkTarget(http, runId, selectorOrQuery) {
+async function resolveSessionFileLinkTarget(http, sessionId, selectorOrQuery) {
     if (typeof selectorOrQuery === "string") {
         if (selectorOrQuery.length === 0) {
-            throw new RunStateError("outputLink: selector must include an output id or query", { runId });
+            throw new SessionStateError("sessionFileLink: selector must include a file id or query", { sessionId });
         }
         return { id: selectorOrQuery };
     }
-    if (hasOutputId(selectorOrQuery)) {
+    if (hasSessionFileId(selectorOrQuery)) {
         if (selectorOrQuery.id.length === 0) {
-            throw new RunStateError("outputLink: selector must include an output id or query", { runId });
+            throw new SessionStateError("sessionFileLink: selector must include a file id or query", { sessionId });
         }
         return selectorOrQuery;
     }
     if (isPathSelector(selectorOrQuery) && selectorOrQuery.match === "suffix") {
-        return resolveOutputFileSelector(await listOutputs(http, runId), selectorOrQuery, runId);
+        return resolveSessionFileSelector(await listSessionFiles(http, sessionId), selectorOrQuery, sessionId);
     }
-    const match = await findOutput(http, runId, selectorOrQuery);
+    const match = await findSessionFile(http, sessionId, selectorOrQuery);
     if (match)
         return match;
-    throw new RunStateError("outputLink: output query matched no files", { runId });
+    throw new SessionStateError("sessionFileLink: file query matched no files", { sessionId });
 }
-function outputMatchesQuery(output, query) {
-    const normalizedPath = typeof output.filename === "string" ? normalizeOutputQueryPath(output.filename) : "";
-    if (query.path !== undefined && normalizedPath !== normalizeOutputQueryPath(query.path)) {
+function sessionFileMatchesQuery(file, query) {
+    const normalizedPath = typeof file.filename === "string" ? normalizeSessionFileQueryPath(file.filename) : "";
+    if (query.path !== undefined && normalizedPath !== normalizeSessionFileQueryPath(query.path)) {
         return false;
     }
     if (query.filename !== undefined) {
@@ -875,21 +865,21 @@ function outputMatchesQuery(output, query) {
     if (query.extension !== undefined && extensionOf(normalizedPath) !== normalizeExtension(query.extension)) {
         return false;
     }
-    if (query.contentType !== undefined && !contentTypeMatches(output.contentType, query.contentType)) {
+    if (query.contentType !== undefined && !contentTypeMatches(file.contentType, query.contentType)) {
         return false;
     }
-    if (query.type !== undefined && classifyOutput(output) !== query.type) {
+    if (query.type !== undefined && classifySessionFile(file) !== query.type) {
         return false;
     }
     return true;
 }
-function hasOutputId(value) {
+function hasSessionFileId(value) {
     return Boolean(value && typeof value === "object" && "id" in value && typeof value.id === "string");
 }
-function normalizeOutputQueryPath(path) {
+function normalizeSessionFileQueryPath(path) {
     let normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
-    while (normalized === "outputs" || normalized.startsWith("outputs/")) {
-        normalized = normalized === "outputs" ? "" : normalized.slice("outputs/".length);
+    while (normalized === "files" || normalized.startsWith("files/")) {
+        normalized = normalized === "files" ? "" : normalized.slice("files/".length);
     }
     return normalized.replace(/\/+$/, "");
 }
@@ -897,7 +887,7 @@ function basenameOf(path) {
     return path.split("/").filter(Boolean).pop() ?? "";
 }
 function directoryMatches(path, dir, recursive) {
-    const normalizedDir = normalizeOutputQueryPath(dir);
+    const normalizedDir = normalizeSessionFileQueryPath(dir);
     if (normalizedDir.length === 0)
         return true;
     const prefix = `${normalizedDir}/`;
@@ -912,7 +902,7 @@ function normalizeExtension(extension) {
 function extensionOf(path) {
     if (!path)
         return "";
-    const basename = basenameOf(normalizeOutputQueryPath(path));
+    const basename = basenameOf(normalizeSessionFileQueryPath(path));
     const index = basename.lastIndexOf(".");
     return index > 0 && index < basename.length - 1 ? basename.slice(index + 1).toLowerCase() : "";
 }
@@ -930,64 +920,64 @@ function contentTypeMatches(actual, expected) {
     return normalizedActual === normalizedExpected;
 }
 /**
- * Download EVERYTHING public about a run as one zip, organised into the three
+ * Download EVERYTHING public about a session as one zip, organised into the three
  * namespace folders:
  *
- *   metadata/run.json     — the run record.
+ *   metadata/session.json     — the session record.
  *   events/events.jsonl   — typed event-channel records.
- *   outputs/<rel>         — the run's deliverables.
- *   manifest.json         — `RunRecordManifestV1`.
+ *   files/<rel>       — the session's captured files.
+ *   manifest.json         — `SessionRecordManifestV1`.
  */
-export async function download(http, runId) {
-    const [run, events, outputs] = await Promise.all([
-        getRun(http, runId),
-        listRunEvents(http, runId),
-        listOutputs(http, runId)
+export async function download(http, sessionId) {
+    const [sessionRecord, events, files] = await Promise.all([
+        getSessionRecord(http, sessionId),
+        listSessionRecordEvents(http, sessionId),
+        listSessionFiles(http, sessionId)
     ]);
-    const out = await collectArtifactBytes(http, runId, outputs, "outputs/", "outputs");
-    const submissionSnapshot = extractSubmissionSnapshot(run);
-    const costTelemetry = extractCostTelemetry(run);
-    const manifest = buildRunRecordDownloadManifestV1({
-        runId,
-        outputs: out.captured,
-        errors: out.errors,
+    const collectedFiles = await collectArtifactBytes(http, sessionId, files, "files/", "files");
+    const submissionSnapshot = extractSubmissionSnapshot(sessionRecord);
+    const costTelemetry = extractCostTelemetry(sessionRecord);
+    const manifest = buildSessionRecordDownloadManifestV1({
+        sessionId,
+        sessionFiles: collectedFiles.captured,
+        errors: collectedFiles.errors,
         typedEventCount: events.length,
         ...(submissionSnapshot ? { submission: { status: "present" } } : {}),
         ...(costTelemetry ? { cost: { status: "present" } } : {})
     });
     return zipEntries([
-        jsonEntry("metadata/run.json", run),
+        jsonEntry("metadata/session.json", sessionRecord),
         ...(submissionSnapshot ? [jsonEntry("metadata/submission.json", submissionSnapshot)] : []),
         ...(costTelemetry ? [jsonEntry("metadata/cost.json", costTelemetry)] : []),
         jsonlEntry("events/events.jsonl", events),
-        ...out.entries,
+        ...collectedFiles.entries,
         jsonEntry("manifest.json", manifest)
     ]);
 }
 /**
- * Download only the run's deliverables (the `outputs` namespace). Zip
+ * Download only the session's captured files (the `files` namespace). Zip
  * layout: `<rel>` per file plus a `manifest.json`
- * (`{ runId, namespace: "outputs", outputs[], errors[] }`).
+ * (`{ sessionId, namespace: "files", files[], errors[] }`).
  */
-export async function downloadOutputs(http, runId, options) {
-    const outputs = await listOutputs(http, runId);
-    const timeoutMs = normalizeOutputTransferTimeoutMs(options?.timeoutMs);
-    const { entries, captured, errors } = await collectArtifactBytes(http, runId, outputs, "", "outputs", timeoutMs);
+export async function downloadSessionFiles(http, sessionId, options) {
+    const files = await listSessionFiles(http, sessionId);
+    const timeoutMs = normalizeSessionFileTransferTimeoutMs(options?.timeoutMs);
+    const { entries, captured, errors } = await collectArtifactBytes(http, sessionId, files, "", "files", timeoutMs);
     return zipEntries([
         ...entries,
-        jsonEntry("manifest.json", { runId, namespace: "outputs", outputs: captured, errors })
+        jsonEntry("manifest.json", { sessionId, namespace: "files", files: captured, errors })
     ]);
 }
 /**
  * Download only the event archive (the `events` namespace). Always includes
  * typed `events.jsonl` plus `manifest.json`.
  */
-export async function downloadEvents(http, runId) {
-    const events = await listRunEvents(http, runId);
+export async function downloadEvents(http, sessionId) {
+    const events = await listSessionRecordEvents(http, sessionId);
     return zipEntries([
         jsonlEntry("events.jsonl", events),
         jsonEntry("manifest.json", {
-            runId,
+            sessionId,
             namespace: "events",
             files: [{ path: "events.jsonl", role: "typed_events", status: "present", recordCount: events.length }],
             errors: []
@@ -995,23 +985,23 @@ export async function downloadEvents(http, runId) {
     ]);
 }
 /**
- * Download only the run record (the `metadata` namespace) as a zip
- * containing `run.json` plus `manifest.json`.
+ * Download only the session record (the `metadata` namespace) as a zip
+ * containing `session.json` plus `manifest.json`.
  */
-export async function downloadMetadata(http, runId) {
-    const run = await getRun(http, runId);
+export async function downloadMetadata(http, sessionId) {
+    const sessionRecord = await getSessionRecord(http, sessionId);
     return zipEntries([
-        jsonEntry("run.json", run),
+        jsonEntry("session.json", sessionRecord),
         jsonEntry("manifest.json", {
-            runId,
+            sessionId,
             namespace: "metadata",
-            files: [{ path: "run.json", role: "run_metadata", status: "present" }],
+            files: [{ path: "session.json", role: "session_metadata", status: "present" }],
             errors: []
         })
     ]);
 }
 function zipEntries(entries) {
-    assertRunRecordArchivePublicSafeV1(entries);
+    assertSessionRecordArchivePublicSafeV1(entries);
     const files = {};
     for (const entry of entries) {
         files[entry.path] = entry.bytes;
@@ -1032,8 +1022,8 @@ function jsonlEntry(path, events) {
         contentType: "application/jsonl; charset=utf-8"
     };
 }
-function extractSubmissionSnapshot(run) {
-    const raw = run.submission;
+function extractSubmissionSnapshot(sessionRecord) {
+    const raw = sessionRecord.submission;
     if (!isRecord(raw) || raw.kind !== "submission" || !isRecord(raw.submission)) {
         return undefined;
     }
@@ -1041,18 +1031,18 @@ function extractSubmissionSnapshot(run) {
         submission: raw.submission
     };
 }
-function extractCostTelemetry(run) {
-    const raw = run.costTelemetry;
+function extractCostTelemetry(sessionRecord) {
+    const raw = sessionRecord.costTelemetry;
     return isRecord(raw) ? raw : undefined;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 // ===========================================================================
-// Run submission operations (McpServer / run config composition)
+// SessionRecord submission operations (McpServer / session config composition)
 // ===========================================================================
-export async function submitRun(http, request) {
-    return http.request("/api/runs", {
+export async function startSessionRecord(http, request) {
+    return http.request("/api/sessions", {
         method: "POST",
         body: JSON.stringify(request)
     });
@@ -1200,8 +1190,8 @@ function unwrapSkill(result) {
     }
     return result;
 }
-function hasRun(value) {
-    return Boolean(value && typeof value === "object" && "run" in value);
+function hasSessionRecord(value) {
+    return Boolean(value && typeof value === "object" && "session" in value);
 }
 function unwrapSession(result) {
     if (result && typeof result === "object" && "session" in result) {
@@ -1212,7 +1202,7 @@ function unwrapSession(result) {
 /**
  * Upload bytes to the hosted API's content-addressable asset endpoint.
  * Returns a storage-neutral asset id suitable for `kind:"asset"` refs in a
- * later run submission.
+ * later session submission.
  */
 export async function uploadWorkspaceAsset(http, input) {
     return http.request("/assets", {