@aexhq/sdk 0.26.5 → 0.28.0

package/docs/concepts/agent-tools.md

@@ -1,40 +1,55 @@
 ---
 title: Agent tools
-description: The default machine tools available inside managed runs.
+description: The default builtin tools available inside managed runs.
 icon: TerminalSquare
 ---
 
-Managed runs expose a DX-first default builtin set to the agent. Omit
-`builtins` for the recommended defaults:
-
-- `web_search`
-- `web_fetch`
-- `read`
-- `edit`
-- `glob`
-- `grep`
-- `head`
-- `tail`
-- `bash`
-
-Pass `builtins: []` for a pure-MCP run with no builtins. Pass a custom list to
-narrow or extend the surface, for example adding the optional `notebook`
-builtin. MCP-derived tools and subagent tools are separate surfaces.
-
-## Default filesystem and web tools
-
-- `read` and `edit` expose file read/create/patch tools.
-- `grep` and `glob` search file contents and paths.
-- `head` and `tail` read bounded file slices.
-- `bash` runs shell commands in the run sandbox.
-- `web_fetch` fetches a URL and returns readable text.
-- `web_search` performs managed web search without requiring a caller-supplied
-  search key.
+Managed runs inject a DX-first set of builtin tools to the agent by default. The
+default set is every builtin tool EXCEPT `notebook_edit` (notebook editing is
+opt-in). It includes:
+
+- `bash`, `code_execution` — run shell commands / model-written snippets
+- `read_file`, `write_file`, `edit_file` — file read/create/patch
+- `grep`, `glob` — search file contents and paths
+- `head`, `tail` — read bounded file slices
+- `web_fetch`, `web_search` — fetch a URL / managed web search
+- `todo_write` — maintain a todo list
+- `subagent`, `subagent_result` — delegate to and read back from child runs
+- `bash_output`, `bash_kill` — manage background bash jobs
+- `wait`, `git` — bounded idle-yield and first-class git
+
+## Toggling builtins
+
+Set `includeBuiltinTools: false` to inject NO builtins — useful for a pure-MCP
+or pure-custom run where every tool comes from `mcpServers` or `tools`.
+
+`includeBuiltinTools` defaults to `true`.
+
+## Cherry-picking builtins
+
+The `tools` list accepts both custom tool bundles and BUILTIN tool references
+(bare name strings, preferably `BuiltinTools.<name>`). Use a builtin reference
+to add a tool the default set omits (notebook editing), or to pick a narrow
+subset alongside `includeBuiltinTools: false`.
+
+The final tool list is ordered: resolved builtin tools, then custom tools, then
+MCP tools.
 
 ## Optional notebook support
 
-`notebook` edits Jupyter `.ipynb` cells as JSON. It is accepted by the
-contract, but it is not in the default builtin list.
+`notebook_edit` edits Jupyter `.ipynb` cells as JSON. It is NOT in the default
+builtin set; add it via `tools`:
+
+```ts
+import { BuiltinTools, Models } from "@aexhq/sdk";
+
+await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Edit the analysis notebook.",
+  tools: [BuiltinTools.notebook_edit],
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
 
 Networking is open by default. If you explicitly set
 `environment.networking.mode` to `limited`, fetched hosts and the managed search
@@ -49,7 +64,7 @@ await aex.submit({
   model: Models.CLAUDE_HAIKU_4_5,
   prompt: "Use only the declared MCP tools.",
   mcpServers,
-  builtins: [],
+  includeBuiltinTools: false,
   secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
 });
 ```

package/docs/outputs.md

