@aexhq/sdk 0.26.5 → 0.27.0

package/dist/_contracts/submission.js

@@ -1233,7 +1233,7 @@ export function parseSubmission(input) {
         "securityProfile",
         "metadata",
         "outputs",
-        "builtins",
+        "includeBuiltinTools",
         "outputMode",
         "platform"
     ]);
@@ -1246,7 +1246,7 @@ export function parseSubmission(input) {
     const system = optionalString(value.system, "submission.system");
     const prompt = parsePrompt(value.prompt);
     const skills = parseSkills(value.skills);
-    const tools = parseTools(value.tools);
+    const { tools, builtinTools } = parseTools(value.tools);
     const agentsMd = parseAgentsMd(value.agentsMd);
     const files = parseFiles(value.files);
     const mcpServers = parseMcpServers(value.mcpServers);
@@ -1255,7 +1255,7 @@ export function parseSubmission(input) {
     const securityProfile = parseRuntimeSecurityProfile(value.securityProfile);
     const metadata = optionalJsonRecord(value.metadata, "submission.metadata");
     const outputs = parseOutputs(value.outputs);
-    const builtins = parseBuiltins(value.builtins);
+    const includeBuiltinTools = parseIncludeBuiltinTools(value.includeBuiltinTools);
     const outputMode = parseOutputMode(value.outputMode);
     const platform = parsePlatformConfig(value.platform);
     return {
@@ -1272,7 +1272,8 @@ export function parseSubmission(input) {
         ...(securityProfile ? { securityProfile } : {}),
         ...(metadata ? { metadata } : {}),
         ...(outputs ? { outputs } : {}),
-        ...(builtins !== undefined ? { builtins } : {}),
+        ...(includeBuiltinTools !== undefined ? { includeBuiltinTools } : {}),
+        ...(builtinTools.length > 0 ? { builtinTools } : {}),
         ...(outputMode !== undefined ? { outputMode } : {}),
         ...(platform ? { platform } : {})
     };
@@ -1336,108 +1337,105 @@ function parseOutputMode(input) {
     return input;
 }
 /**
- * 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.
  *
- * The first entries are the recommended concrete builtins. The legacy aggregate
- * extension names remain accepted for existing callers, but are not the default.
+ * Order mirrors `HANDS_TOOLS`. A builtin tool reference (a bare string in
+ * `submission.tools`) must be a member of this set.
  */
-export const BUILTINS = [
-    "web_search",
-    "web_fetch",
-    "read",
-    "edit",
-    "glob",
-    "grep",
-    "head",
-    "tail",
+export const BUILTIN_TOOL_NAMES = [
     "bash",
-    "notebook",
-    "developer",
-    "computercontroller",
-    "memory",
-    "autovisualiser",
-    "tutorial"
-];
-/**
- * DX-first managed-runtime defaults. Omitted `builtins` resolves to this list.
- * Notebook support remains opt-in through {@link Builtins.NOTEBOOK}.
- */
-export const DEFAULT_BUILTINS = [
-    "web_search",
-    "web_fetch",
-    "read",
-    "edit",
-    "glob",
+    "read_file",
+    "write_file",
+    "edit_file",
     "grep",
+    "glob",
     "head",
     "tail",
-    "bash"
+    "todo_write",
+    "subagent",
+    "subagent_result",
+    "web_fetch",
+    "web_search",
+    "notebook_edit",
+    "bash_output",
+    "bash_kill",
+    "code_execution",
+    "wait",
+    "git"
 ];
 /**
- * Symbol-style accessors for the closed builtin set, e.g.
- * `Builtins.WEB_SEARCH`.
+ * 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.
+ *
+ * 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 const Builtins = {
-    /** Managed web search. Included in {@link DEFAULT_BUILTINS}. */
-    WEB_SEARCH: "web_search",
-    /** Fetch a URL and return readable text. Included in {@link DEFAULT_BUILTINS}. */
-    WEB_FETCH: "web_fetch",
-    /** Read files. Included in {@link DEFAULT_BUILTINS}. */
-    READ: "read",
-    /** Create/modify files. Included in {@link DEFAULT_BUILTINS}. */
-    EDIT: "edit",
-    /** Search paths by glob. Included in {@link DEFAULT_BUILTINS}. */
-    GLOB: "glob",
-    /** Search file contents. Included in {@link DEFAULT_BUILTINS}. */
-    GREP: "grep",
-    /** Read the first lines of a file. Included in {@link DEFAULT_BUILTINS}. */
-    HEAD: "head",
-    /** Read the last lines of a file. Included in {@link DEFAULT_BUILTINS}. */
-    TAIL: "tail",
-    /** Shell command execution. Included in {@link DEFAULT_BUILTINS}. */
-    BASH: "bash",
-    /** Jupyter notebook editing. Optional; not in {@link DEFAULT_BUILTINS}. */
-    NOTEBOOK: "notebook",
-    /** Legacy aggregate: shell/filesystem/navigation/web/notebook tools. */
-    DEVELOPER: "developer",
-    /** Legacy aggregate alias retained for existing callers. */
-    COMPUTER_CONTROLLER: "computercontroller",
-    /** Legacy aggregate alias retained for existing callers. */
-    MEMORY: "memory",
-    /** Legacy aggregate alias retained for existing callers. */
-    AUTOVISUALISER: "autovisualiser",
-    /** Legacy aggregate alias retained for existing callers. */
-    TUTORIAL: "tutorial"
+export const BuiltinTools = {
+    bash: "bash",
+    read_file: "read_file",
+    write_file: "write_file",
+    edit_file: "edit_file",
+    grep: "grep",
+    glob: "glob",
+    head: "head",
+    tail: "tail",
+    todo_write: "todo_write",
+    subagent: "subagent",
+    subagent_result: "subagent_result",
+    web_fetch: "web_fetch",
+    web_search: "web_search",
+    notebook_edit: "notebook_edit",
+    bash_output: "bash_output",
+    bash_kill: "bash_kill",
+    code_execution: "code_execution",
+    wait: "wait",
+    git: "git"
 };
-const MAX_BUILTINS = 16;
-function parseBuiltins(input) {
+/**
+ * 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 const DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES.filter((name) => name !== "notebook_edit");
+/**
+ * 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 function resolveBuiltinToolNames(includeBuiltinTools, toolRefs) {
+    const enabled = new Set(includeBuiltinTools !== false ? DEFAULT_BUILTIN_TOOLS : []);
+    for (const ref of toolRefs ?? []) {
+        if (!BUILTIN_TOOL_NAMES.includes(ref)) {
+            throw new Error(`${JSON.stringify(ref)} is not a builtin tool; expected one of: ${BUILTIN_TOOL_NAMES.join(", ")}`);
+        }
+        enabled.add(ref);
+    }
+    return BUILTIN_TOOL_NAMES.filter((name) => enabled.has(name));
+}
+/** Validate the optional `includeBuiltinTools` flag (default `true`). */
+function parseIncludeBuiltinTools(input) {
     if (input === undefined || input === null)
         return undefined;
-    if (!Array.isArray(input)) {
-        throw new Error("submission.builtins must be an array of strings");
-    }
-    if (input.length > MAX_BUILTINS) {
-        throw new Error(`submission.builtins exceeds the max of ${MAX_BUILTINS} entries`);
-    }
-    const seen = new Set();
-    const out = [];
-    for (let i = 0; i < input.length; i++) {
-        const v = input[i];
-        if (typeof v !== "string") {
-            throw new Error(`submission.builtins[${i}] must be a string`);
-        }
-        if (!BUILTINS.includes(v)) {
-            throw new Error(`submission.builtins[${i}] (${JSON.stringify(v)}) is not a managed-runtime builtin; ` +
-                `expected one of: ${BUILTINS.join(", ")}`);
-        }
-        if (seen.has(v))
-            continue; // dedupe silently
-        seen.add(v);
-        out.push(v);
+    if (typeof input !== "boolean") {
+        throw new Error("submission.includeBuiltinTools must be a boolean");
     }
-    return out;
+    return input;
 }
 /**
  * Maximum number of output capture entries accepted per list.
@@ -1665,17 +1663,35 @@ function parseSkills(input) {
         return ref;
     });
 }
+/**
+ * Parse the `submission.tools` union: each entry is either a BARE STRING (a
+ * builtin tool reference, validated against {@link BUILTIN_TOOL_NAMES}) or a
+ * custom tool bundle OBJECT ({@link ToolRef}). Returns the two groups split:
+ * `tools` (custom bundles, the existing downstream shape) and `builtinTools`
+ * (the deduped builtin-name references, in {@link BUILTIN_TOOL_NAMES} order).
+ */
 function parseTools(input) {
     if (input === undefined) {
-        return [];
+        return { tools: [], builtinTools: [] };
     }
     if (!Array.isArray(input)) {
-        throw new Error("submission.tools must be an array of ToolRef objects");
+        throw new Error("submission.tools must be an array of builtin tool names or ToolRef objects");
     }
     const seenNames = new Set();
     const seenAssetIds = new Set();
-    return input.map((item, index) => {
+    const seenBuiltins = new Set();
+    const tools = [];
+    input.forEach((item, index) => {
         const path = `submission.tools[${index}]`;
+        // A bare string is a builtin tool reference (e.g. BuiltinTools.notebook_edit).
+        if (typeof item === "string") {
+            if (!BUILTIN_TOOL_NAMES.includes(item)) {
+                throw new Error(`${path} (${JSON.stringify(item)}) is not a builtin tool name; ` +
+                    `expected one of: ${BUILTIN_TOOL_NAMES.join(", ")}`);
+            }
+            seenBuiltins.add(item);
+            return;
+        }
         const raw = requireRecord(item, path);
         for (const key of Object.keys(raw)) {
             if (key !== "kind" &&
@@ -1717,15 +1733,17 @@ function parseTools(input) {
             throw new Error(`${path}.input_schema.type must be "object"`);
         }
         const entry = normaliseSkillBundlePath(requireString(raw.entry, `${path}.entry`));
-        return {
+        tools.push({
             kind: "asset",
             assetId: fields.assetId,
             name: fields.name,
             description,
             input_schema: inputSchema,
             entry
-        };
+        });
     });
+    const builtinTools = BUILTIN_TOOL_NAMES.filter((name) => seenBuiltins.has(name));
+    return { tools, builtinTools };
 }
 function parseAgentsMd(input) {
     if (input === undefined)

package/dist/cli.mjs

@@ -798,6 +798,28 @@ function parseRunRegion(input) {
   }
   return input;
 }
+var BUILTIN_TOOL_NAMES = [
+  "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"
+];
+var DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES.filter((name) => name !== "notebook_edit");
 var MAX_OUTPUT_CAPTURE_TIMEOUT_MS = 6 * 60 * 60 * 1e3;
 
 // ../contracts/dist/connection-ticket.js
@@ -1376,6 +1398,8 @@ function extractErrorMessage(body) {
 // ../contracts/dist/operations.js
 var operations_exports = {};
 __export(operations_exports, {
+  READ_OUTPUT_TEXT_DEFAULT_BYTES: () => READ_OUTPUT_TEXT_DEFAULT_BYTES,
+  READ_OUTPUT_TEXT_MAX_BYTES: () => READ_OUTPUT_TEXT_MAX_BYTES,
   cancelRun: () => cancelRun,
   classifyOutput: () => classifyOutput,
   createAgentsMd: () => createAgentsMd,
@@ -1414,10 +1438,12 @@ __export(operations_exports, {
   listFiles: () => listFiles,
   listOutputs: () => listOutputs,
   listRunEvents: () => listRunEvents,
+  listRuns: () => listRuns,
   listSecrets: () => listSecrets,
   listSkills: () => listSkills,
   normalizeOutputLinkExpiresIn: () => normalizeOutputLinkExpiresIn,
   outputLink: () => outputLink,
+  readOutputText: () => readOutputText,
   redeliverRunWebhook: () => redeliverRunWebhook,
   resolveOutputFileSelector: () => resolveOutputFileSelector,
   rotateSecret: () => rotateSecret,
@@ -2151,6 +2177,18 @@ async function getRun(http, runId) {
 async function getRunUnit(http, runId) {
   return http.request(`/api/runs/${encodeURIComponent(runId)}`);
 }
+async function listRuns(http, query) {
+  const params = {};
+  if (query?.status !== void 0)
+    params.status = query.status;
+  if (query?.since !== void 0)
+    params.since = query.since;
+  if (query?.limit !== void 0)
+    params.limit = String(query.limit);
+  if (query?.cursor !== void 0)
+    params.cursor = query.cursor;
+  return http.request("/api/runs", {}, params);
+}
 var LIST_EVENTS_PAGE_BUDGET = 1e3;
 async function listRunEvents(http, runId) {
   const path = `/api/runs/${encodeURIComponent(runId)}/events`;
@@ -2249,6 +2287,74 @@ 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()) };
 }
+var READ_OUTPUT_TEXT_MAX_BYTES = 1e7;
+var READ_OUTPUT_TEXT_DEFAULT_BYTES = 5e4;
+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 === void 0 ? capped.text : grepLines(capped.text, options.grep);
+  return { output, text, truncated: capped.truncated, totalBytes: capped.totalBytes };
+}
+async function readCappedText(response, maxBytes) {
+  const declaredRaw = response.headers.get("content-length");
+  const declared = declaredRaw !== null && /^\d+$/.test(declaredRaw) ? Number(declaredRaw) : void 0;
+  const decoder = new TextDecoder("utf-8");
+  const body = response.body;
+  if (!body) {
+    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) {
+      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 !== void 0 ? 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");
+}
 async function cancelRun(http, runId) {
   await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
 }

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-41301b02d51ef616bfff7b0d282d58e6ccc0ac5792c693f094bcae3c05c105db  cli.mjs
+0386d2625bfa4f8aea426cffc3bf21546c48b33b7134eb7cd4bbfefdc2d69d96  cli.mjs

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputMode, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunWebhookDelivery, type RunProvider, type RunRegion, type SecretRecord, type SecretReveal, type RunUnit, type Builtin, type RuntimeSize, type RuntimeKind, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
+import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type CredentialMode, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type RunListPage, type RunListQuery, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunWebhookDelivery, type RunProvider, type RunRegion, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type RuntimeKind, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { type UploadedAsset } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -91,7 +91,18 @@ export interface SubmitOptions {
     readonly system?: string;
     readonly prompt: string | readonly string[];
     readonly skills?: readonly Skill[];
-    readonly tools?: readonly Tool[];
+    /**
+     * Tools available to the agent. Each entry is either a custom {@link Tool}
+     * bundle, or a BUILTIN tool reference — a bare name string, preferably
+     * `BuiltinTools.<name>` (e.g. `BuiltinTools.notebook_edit`) so a typo is a
+     * compile error. Builtin references compose with {@link includeBuiltinTools}:
+     * use them to cherry-pick a tool the default set omits (notebook editing), or
+     * to pick a narrow subset alongside `includeBuiltinTools: false`.
+     *
+     * Order in the agent's tool list: resolved builtin tools, then custom tools,
+     * then MCP tools.
+     */
+    readonly tools?: readonly (Tool | BuiltinToolName)[];
     readonly agentsMd?: readonly AgentsMd[];
     readonly files?: readonly File[];
     readonly mcpServers?: readonly McpServer[];
@@ -146,22 +157,14 @@ export interface SubmitOptions {
         readonly maxFiles?: number;
     };
     /**
-     * Override the managed runtime builtins enabled inside the runner.
-     * Each entry is one of the closed {@link Builtin} set — prefer the
-     * {@link Builtins} symbol const so a typo is a compile error.
+     * Whether to inject the standard builtin tool set
+     * ({@link DEFAULT_BUILTIN_TOOLS} — every builtin except `notebook_edit`).
      *
-     * - Omitted (default): the runner enables `DEFAULT_BUILTINS`
-     *   (`web_search`, `web_fetch`, `read`, `edit`, `glob`, `grep`, `head`,
-     *   `tail`).
-     * - Empty array: the agent runs with zero builtins — useful for pure-MCP
-     *   setups where every tool comes from a submitted `mcpServers` entry.
-     * - Custom list: narrows or extends the surface, e.g.
-     *   `[Builtins.WEB_SEARCH, Builtins.NOTEBOOK]`.
-     *
-     * Validation: each entry must be a member of {@link Builtins}, max 16
-     * entries, deduplicated server-side.
+     * - Omitted / `true` (default): inject the standard builtins.
+     * - `false`: inject NO builtins — useful for a pure-MCP / pure-custom run.
+     *   Cherry-pick a narrow subset back by listing builtin names in `tools`.
      */
-    readonly builtins?: readonly Builtin[];
+    readonly includeBuiltinTools?: boolean;
     /**
      * Assistant-output granularity. `"buffered"` (default) delivers one event per
      * assistant message; `"stream"` delivers per-token text deltas for live
@@ -480,6 +483,17 @@ export declare class AgentExecutor {
     getRun(runId: string): Promise<Run>;
     /** Short alias for `getRun`. */
     get(runId: string): Promise<Run>;
+    /**
+     * List the runs in this workspace, most-recent first, one page at a time.
+     * The workspace is derived server-side from the API token, so this only ever
+     * enumerates your own runs. Pass `query.cursor` (from a prior page's
+     * `nextCursor`) to page; omit it for the first page. Returns public-safe
+     * {@link RunSummary} rows — the full submission stays behind `getRunUnit`.
+     *
+     * This is the workspace-wide discovery entry point: combine it with
+     * `listOutputs` / `readOutputText` to reach any run's deliverables.
+     */
+    listRuns(query?: RunListQuery): Promise<RunListPage>;
     /**
      * Fetch the self-contained `RunUnit`: parsed submission inputs,
      * attempts, indexed events (inline + cursor for the tail), raw
@@ -530,6 +544,15 @@ export declare class AgentExecutor {
     outputLink(runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
     createOutputLink(runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<OutputLink>;
     fetchOutput(runId: string, selectorOrQuery: OutputLinkSelector, options?: OutputLinkOptions): Promise<Response>;
+    /**
+     * Read ONE output file as byte-capped, decoded UTF-8 text. Streams the file and
+     * STOPS at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a huge
+     * deliverable never fully buffers — ideal for handing a run's output to an LLM
+     * tool. Check `result.truncated` before treating the text as complete; pass
+     * `options.grep` to keep only matching lines. Select by `{ path }` or `{ id }`,
+     * same as `downloadOutput`.
+     */
+    readOutputText(runId: string, selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
     eventArchiveLink(runId: string, options?: OutputLinkOptions): Promise<OutputLink>;
     /**
      * Download captured deliverables. Omit `selector` to receive the full

package/dist/client.js

@@ -1,4 +1,4 @@
-import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, RUN_REGIONS, RUNTIME_KINDS, RunStateError, SecretString, isRunSettled, operations, parseCredentialMode, providersForModel, streamCoordinatorEvents, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexError, DEFAULT_CREDENTIAL_MODE, DEFAULT_RUN_PROVIDER, HttpClient, RUN_REGIONS, RUNTIME_KINDS, RunStateError, SecretString, isRunSettled, operations, parseCredentialMode, providersForModel, streamCoordinatorEvents, BUILTIN_TOOL_NAMES, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { uploadAsset } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -380,7 +380,12 @@ export class AgentExecutor {
             ...(options.system ? { system: options.system } : {}),
             prompt,
             skills: preparedSkills,
-            tools: preparedTools,
+            // The wire `tools` is the union: builtin name strings (cherry-picks)
+            // followed by the custom tool bundle refs. The shared parser splits them
+            // back into `tools` (custom) + `builtinTools` (names). The cast
+            // acknowledges the SDK is producing pre-parse wire input here, same as
+            // `mcpServers` / `environment` below.
+            tools: [...preparedTools.builtinNames, ...preparedTools.refs],
             agentsMd: preparedAgentsMd,
             files: preparedFiles,
             // submissionMcpServers may contain workspace refs of the shape
@@ -401,10 +406,10 @@ export class AgentExecutor {
                 : {}),
             ...(options.metadata ? { metadata: options.metadata } : {}),
             ...(outputCapture ? { outputs: outputCapture } : {}),
-            // Pass-through `builtins` verbatim — including an empty array,
-            // which is the "disable all builtins" signal. Distinguish from
-            // omitted (default applies) via `!== undefined`.
-            ...(options.builtins !== undefined ? { builtins: options.builtins } : {}),
+            // Pass-through the builtin-tool toggle verbatim (omitted ⇒ default ON).
+            ...(options.includeBuiltinTools !== undefined
+                ? { includeBuiltinTools: options.includeBuiltinTools }
+                : {}),
             ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {})
         };
         const secrets = {
@@ -451,6 +456,19 @@ export class AgentExecutor {
     get(runId) {
         return this.getRun(runId);
     }
+    /**
+     * List the runs in this workspace, most-recent first, one page at a time.
+     * The workspace is derived server-side from the API token, so this only ever
+     * enumerates your own runs. Pass `query.cursor` (from a prior page's
+     * `nextCursor`) to page; omit it for the first page. Returns public-safe
+     * {@link RunSummary} rows — the full submission stays behind `getRunUnit`.
+     *
+     * This is the workspace-wide discovery entry point: combine it with
+     * `listOutputs` / `readOutputText` to reach any run's deliverables.
+     */
+    listRuns(query) {
+        return operations.listRuns(this.#http, query);
+    }
     /**
      * Fetch the self-contained `RunUnit`: parsed submission inputs,
      * attempts, indexed events (inline + cursor for the tail), raw
@@ -581,6 +599,17 @@ export class AgentExecutor {
         const link = await this.outputLink(runId, selectorOrQuery, options);
         return (this.#fetch ?? fetch)(link.url);
     }
+    /**
+     * Read ONE output file as byte-capped, decoded UTF-8 text. Streams the file and
+     * STOPS at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a huge
+     * deliverable never fully buffers — ideal for handing a run's output to an LLM
+     * tool. Check `result.truncated` before treating the text as complete; pass
+     * `options.grep` to keep only matching lines. Select by `{ path }` or `{ id }`,
+     * same as `downloadOutput`.
+     */
+    readOutputText(runId, selector, options) {
+        return operations.readOutputText(this.#http, runId, selector, options);
+    }
     eventArchiveLink(runId, options) {
         return operations.eventArchiveLink(this.#http, runId, options);
     }
@@ -826,12 +855,33 @@ async function prepareSkills(skills, uploader) {
     }
     return refs;
 }
+/**
+ * Split the `tools` union into custom tool refs (drafts eagerly uploaded as
+ * assets) and builtin tool-name references (bare strings, validated against the
+ * closed {@link BUILTIN_TOOL_NAMES} set). Builtin names are deduped, in input
+ * order; the two groups are recombined on the wire (builtins first) by the
+ * caller.
+ */
 async function prepareTools(tools, uploader) {
     const refs = [];
+    const seenBuiltins = new Set();
+    const builtinNames = [];
     for (let i = 0; i < tools.length; i++) {
         const entry = tools[i];
+        // A bare string is a builtin tool reference.
+        if (typeof entry === "string") {
+            if (!BUILTIN_TOOL_NAMES.includes(entry)) {
+                throw new Error(`AgentExecutor.submit: tools[${i}] (${JSON.stringify(entry)}) is not a builtin tool name; ` +
+                    `expected a Tool instance or one of: ${BUILTIN_TOOL_NAMES.join(", ")}`);
+            }
+            if (!seenBuiltins.has(entry)) {
+                seenBuiltins.add(entry);
+                builtinNames.push(entry);
+            }
+            continue;
+        }
         if (!(entry instanceof Tool)) {
-            throw new Error(`AgentExecutor.submit: tools[${i}] must be a Tool instance`);
+            throw new Error(`AgentExecutor.submit: tools[${i}] must be a Tool instance or a builtin tool name`);
         }
         if (entry.isConsumed) {
             throw new Error(`AgentExecutor.submit: tools[${i}] was already consumed by a prior submit`);
@@ -852,7 +902,7 @@ async function prepareTools(tools, uploader) {
         }
         refs.push(ref);
     }
-    return refs;
+    return { refs, builtinNames };
 }
 /** Walk AgentsMd[], eagerly upload drafts as assets, and return plain asset refs. */
 async function prepareAgentsMd(agentsMds, uploader) {