@aexhq/sdk 0.26.4 → 0.27.0

package/dist/index.js

@@ -17,6 +17,10 @@ export { McpServer } from "./mcp-server.js";
 export { ProxyEndpoint } from "./proxy-endpoint.js";
 export { Secret } from "./secret.js";
 export { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
+// Data-source chat tools — turn the read surface (listRuns / listOutputs /
+// readOutputText) into vendor-neutral LLM tool definitions + an executor, so a
+// chat over workspace/run data is a few lines on top of the public SDK.
+export { createDataTools, DataToolError, DATA_TOOLS_INSTRUCTIONS } from "./data-tools.js";
 // Errors
 export { AexApiError, AexError, CleanupError, CredentialValidationError, ProviderError, RunStateError } from "./_contracts/index.js";
 // Skill / MCP wire types
@@ -25,11 +29,11 @@ export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SkillBundleValidationErro
 // Prefer the `RuntimeSizes` symbol const (e.g. `RuntimeSizes.SHARED_2X_2GB`)
 // so an invalid token is a compile error, not a runtime 400.
 export { CUSTODY_MANIFEST_SCHEMA_VERSION, RUN_RECORD_MANIFEST_SCHEMA_VERSION, RUN_RECORD_SCHEMA_VERSION, DEFAULT_RUNTIME_SIZE, RUNTIME_SIZE_PRESETS, RUNTIME_SIZES, RuntimeSizes } from "./_contracts/index.js";
-// Managed-runtime builtins — the default and closed builtin sets.
-// Prefer the `Builtins` symbol const (e.g.
-// `Builtins.WEB_SEARCH`) so an invalid token is a compile
-// error, not a runtime 400.
-export { DEFAULT_BUILTINS, BUILTINS, Builtins } from "./_contracts/index.js";
+// Builtin tools — the closed + default builtin tool sets. Toggle the standard
+// set with `includeBuiltinTools` on submit; cherry-pick individual tools by
+// listing their names in `tools`. Prefer the `BuiltinTools` const (e.g.
+// `BuiltinTools.notebook_edit`) so a typo is a compile error, not a runtime 400.
+export { BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, resolveBuiltinToolNames } from "./_contracts/index.js";
 // Provider + runtime dispatch surface. Agents and SDK consumers
 // inspect these to know which (provider, runtime) combos are valid
 // and to validate submissions offline before posting.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AActG,yBAAyB;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,SAAS;AACT,OAAO,EACL,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B,yBAAyB;AACzB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAqE1B,oEAAoE;AACpE,6EAA6E;AAC7E,6DAA6D;AAC7D,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,EAClC,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,YAAY,EACb,MAAM,kBAAkB,CAAC;AAG1B,kEAAkE;AAClE,2CAA2C;AAC3C,0DAA0D;AAC1D,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGxE,gEAAgE;AAChE,mEAAmE;AACnE,sDAAsD;AACtD,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,iCAAiC,EACjC,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,aAAa,EACb,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAU1B,sCAAsC;AACtC,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B,gFAAgF;AAChF,6EAA6E;AAC7E,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAQ1B,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/D,yEAAyE;AACzE,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AActG,yBAAyB;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,2EAA2E;AAC3E,+EAA+E;AAC/E,wEAAwE;AACxE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG1F,SAAS;AACT,OAAO,EACL,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B,yBAAyB;AACzB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AA0E1B,oEAAoE;AACpE,6EAA6E;AAC7E,6DAA6D;AAC7D,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,EAClC,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,YAAY,EACb,MAAM,kBAAkB,CAAC;AAG1B,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,iFAAiF;AACjF,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAGpH,gEAAgE;AAChE,mEAAmE;AACnE,sDAAsD;AACtD,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,iCAAiC,EACjC,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,aAAa,EACb,SAAS,EACT,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAU1B,sCAAsC;AACtC,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAE1B,gFAAgF;AAChF,6EAA6E;AAC7E,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAQ1B,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/D,yEAAyE;AACzE,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.26.4";
+export declare const SDK_VERSION = "0.27.0";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.26.4";
+export const SDK_VERSION = "0.27.0";
 //# sourceMappingURL=version.js.map

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/credentials.md

@@ -10,13 +10,31 @@ credentials. Reusable env secrets are documented separately in
 
 The caller passes a workspace-scoped SDK token and the provider key inline on every `submit` call. aex holds the bundle in run-scoped custody for the run lifecycle and attempts terminal cleanup/revocation for the aex-controlled references. MCP credentials and proxy endpoint auth values travel the same way.
 
-A run targets exactly one provider (selected by `provider`, default `anthropic`), so the key is a single flat field:
+A run selects one upstream `provider` (default `anthropic`) and must carry a BYOK
+key for it. Keys are supplied per-provider so a run can also hold keys for the
+**other** providers its subagents may use:
 
 | Field | Required secret |
 | --- | --- |
-| Provider API key | `secrets.apiKey` |
+| Provider API keys | `secrets.apiKeys` (keyed by provider) |
 
-The same `secrets.apiKey` carries the BYOK key for whichever `provider` the run selects.
+```ts
+// The run's own provider key, plus extra keys its subagents can use.
+secrets: {
+  apiKeys: {
+    anthropic: process.env.ANTHROPIC_API_KEY!, // the run's provider
+    deepseek: process.env.DEEPSEEK_API_KEY!     // for a cross-provider subagent
+  }
+}
+```
+
+A `subagent` spawned with a different-family model **inherits the parent's keys
+server-side** from the run's vaulted bundle — the keys never transit the
+container. If the parent holds no key for the child's provider, the child submit
+is rejected with `parent_missing_provider_key`.
+
+The flat `secrets.apiKey` is still accepted as a back-compat shorthand for the
+run's own provider key (equivalent to `apiKeys[provider]`).
 
 MCP credential types:
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,15 +26,19 @@
     "examples"
   ],
   "scripts": {
-    "build": "bun ./scripts/clean-dist.mjs && bun run --cwd ../.. --filter @aexhq/contracts build && bun run --cwd ../.. --filter @aexhq/cli build && tsc -p tsconfig.build.json && bun ./scripts/bundle-cli.mjs && bun ./scripts/inline-contracts.mjs",
-    "lint": "tsc --noEmit",
+    "build": "bun ../../scripts/with-generated-dist-lock.mjs bun run build:unlocked",
+    "build:unlocked": "bun ./scripts/clean-dist.mjs && bun run --cwd ../.. --filter @aexhq/contracts build && bun run --cwd ../.. --filter @aexhq/cli build && tsc -p tsconfig.build.json && bun ./scripts/bundle-cli.mjs && bun ./scripts/inline-contracts.mjs",
+    "lint": "bun ../../scripts/with-generated-dist-lock.mjs bun run lint:unlocked",
+    "lint:unlocked": "tsc --noEmit",
     "test": "bun run test:unit",
-    "test:unit": "vitest run test/unit",
-    "test:security": "vitest run test/security",
+    "test:unit": "bun ../../scripts/with-generated-dist-lock.mjs bun run test:unit:unlocked",
+    "test:unit:unlocked": "vitest run test/unit",
+    "test:security": "bun ../../scripts/with-generated-dist-lock.mjs bun run test:security:unlocked",
+    "test:security:unlocked": "vitest run test/security",
     "test:property": "vitest run --passWithNoTests property",
     "test:coverage": "vitest run --coverage test/unit",
     "prepack": "bun run build",
-    "pack:dry-run": "bun pm pack --dry-run --ignore-scripts"
+    "pack:dry-run": "bun ../../scripts/with-generated-dist-lock.mjs bun pm pack --dry-run --ignore-scripts"
   },
   "devDependencies": {
     "@aexhq/contracts": "0.26.0"