@aexhq/sdk 0.29.0 → 0.30.0

package/dist/skill.js

@@ -25,7 +25,8 @@ import { readDirectoryAsFiles } from "./node-fs.js";
 export class Skill {
     #ref;
     #inlineBytes;
-    #consumed = false;
+    /** Asset id cached after the first submit, so reuse skips a re-upload. */
+    #assetId;
     /**
      * Internal constructor. Use `Skill.fromFiles` or `Skill.fromPath` to create
      * instances.
@@ -45,10 +46,15 @@ export class Skill {
     }
     /** True for local-bytes Skills that haven't been uploaded yet. */
     get isDraft() {
-        return this.#ref.kind === "draft" && !this.#consumed;
+        return this.#ref.kind === "draft";
     }
-    get isConsumed() {
-        return this.#consumed;
+    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    get _cachedAssetId() {
+        return this.#assetId;
+    }
+    /** Internal: remember the asset id resolved for this draft's bytes. */
+    _rememberAsset(assetId) {
+        this.#assetId = assetId;
     }
     /**
      * Build a draft Skill from an inline files map. The SDK validates
@@ -141,23 +147,17 @@ export class Skill {
         return new Skill(ref);
     }
     /**
-     * Internal: yield the draft's bytes + metadata so `client.submit`
-     * can upload the asset. After this returns, the Skill is marked consumed
-     * so a second submit call against the same instance throws
-     * (avoid silently re-uploading; explicit re-construction is the
-     * supported retry pattern).
+     * Internal: yield the draft's bytes + metadata so `client.submit` can upload
+     * the asset. Idempotent (non-consuming): a Skill is reusable across submits —
+     * the first submit caches the resolved asset id (see `_rememberAsset`) so
+     * later submits reuse it instead of re-uploading.
      *
      * Returns undefined for already-materialized Skills.
      */
     _takeDraftBundle() {
-        if (this.#consumed) {
-            throw new Error("Skill: cannot reuse a consumed Skill in submit. Build a fresh Skill via " +
-                "Skill.fromPath(...) / Skill.fromFiles(...) per submit call.");
-        }
         if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
             return undefined;
         }
-        this.#consumed = true;
         return {
             name: this.#ref.name,
             contentHash: this.#ref.contentHash,

package/dist/skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}

package/dist/tool.d.ts

@@ -12,7 +12,10 @@ export declare class Tool {
     private constructor();
     get ref(): ToolRef | DraftToolRef;
     get isDraft(): boolean;
-    get isConsumed(): boolean;
+    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    get _cachedAssetId(): string | undefined;
+    /** Internal: remember the asset id resolved for this draft's bytes. */
+    _rememberAsset(assetId: string): void;
     static fromFiles(args: ToolManifestInput & {
         readonly files: SkillFiles;
     }): Promise<Tool>;

package/dist/tool.js

@@ -4,7 +4,8 @@ import { readDirectoryAsFiles } from "./node-fs.js";
 export class Tool {
     #ref;
     #inlineBytes;
-    #consumed = false;
+    /** Asset id cached after the first submit, so reuse skips a re-upload. */
+    #assetId;
     constructor(ref, inlineBytes) {
         this.#ref = ref;
         this.#inlineBytes = inlineBytes;
@@ -13,10 +14,15 @@ export class Tool {
         return this.#ref;
     }
     get isDraft() {
-        return this.#ref.kind === "draft" && !this.#consumed;
+        return this.#ref.kind === "draft";
     }
-    get isConsumed() {
-        return this.#consumed;
+    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    get _cachedAssetId() {
+        return this.#assetId;
+    }
+    /** Internal: remember the asset id resolved for this draft's bytes. */
+    _rememberAsset(assetId) {
+        this.#assetId = assetId;
     }
     static async fromFiles(args) {
         if (!args || typeof args !== "object") {
@@ -60,13 +66,9 @@ export class Tool {
         return new Tool(normalizeToolRef("Tool.fromAsset", ref));
     }
     _takeDraftBundle() {
-        if (this.#consumed) {
-            throw new Error("Tool: cannot reuse a consumed Tool in submit. Build a fresh Tool via Tool.fromPath(...) / Tool.fromFiles(...) per submit call.");
-        }
         if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
             return undefined;
         }
-        this.#consumed = true;
         const { kind: _kind, contentHash, ...ref } = this.#ref;
         return {
             ref: { kind: "asset", ...ref },

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

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.29.0";
+export declare const SDK_VERSION = "0.30.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.29.0";
+export const SDK_VERSION = "0.30.0";
 //# sourceMappingURL=version.js.map

package/docs/concepts/agent-tools.md

@@ -51,9 +51,13 @@ await aex.submit({
 });
 ```
 
-Networking is open by default. If you explicitly set
-`environment.networking.mode` to `limited`, fetched hosts and the managed search
-host must be allowed by the run's networking configuration.
+Networking is open by default: the agent may reach any public host, subject to a
+fixed SSRF deny-list. `web_fetch` and `web_search` reach the network over a
+managed, SSRF-guarded path that is **not** governed by `environment.networking`,
+so their hosts never need to be listed in a `limited` allowlist. Setting
+`environment.networking.mode` to `limited` restricts only the agent's own
+arbitrary egress (e.g. a `curl` in `bash`); the built-in web tools keep working.
+See [Networking](../networking.md).
 
 ## Disable builtins
 

package/docs/events.md

@@ -36,11 +36,23 @@ for await (const event of aex.streamEnvelopes(runId, { from: 0 })) {
 The CLI mirrors the same surface:
 
 ```bash
-aex events <run-id> --api-token … [--aex-url …]                      # snapshot
-aex events <run-id> --follow [--timeout 8m] --api-token … [--aex-url …]  # stream until terminal
-aex wait   <run-id> [--timeout 8m] [--interval 2s] --api-token …          # block, print final run
+aex events  <run-id> --api-token … [--aex-url …]                      # snapshot (polling)
+aex events  <run-id> --follow [--timeout 8m] --api-token … [--aex-url …]  # stream until terminal (polling)
+aex tail    <run-id> [--json] [--filter <type|source>] [--logs] [--settle] [--timeout 8m] --api-token …  # live, human-readable, over the WS envelope stream
+aex inspect <run-id> [--json] [--filter <type|source>] [--logs] [--timeout 8m] --api-token …             # one-shot full timeline + jump-to-failure + cost/usage
+aex wait    <run-id> [--timeout 8m] [--interval 2s] --api-token …          # block, print final run
 ```
 
+`aex tail` and `aex inspect` consume the same coordinator WebSocket envelope
+stream as `streamEnvelopes()` (replay-from-cursor + tail + exactly-once resume),
+so they are the low-latency equivalents of `events --follow`'s polling. `--json`
+is the raw-NDJSON escape hatch; `--filter` keeps only the named AG-UI types
+(`TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, …) or sources (`agent`/`runtime`/…);
+a `RUN_ERROR` is surfaced as a jump-to-failure line. `aex inspect` adds a header,
+a settle-consistent full timeline, and a cost/usage footer. Both exit `0`
+succeeded / `1` other terminal / `3` timeout. They need a global `WebSocket`
+(Bun or Node ≥ 22).
+
 `aex wait` is the host mirror of `aex.wait(runId)` / `aex.waitForRun(runId)`:
 it polls until the run reaches a terminal status and prints the final `Run`
 record. Exit `0` when the run `succeeded`, `1` for any other terminal status,
@@ -69,9 +81,11 @@ Two facts make this easy to work with:
   consistently, don't key off the terminal event — use one of:
 
 ```ts
-// Blocking: resolves only once the RECORD is terminal (polls getRun, not the event).
-const run = await aex.run(runConfig);      // submit + wait
-const same = await aex.waitForRun(runId);  // or wait on an already-submitted run
+// Blocking: submit + wait + collect. Resolves once the RECORD is terminal
+// (polls getRun, not the event) and returns a settle-consistent RunResult
+// (status, ok, text, events, trace, outputs, costUsd).
+const result = await aex.run(runConfig);
+const sameRun = await aex.waitForRun(runId); // or wait on an already-submitted run for the bare Run record
 ```
 
 ```ts
@@ -112,7 +126,7 @@ terminal event is `RUN_ERROR` with `data.reason: "failed"` and
 
 ## Typed helpers
 
-The package exports conservative type guards that narrow normalized aex event envelopes:
+The package exports conservative type guards over run events:
 
 ```ts
 import {
@@ -126,8 +140,17 @@ import {
   isToolCallResult,
   isCustom,
   isLog,
-  isEventChannel
+  isEventChannel,
+  textOf
 } from "@aexhq/sdk";
 ```
 
-They narrow only the discriminant. Payload field shapes stay `unknown` until callers parse them, and provider-specific payloads remain behind the normalized envelope.
+All guards test the `type` discriminant at runtime. `isTextMessage`,
+`isToolCallStart`, `isToolCallResult`, and `isRunFinished` operate on the loose
+`RunEvent` snapshot (`listEvents` / `RunResult.events`) and additionally NARROW
+`event.data` to the fields that event type carries — e.g. inside
+`if (isTextMessage(e))`, `e.data.text` is typed `string`. The lifecycle/channel
+guards (`isRunStarted`, `isRunError`, `isCustom`, `isLog`, …) operate on the
+coordinator envelope and narrow only the discriminant. `textOf(events)` returns
+the run's final assistant text concatenated from the `TEXT_MESSAGE_CONTENT`
+blocks.

package/docs/networking.md

@@ -0,0 +1,141 @@
+---
+title: Networking
+---
+
+# Networking
+
+A run executes your agent's code in a sandbox that has **no unmediated route to
+the internet**. Every outbound connection — whether it comes from the model, a
+built-in tool, or a `curl` your code runs in the shell — passes through the
+platform's egress boundary, which enforces the run's networking policy and a
+fixed SSRF deny-list (loopback, link-local, cloud-metadata, and other private
+ranges are always blocked, including hostnames that resolve to those ranges).
+
+**Networking is open by default.** A run that does not set
+`environment.networking` may reach any public host — still subject to the SSRF
+deny-list above — with no allowlist required. You use the `environment.networking`
+field to *narrow* that surface when you want a tighter, auditable egress posture.
+Code cannot widen the policy from inside the container: the boundary is the
+platform's, not the agent's.
+
+## Paths that always work
+
+These reach the network over managed paths and are **not** subject to
+`environment.networking`, so you never list their hosts:
+
+- The model / provider call for the run (and its subagents).
+- The built-in `web_search` and `web_fetch` tools (still SSRF-guarded).
+- Any remote MCP servers you declare in `mcpServers` — see [MCP](mcp.md).
+- Any `proxyEndpoints` you declare — see [Credentials](credentials.md).
+- The package registries for any `environment.packages` you declare (pip → PyPI,
+  apt → the distribution mirrors). Declaring a package implicitly allows the
+  registry it installs from.
+
+`environment.networking` governs the **other** case: arbitrary outbound that
+your own code makes to a host the platform doesn't already manage — a `curl` in
+the `bash` tool, a `requests`/`urllib` call in Python, a `fetch` in
+`code_execution`, or a third-party SDK.
+
+## Restrict a run to an allowlist
+
+Set `mode: "limited"` and list exactly the hosts your code is allowed to reach.
+Anything not on the list (and not one of the always-allowed paths above) is
+blocked, and the call fails. The platform automatically appends the
+infrastructure hosts aex itself needs, so the model and tool paths keep working
+without you listing them.
+
+### TypeScript
+
+```ts
+import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+
+await aex.submit({
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Fetch the public status page and summarize it.",
+  environment: {
+    networking: {
+      mode: "limited",
+      allowedHosts: ["api.example.com", "status.example.com"]
+    }
+  },
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+`allowedHosts` entries are host names (lowercased), e.g. `api.example.com`. Add a
+non-default port when you need one (`api.example.com:8443`); a bare host name
+covers HTTPS on 443. Matching is exact per host — it is not a wildcard or suffix
+match, so list each host you need.
+
+To validate your allowlist before submitting, `buildPlatformAllowedHosts` returns
+the host set the platform will enforce given a base URL plus your extra hosts:
+
+```ts
+import { buildPlatformAllowedHosts } from "@aexhq/sdk";
+
+const allowedHosts = buildPlatformAllowedHosts({
+  baseUrl: "https://api.aex.dev",
+  extraHosts: ["api.example.com"]
+});
+```
+
+## Open mode
+
+`open` is the default: a run that omits `environment.networking` already runs in
+open mode. Set `mode: "open"` explicitly when you want to be unambiguous, or when
+a run needs to reach hosts you can't enumerate ahead of time. The run may then
+reach any public host, still subject to the SSRF deny-list. Prefer `limited`
+whenever you can name the hosts — it gives the run a stable, auditable, least-
+privilege egress surface (it is the tighter posture, not the default).
+
+```ts
+await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Research the topic across the open web.",
+  environment: { networking: { mode: "open" } },
+  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+## Transparent for normal HTTP clients
+
+You write ordinary code — there is no per-request proxy configuration and no
+client changes. The runtime sets the standard proxy environment
+(`HTTP_PROXY` / `HTTPS_PROXY`, with `NO_PROXY` for internal hosts), so any client
+that honors it — `curl`, Python `requests` / `urllib`, `pip`, `npm`, Node
+`fetch`, and most language SDKs — reaches allowed hosts transparently:
+
+```bash
+# In the agent's shell, against a limited run that allows api.example.com:
+curl -sS https://api.example.com/v1/status   # works
+curl -sS https://other-host.example          # blocked (not in allowlist)
+```
+
+You also do **not** need to install any certificate. The platform manages the
+trust store for the managed egress path automatically, so TLS verification in
+your client succeeds without extra setup.
+
+## Limitations and gotchas
+
+- **Enforcement is at the platform boundary, not in your code.** A tool can't
+  bypass the policy by ignoring proxy settings or opening a raw socket — the
+  sandbox has no other route out, so a disallowed host simply fails. This is the
+  intended fail-closed behavior.
+- **A client that hard-bypasses the standard environment may fail to connect.**
+  This is rare — almost all HTTP tooling honors `HTTP_PROXY` / `HTTPS_PROXY` and
+  the system trust store. But a client that is explicitly told to ignore the
+  proxy environment, pins or replaces its certificate trust store, or speaks a
+  non-HTTP protocol over a raw socket can hit a wall even for an allowed host.
+  The fix is to let the client use the standard proxy and certificate
+  environment the runtime provides (most libraries do by default), rather than
+  overriding it.
+- **`allowedHosts` only applies in `limited` mode.** It is ignored in `open`
+  mode, where the SSRF deny-list is the only gate.
+
+For routing credentialed HTTP calls through the managed proxy without putting the
+secret in the container, use proxy endpoints — see
+[Credentials](credentials.md). For remote tool servers, see [MCP](mcp.md). For
+the full set of run-config fields, see [Run configuration](run-config.md).

package/docs/quickstart.md

@@ -10,26 +10,35 @@ title: Quickstart
 bun add @aexhq/sdk
 ```
 
-## 2. Submit a run
+## 2. Run a prompt
 
 ```ts
-import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+import { AgentExecutor, Models } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!
-});
+const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
 
-const runId = await aex.submit({
-  provider: Providers.ANTHROPIC,
+// run() submits, waits for the run to settle, and returns the result.
+// `provider` is derived from the model; `apiKey` is your BYOK provider key.
+const { text, ok } = await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Write a short report and save it as a file.",
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  prompt: "Write a short report and save it as a file."
 });
+
+console.log(ok, text);
 ```
 
-## 3. Stream, wait, and download
+## 3. Submit, stream, wait, and download
+
+When you need the run id, live events, or downloads, drive the lifecycle yourself:
 
 ```ts
+const runId = await aex.submit({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  prompt: "Write a short report and save it as a file."
+});
+
 for await (const event of aex.stream(runId)) {
   console.log(event.type);
 }

package/examples/chat-corpus.ts

@@ -0,0 +1,85 @@
+/**
+ * Reference: a read-only, multi-run chat over a CORPUS of aex runs.
+ *
+ * Combines the public `@aexhq/sdk` corpus read-tools (`createCorpusTools`) with a
+ * direct Claude chat loop (`@anthropic-ai/sdk`). The importable `@aexhq/sdk` stays
+ * LLM-vendor-free; the vendor dependency lives only here in the example (and in
+ * the bundled `aex chat` CLI command).
+ *
+ * Run (Bun): ANTHROPIC_API_KEY=… AEX_TOKEN=… bun examples/chat-corpus.ts <runId> [runId…]
+ *
+ * The model answers ONLY from the named runs' outputs (read via the corpus
+ * tools); a run outside the corpus is refused by the tool layer.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { AgentExecutor, createCorpusTools, DataToolError } from "@aexhq/sdk";
+
+const runIds = process.argv.slice(2);
+if (runIds.length === 0) {
+  console.error("usage: bun examples/chat-corpus.ts <runId> [runId…]");
+  process.exit(2);
+}
+
+const aex = new AgentExecutor({
+  apiToken: process.env.AEX_TOKEN!,
+  ...(process.env.AEX_URL ? { baseUrl: process.env.AEX_URL } : {})
+});
+const tools = createCorpusTools(aex, { runIds });
+const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
+
+const SYSTEM =
+  "You answer questions about a fixed set of aex agent runs using the provided tools. " +
+  tools.instructions;
+
+// Anthropic wire-shape tool defs: { name, description, input_schema }. The corpus
+// tool defs are already in that exact shape. Put one cache_control breakpoint on
+// the LAST tool so the (deterministic) tool list + system prefix cache together.
+const wireTools = tools.tools.map((t, i) => ({
+  name: t.name,
+  description: t.description,
+  input_schema: t.input_schema,
+  ...(i === tools.tools.length - 1 ? { cache_control: { type: "ephemeral" as const } } : {})
+}));
+
+const messages: Anthropic.MessageParam[] = [
+  {
+    role: "user",
+    content: "Across these runs, what did they produce and what are the headline findings?"
+  }
+];
+
+for (let turn = 0; turn < 12; turn++) {
+  const stream = anthropic.messages.stream({
+    model: process.env.AEX_CHAT_MODEL ?? "claude-opus-4-8",
+    max_tokens: 8192,
+    thinking: { type: "adaptive" },
+    system: [{ type: "text", text: SYSTEM }],
+    tools: wireTools,
+    messages
+  });
+  stream.on("text", (delta) => process.stdout.write(delta));
+  const response = await stream.finalMessage();
+  messages.push({ role: "assistant", content: response.content });
+
+  if (response.stop_reason === "refusal") {
+    console.error("\n[refused]", response.stop_details?.category ?? "");
+    break;
+  }
+  if (response.stop_reason === "end_turn" || response.stop_reason === "max_tokens") break;
+  if (response.stop_reason === "pause_turn") continue;
+  if (response.stop_reason !== "tool_use") break;
+
+  const toolResults: Anthropic.ToolResultBlockParam[] = [];
+  for (const block of response.content) {
+    if (block.type !== "tool_use") continue;
+    try {
+      const result = await tools.execute(block.name, block.input as Record<string, unknown>);
+      toolResults.push({ type: "tool_result", tool_use_id: block.id, content: JSON.stringify(result) });
+    } catch (err) {
+      const message = err instanceof DataToolError ? err.message : String(err);
+      toolResults.push({ type: "tool_result", tool_use_id: block.id, content: message, is_error: true });
+    }
+  }
+  messages.push({ role: "user", content: toolResults });
+}
+console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
     "pack:dry-run": "bun ../../scripts/with-generated-dist-lock.mjs bun pm pack --dry-run --ignore-scripts"
   },
   "devDependencies": {
-    "@aexhq/contracts": "0.26.0"
+    "@aexhq/contracts": "0.30.0"
   },
   "engines": {
     "bun": ">=1.3.14"