@@ -77,6 +77,28 @@ const looseReport = await aex.downloadOutput(runId, { path: "report.txt", match:
 console.log(looseReport.byteLength);
 ```
 
+## Reading one output as text
+
+`readOutputText(runId, selector, options?)` reads ONE output file as byte-capped, decoded UTF-8 text. It streams the file and stops at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a large deliverable never fully buffers — this is the read built for handing a run's output to an LLM tool. Select the file the same way as `downloadOutput`: by `{ path }` (suffix-matchable) or `{ id }`.
+
+```ts
+const { text, truncated, totalBytes } = await aex.readOutputText(
+  runId,
+  { path: "report.md", match: "suffix" },
+  { maxBytes: 50_000, grep: "error" }
+);
+
+if (truncated) {
+  // text is a prefix of a larger file — narrow with `grep` or a tighter `path`.
+}
+```
+
+Check `truncated` before treating `text` as complete. Pass `options.grep` (a substring or `RegExp`) to keep only matching lines of the capped text. The returned `output` is the matched `Output` record, and `totalBytes` is the file's full size when the server reports it.
+
+### Chatting over a workspace's outputs
+
+`createDataTools(client)` packages the read surface (`listRuns` + `listOutputs` + `readOutputText`) as a vendor-neutral LLM tool set (`{ tools, instructions, execute }`) so you can build a search-then-fetch chat over your runs and their outputs in a few lines on top of the public SDK. The `tools` are plain JSON-Schema definitions (the shape every major LLM tool API accepts); `execute(name, input)` dispatches a tool call against the workspace-scoped client. See the runnable `examples/data-chat/` example.
+
 ## Finding outputs
 
 `listOutputs(runId, query?)` and its alias `outputs(runId, query?)` can filter the captured output list client-side. Use `findOutputs` when you want discovery to be explicit, or `findOutput` when exactly one file is expected:

package/docs/run-config.md

@@ -21,7 +21,7 @@ Allowed fields:
 - `proxyEndpoints` - array of `PlatformProxyEndpoint`; endpoint-level `retry` is allowed here and remains declaration-based.
 - `metadata` - non-secret structured metadata.
 
-`agentsMd`, `files`, `outputs`, `builtins`, and `outputMode` are top-level `submit` options, not run-config fields. They carry bytes, capture behavior, or agent tool/output controls that belong on a concrete run submission.
+`agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, and `outputMode` are top-level `submit` options, not run-config fields. They carry bytes, capture behavior, or agent tool/output controls that belong on a concrete run submission.
 
 Secrets never live in run config. Pass credentials through `submit({ ...config, secrets })` in the SDK or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`, `--proxy-auth`) in the CLI. See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md) for the proxy endpoint policy/auth split and retry fields.
 

package/docs/run-record.md

@@ -6,6 +6,25 @@ title: Run record
 
 The run record is the durable product primitive for one run id. It is the public-safe bundle of status metadata, the non-secret submission snapshot when available, typed events, captured outputs, and manifest entries for custody and cost telemetry.
 
+## Listing runs
+
+`aex.listRuns(query?)` enumerates 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 returns your own runs. It is the workspace-wide discovery entry point: combine it with `listOutputs` / `readOutputText` (see [Outputs](outputs.md)) to reach any run's deliverables.
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await aex.listRuns({ status: "succeeded", limit: 25, cursor });
+  for (const run of page.runs) {
+    console.log(run.id, run.status, run.createdAt, run.costUsd);
+  }
+  cursor = page.nextCursor;
+} while (cursor);
+```
+
+`query` fields are all optional: `status` (single run status, e.g. `"succeeded"`), `since` (ISO-8601 lower bound on `createdAt`), `limit` (defaults to 25, clamped to `[1, 100]`), and `cursor` (the opaque keyset cursor from a prior page's `nextCursor` — absent on the last page). Each page row is a public-safe `RunSummary` (`id`, `status`, `createdAt`, `updatedAt`, and `costUsd` once settled); it deliberately omits the submission snapshot (model / prompt / env). Use `aex.getRun(runId)` for status / timing / cost on one run, or `aex.getRunUnit(runId)` (alias `getUnit`) for the full self-contained record including the parsed submission.
+
+## Downloading a run record
+
 `aex.download(runId)` and `aex download <run-id>` return a zip with this layout:
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.26.5",
+  "version": "0.28.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {