@aexhq/sdk 0.26.5 → 0.27.0

package/dist/_contracts/operations.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from "./http.js";
 import type { RunUnit } from "./run-unit.js";
-import type { AgentsMdRecord, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, Run, RunEvent, RunWebhookDelivery, SecretRecord, SecretReveal, Skill, WhoAmI } from "./runtime-types.js";
+import type { AgentsMdRecord, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, RunEvent, RunListPage, RunListQuery, RunWebhookDelivery, SecretRecord, SecretReveal, Skill, WhoAmI } from "./runtime-types.js";
 import type { PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -27,6 +27,16 @@ export declare function getRun(http: HttpClient, runId: string): Promise<Run>;
  * stays for callers that only need the loose record.
  */
 export declare function getRunUnit(http: HttpClient, runId: string): Promise<RunUnit>;
+/**
+ * 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
+ * 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.
+ */
+export declare function listRuns(http: HttpClient, query?: RunListQuery): Promise<RunListPage>;
 /**
  * List a run's events. The read endpoint is PAGED (bounded per response so a
  * long run can't return an unbounded body); this follows `nextCursor` across
@@ -56,6 +66,20 @@ export declare function createOutputLink(http: HttpClient, runId: string, select
 export declare function eventArchiveLink(http: HttpClient, runId: string, options?: OutputLinkOptions): Promise<OutputLink>;
 export declare function resolveOutputFileSelector(outputs: readonly Output[], selector: OutputFileSelector, runId?: string): Output;
 export declare function downloadOutput(http: HttpClient, runId: string, selector: OutputFileSelector): Promise<OutputFileDownload>;
+/** Byte ceiling for {@link readOutputText} — a hard cap even if a caller asks for more. */
+export declare const READ_OUTPUT_TEXT_MAX_BYTES = 10000000;
+/** Default `maxBytes` for {@link readOutputText} — a chat-sized preview. */
+export declare const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50000;
+/**
+ * Read ONE output file as byte-capped, decoded UTF-8 text. Built for handing a run
+ * 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.
+ */
+export declare function readOutputText(http: HttpClient, runId: string, selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
 export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
 export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
 /**

package/dist/_contracts/operations.js

@@ -31,6 +31,27 @@ export async function getRun(http, runId) {
 export async function getRunUnit(http, runId) {
     return http.request(`/api/runs/${encodeURIComponent(runId)}`);
 }
+/**
+ * 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
+ * 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.
+ */
+export async function listRuns(http, query) {
+    const params = {};
+    if (query?.status !== undefined)
+        params.status = query.status;
+    if (query?.since !== undefined)
+        params.since = query.since;
+    if (query?.limit !== undefined)
+        params.limit = String(query.limit);
+    if (query?.cursor !== undefined)
+        params.cursor = query.cursor;
+    return http.request("/api/runs", {}, params);
+}
 // 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
 // server that never clears `nextCursor` can't loop forever.
@@ -146,6 +167,100 @@ export async function downloadOutput(http, runId, selector) {
     const { response } = await http.download(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`);
     return { output, bytes: new Uint8Array(await response.arrayBuffer()) };
 }
+/** 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;
+/**
+ * Read ONE output file as byte-capped, decoded UTF-8 text. Built for handing a run
+ * 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.
+ */
+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 { response } = await http.download(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(output.id)}/download`);
+    const capped = await readCappedText(response, maxBytes);
+    const text = options?.grep === undefined ? capped.text : grepLines(capped.text, options.grep);
+    return { output, text, truncated: capped.truncated, totalBytes: capped.totalBytes };
+}
+/**
+ * Read a streamed response body up to `maxBytes`, decode as UTF-8, and report
+ * whether the file was larger than the cap. Prefers the `content-length` header
+ * for `totalBytes`; falls back to the bytes actually read. Cancels the stream
+ * once the cap is reached so the remainder is never transferred.
+ */
+async function readCappedText(response, maxBytes) {
+    const declaredRaw = response.headers.get("content-length");
+    const declared = declaredRaw !== null && /^\d+$/.test(declaredRaw) ? Number(declaredRaw) : undefined;
+    const decoder = new TextDecoder("utf-8");
+    const body = response.body;
+    if (!body) {
+        // No streaming body (some fetch polyfills) — buffer, then slice to the cap.
+        const buf = new Uint8Array(await response.arrayBuffer());
+        const total = declared ?? buf.byteLength;
+        return {
+            text: decoder.decode(buf.subarray(0, maxBytes)),
+            truncated: buf.byteLength > maxBytes,
+            totalBytes: total
+        };
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let read = 0;
+    let sawMore = false;
+    try {
+        while (read < maxBytes) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value && value.byteLength > 0) {
+                read += value.byteLength;
+                chunks.push(value);
+            }
+        }
+        if (read >= maxBytes) {
+            // We hit the cap; peek once more to learn whether bytes remain, then stop.
+            const next = await reader.read();
+            if (!next.done && next.value && next.value.byteLength > 0)
+                sawMore = true;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const merged = concatBytes(chunks).subarray(0, maxBytes);
+    const truncated = declared !== undefined ? declared > maxBytes : sawMore;
+    const totalBytes = declared ?? read;
+    return { text: decoder.decode(merged), truncated, totalBytes };
+}
+function concatBytes(chunks) {
+    if (chunks.length === 1)
+        return chunks[0];
+    const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.byteLength;
+    }
+    return out;
+}
+function grepLines(text, pattern) {
+    const test = typeof pattern === "string"
+        ? (line) => line.toLowerCase().includes(pattern.toLowerCase())
+        : (line) => pattern.test(line);
+    return text
+        .split("\n")
+        .filter((line) => test(line))
+        .join("\n");
+}
 export async function cancelRun(http, runId) {
     await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
 }

package/dist/_contracts/runtime-types.d.ts

@@ -45,6 +45,40 @@ export interface UsageSummary {
     readonly cacheCreationInputTokens?: number;
     readonly totalTokens?: number;
 }
+/**
+ * Filters for {@link import("./operations.js").listRuns} / `AgentExecutor.listRuns`.
+ * Every field is optional; omitting all of them lists the most recent runs in the
+ * token's workspace. Workspace identity is derived server-side from the API token,
+ * so there is no `workspaceId` here — a token can only ever enumerate its own runs.
+ */
+export interface RunListQuery {
+    /** Restrict to a single run status, e.g. `"succeeded"`. */
+    readonly status?: string;
+    /** ISO-8601 lower bound on `createdAt` (inclusive). */
+    readonly since?: string;
+    /** Page size. Defaults to 25, clamped server-side to [1, 100]. */
+    readonly limit?: number;
+    /** Opaque keyset cursor from a prior page's `nextCursor`. */
+    readonly cursor?: string;
+}
+/**
+ * A public-safe run summary as returned by `GET /api/runs` (the workspace run
+ * list). DELIBERATELY omits the submission snapshot (model/prompt/env) — the full,
+ * redaction-scanned submission is only reachable through `getRunUnit(runId)`.
+ */
+export interface RunSummary {
+    readonly id: string;
+    readonly status: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** Settled showback estimate (USD), present once the run has cost telemetry. */
+    readonly costUsd?: number;
+}
+/** One page of the workspace run list. `nextCursor` absent ⇒ last page. */
+export interface RunListPage {
+    readonly runs: readonly RunSummary[];
+    readonly nextCursor?: string;
+}
 /**
  * A run event as recorded by the dashboard. Includes the `type` field
  * that the `is*Event` type guards narrow on plus any provider payload.
@@ -150,6 +184,39 @@ export interface OutputFileDownload {
     readonly output: Output;
     readonly bytes: Uint8Array;
 }
+/** Options for `AgentExecutor.readOutputText` / {@link import("./operations.js").readOutputText}. */
+export interface ReadOutputTextOptions {
+    /**
+     * Stop reading after this many bytes. Defaults to 50_000; clamped server-side
+     * of the SDK to [1, 10_000_000]. The read streams and cancels once the cap is
+     * reached, so the remainder of a large file is never transferred.
+     */
+    readonly maxBytes?: number;
+    /**
+     * When set, return only the lines of the (capped) text matching this pattern.
+     * A string is matched literally (case-insensitive); a RegExp is used as given.
+     */
+    readonly grep?: string | RegExp;
+}
+/**
+ * A byte-capped, decoded text read of one output file, as returned by
+ * `AgentExecutor.readOutputText`. Built for feeding run deliverables to an LLM
+ * without loading the whole (possibly very large) file into memory or context:
+ * the read streams and stops at `maxBytes`, so `text` is at most that many bytes
+ * decoded as UTF-8. Check {@link truncated} before treating `text` as complete.
+ */
+export interface OutputText {
+    readonly output: Output;
+    /** Decoded UTF-8, capped to the requested `maxBytes`. */
+    readonly text: string;
+    /** True when the file is larger than `maxBytes` (so `text` is a prefix). */
+    readonly truncated: boolean;
+    /**
+     * Full size of the file in bytes when the server reports it (`content-length`);
+     * otherwise the number of bytes actually read.
+     */
+    readonly totalBytes: number;
+}
 export type OutputLinkExpiresIn = number | "15m" | "1h" | "1d";
 export interface OutputLinkOptions {
     /** Seconds or one of the documented presets. Defaults to `"1h"`. */

package/dist/_contracts/submission.d.ts

@@ -354,23 +354,24 @@ export interface PlatformSubmission {
      */
     readonly outputs?: PlatformOutputCaptureConfig;
     /**
-     * Optional override for the managed-runtime builtins enabled inside the
-     * runner container. Each entry is one of the closed {@link BUILTINS} set
-     * (prefer the {@link Builtins} symbol const).
+     * Whether to inject the standard builtin tool set ({@link DEFAULT_BUILTIN_TOOLS}).
      *
-     * Omit the field for {@link DEFAULT_BUILTINS}: web search, web fetch,
-     * file read/edit, glob, grep, head, and tail. Pass an empty array to opt out
-     * of all builtins for pure-MCP runs. Pass a custom list to narrow or extend
-     * the tool surface, for example `[Builtins.WEB_SEARCH, Builtins.NOTEBOOK]`.
+     *   - omitted / `true` (default): inject the standard builtins.
+     *   - `false`: inject NO builtins — useful for a pure-MCP / pure-custom run.
      *
-     * Validation:
-     *   - Each entry must be a member of {@link BUILTINS}.
-     *   - Max 16 entries.
-     *   - Deduplicated.
-     *
-     * The dispatcher accepts and persists it for snapshot fidelity.
+     * Cherry-pick individual builtins (e.g. opt the notebook in, or pick a narrow
+     * subset alongside `includeBuiltinTools: false`) by listing their names in
+     * `tools` (a bare-string builtin reference, prefer `BuiltinTools.<name>`).
+     */
+    readonly includeBuiltinTools?: boolean;
+    /**
+     * Explicit builtin tool NAME references the caller listed in the wire `tools`
+     * union (the bare-string members), extracted at parse time. Each is a member
+     * of {@link BUILTIN_TOOL_NAMES}. Composed with {@link includeBuiltinTools} via
+     * {@link resolveBuiltinToolNames} to produce the run's final builtin tool set.
+     * `tools` itself carries only the custom tool bundles ({@link ToolRef}).
      */
-    readonly builtins?: readonly Builtin[];
+    readonly builtinTools?: readonly BuiltinToolName[];
     /**
      * Assistant-output granularity. `buffered` (the default) emits one event per
      * assistant message; `stream` emits the agent's per-token text deltas as they
@@ -561,56 +562,69 @@ export declare const OUTPUT_MODES: readonly ["buffered", "stream"];
 export type OutputMode = (typeof OUTPUT_MODES)[number];
 export declare const DEFAULT_OUTPUT_MODE: OutputMode;
 /**
- * Managed-runtime builtins — the closed set the managed runtime accepts.
- * Closed so an invalid name is a compile error via {@link Builtins}, not a
- * silent runtime no-op.
+ * The CLOSED set of builtin tool NAMES the managed runtime can inject — one per
+ * machine tool the hands implement. This list is the single source of truth for
+ * validating builtin tool references; the platform's `HANDS_TOOLS` (the execute
+ * vocabulary) is pinned EQUAL to it at module load (`platform-runtime-agent`
+ * `assertNamesMatch`), so a rename on either side fails loudly rather than
+ * silently shipping a name the executors do not speak.
+ *
+ * Order mirrors `HANDS_TOOLS`. A builtin tool reference (a bare string in
+ * `submission.tools`) must be a member of this set.
+ */
+export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "notebook_edit", "bash_output", "bash_kill", "code_execution", "wait", "git"];
+export type BuiltinToolName = (typeof BUILTIN_TOOL_NAMES)[number];
+/**
+ * Typo-safe accessors for the closed builtin tool set: each key maps to the
+ * real tool NAME string. Reference a builtin in `submission.tools` via
+ * `BuiltinTools.notebook_edit` rather than the bare string so a rename is a
+ * compile error, not a runtime 400.
  *
- * The first entries are the recommended concrete builtins. The legacy aggregate
- * extension names remain accepted for existing callers, but are not the default.
+ * Keys are the real tool names; a unit test asserts `Object.values(BuiltinTools)`
+ * deep-equals `BUILTIN_TOOL_NAMES` so the two can never drift.
  */
-export declare const BUILTINS: readonly ["web_search", "web_fetch", "read", "edit", "glob", "grep", "head", "tail", "bash", "notebook", "developer", "computercontroller", "memory", "autovisualiser", "tutorial"];
-export type Builtin = (typeof BUILTINS)[number];
+export declare const BuiltinTools: {
+    readonly bash: "bash";
+    readonly read_file: "read_file";
+    readonly write_file: "write_file";
+    readonly edit_file: "edit_file";
+    readonly grep: "grep";
+    readonly glob: "glob";
+    readonly head: "head";
+    readonly tail: "tail";
+    readonly todo_write: "todo_write";
+    readonly subagent: "subagent";
+    readonly subagent_result: "subagent_result";
+    readonly web_fetch: "web_fetch";
+    readonly web_search: "web_search";
+    readonly notebook_edit: "notebook_edit";
+    readonly bash_output: "bash_output";
+    readonly bash_kill: "bash_kill";
+    readonly code_execution: "code_execution";
+    readonly wait: "wait";
+    readonly git: "git";
+};
 /**
- * DX-first managed-runtime defaults. Omitted `builtins` resolves to this list.
- * Notebook support remains opt-in through {@link Builtins.NOTEBOOK}.
+ * The default builtin tool set injected when `includeBuiltinTools !== false`:
+ * every builtin tool EXCEPT `notebook_edit` (notebook editing stays opt-in —
+ * add `BuiltinTools.notebook_edit` to `tools` to enable it). Derived by
+ * filtering {@link BUILTIN_TOOL_NAMES} so it can never drift from the closed
+ * set.
  */
-export declare const DEFAULT_BUILTINS: readonly ["web_search", "web_fetch", "read", "edit", "glob", "grep", "head", "tail", "bash"];
+export declare const DEFAULT_BUILTIN_TOOLS: readonly BuiltinToolName[];
 /**
- * Symbol-style accessors for the closed builtin set, e.g.
- * `Builtins.WEB_SEARCH`.
+ * Resolve the set of builtin tool NAMES a submission injects, deduplicated and
+ * in {@link BUILTIN_TOOL_NAMES} order.
+ *
+ *   - `includeBuiltinTools !== false` ⇒ start from {@link DEFAULT_BUILTIN_TOOLS}
+ *     (the standard set); `false` ⇒ start from none (pure-MCP / pure-custom).
+ *   - union in every builtin-name string the caller listed in `tools` (a
+ *     cherry-pick, e.g. `BuiltinTools.notebook_edit` to opt the notebook in).
+ *
+ * Every `toolRefs` string MUST be a member of {@link BUILTIN_TOOL_NAMES}; the
+ * union is validated ⊆ the closed set so an invalid name can never leak through.
  */
-export declare const Builtins: {
-    /** Managed web search. Included in {@link DEFAULT_BUILTINS}. */
-    readonly WEB_SEARCH: "web_search";
-    /** Fetch a URL and return readable text. Included in {@link DEFAULT_BUILTINS}. */
-    readonly WEB_FETCH: "web_fetch";
-    /** Read files. Included in {@link DEFAULT_BUILTINS}. */
-    readonly READ: "read";
-    /** Create/modify files. Included in {@link DEFAULT_BUILTINS}. */
-    readonly EDIT: "edit";
-    /** Search paths by glob. Included in {@link DEFAULT_BUILTINS}. */
-    readonly GLOB: "glob";
-    /** Search file contents. Included in {@link DEFAULT_BUILTINS}. */
-    readonly GREP: "grep";
-    /** Read the first lines of a file. Included in {@link DEFAULT_BUILTINS}. */
-    readonly HEAD: "head";
-    /** Read the last lines of a file. Included in {@link DEFAULT_BUILTINS}. */
-    readonly TAIL: "tail";
-    /** Shell command execution. Included in {@link DEFAULT_BUILTINS}. */
-    readonly BASH: "bash";
-    /** Jupyter notebook editing. Optional; not in {@link DEFAULT_BUILTINS}. */
-    readonly NOTEBOOK: "notebook";
-    /** Legacy aggregate: shell/filesystem/navigation/web/notebook tools. */
-    readonly DEVELOPER: "developer";
-    /** Legacy aggregate alias retained for existing callers. */
-    readonly COMPUTER_CONTROLLER: "computercontroller";
-    /** Legacy aggregate alias retained for existing callers. */
-    readonly MEMORY: "memory";
-    /** Legacy aggregate alias retained for existing callers. */
-    readonly AUTOVISUALISER: "autovisualiser";
-    /** Legacy aggregate alias retained for existing callers. */
-    readonly TUTORIAL: "tutorial";
-};
+export declare function resolveBuiltinToolNames(includeBuiltinTools: boolean | undefined, toolRefs?: readonly string[]): readonly BuiltinToolName[];
 /**
  * Codes emitted when a submission contains features the active runtime cannot
  * serve. Code values are stable so dashboard / SDK error rendering can branch