@aexhq/sdk 0.35.0 → 0.37.0

package/docs/secrets.md

@@ -88,6 +88,11 @@ const metadata = await aex.secrets.get("serper-api-key");
 
 ## Inject A Workspace Secret Into A Run
 
+> **Availability note:** workspace-secret `Secret.ref(...)` injection requires
+> the next platform deploy — on the current hosted plane the referenced
+> variable can resolve empty inside the run. Per-run `Secret.value(...)`
+> secrets are unaffected. This note will be removed once the deploy lands.
+
 Reference workspace secrets with `Secret.ref(name)`. The value resolves
 server-side and is injected as the named environment variable.
 
@@ -111,5 +116,5 @@ await aex.run({
 await aex.secrets.delete("serper-api-key");
 ```
 
-The CLI supports per-run provider, MCP, and proxy credentials. Workspace secret
+The CLI supports per-run provider and MCP credentials. Workspace secret
 administration is exposed through the SDK.

package/docs/skills.md

@@ -72,9 +72,9 @@ files into the workspace under `/workspace/skills/<name>/`. So the `SKILL.md` bo
 and every supporting file are on disk from the first turn; the load-tool call is
 how that body enters the model's context, not how the files get written.
 
-The platform also mounts the `aex` CLI and a per-run manifest into every run.
-Skills call managed HTTP proxy endpoints through the mounted CLI
-(`aex proxy ...`); see [Credentials](credentials.md) for the policy and auth model.
+Skills that call external HTTP APIs should read credentials from
+`environment.secrets` and use the normal client for that service. See
+[Credentials](credentials.md) for the secret model.
 
 Run-scoped asset copies are part of the run record and are removed by run deletion
 or retention cleanup.

package/docs/vision-skills.md

@@ -1,73 +1,57 @@
 ---
-title: Call a vision (or any model) API from a skill
+title: Call a vision API from a skill
 ---
 
-# Call a vision (or any model) API from a skill
+# Call a vision API from a skill
 
-aex has no built-in vision tool. The agent's `provider`/`model` selects the
-*reasoning* model — it is not an endpoint a skill can POST an image to mid-run.
-To give a run image understanding (or to call any other model/HTTP API), ship a
-**skill** that POSTs to the provider's OpenAI-compatible endpoint **through the
-managed proxy**, with the key supplied on a `ProxyEndpoint.bearer(...)` instance.
-The raw key never enters the container.
+aex has no built-in vision tool. The agent's `provider` / `model` selects the
+reasoning model for the run; if a skill needs image understanding mid-run, ship a
+skill that calls the vision provider with normal HTTP and pass that provider key
+as a runtime secret.
 
-This is the same proxy described in `credentials.md` — this page is the worked
-recipe for the model-API case, which has two wrinkles a plain JSON call does not:
-the image rides as a **base64 data URL** in the request body, and that body is
-large enough to need a raised `maxRequestBytes`.
+The runnable example lives at [`examples/vision-skill/`](../../../examples/vision-skill).
+It captions a frame with ByteDance Doubao Seed Vision (Ark) and returns a
+per-noun "does the frame depict X?" verdict.
 
-The canonical, runnable example lives in the repo at
-[`examples/vision-skill/`](../../../examples/vision-skill) (`SKILL.md`,
-`caption_frame.py`, `verify_frame.py`, `run_with_vision_skill.mjs`). It
-captions a frame with ByteDance Doubao Seed Vision (Ark) and returns a per-noun
-"does the frame depict X?" verdict. Everything below is taken from it.
-
-## 1. Declare the model endpoint as a proxy endpoint
-
-The vision provider's API is just an HTTPS host. Declare it with
-`ProxyEndpoint.bearer(...)`, which carries the key on the instance. The two
-model-specific settings are `responseMode: "full"` (so the skill gets the upstream
-JSON back) and a raised `maxRequestBytes` (so the base64 image fits):
+## Submit the run
 
 ```ts
-import { Aex, Models, Tools, ProxyEndpoint } from "@aexhq/sdk";
+import { Aex, Models, Secret, Tools } from "@aexhq/sdk";
 
 const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
 
-const doubaoArk = ProxyEndpoint.bearer({
-  name: "doubao-ark",
-  baseUrl: "https://ark.ap-southeast.bytepluses.com", // intl BytePlus gateway
-  token: process.env.DOUBAO_API_KEY!,
-  allowMethods: ["POST"],
-  allowPathPrefixes: ["/api/v3/chat/completions"],
-  maxRequestBytes: 2_000_000, // base64 image POSTs — see note below
-  responseMode: "full",
-  timeoutMs: 60_000
-});
-
-await aex.run({
+const result = await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  message: "…read skills/frame-vision-gate/SKILL.md, then caption + verify the frame…",
+  message: "Read skills/frame-vision-gate/SKILL.md, then caption and verify the frame.",
   tools: [await Tools.fromSkillDir("./vision-skill", { name: "frame-vision-gate" })],
-  proxyEndpoints: [doubaoArk],
+  environment: {
+    secrets: {
+      DOUBAO_API_KEY: Secret.value(process.env.DOUBAO_API_KEY!)
+    },
+    networking: {
+      mode: "limited",
+      allowedHosts: ["ark.ap-southeast.bytepluses.com"]
+    }
+  },
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
+
+console.log(result.runId, result.text);
 ```
 
-`Tools.fromSkillDir("./vision-skill", …)` is resolved relative to the process CWD, so
-run the script from the directory that *contains* `vision-skill/` (in the
-repo, that is `examples/`). The same pattern works for OpenAI, Gemini's
-OpenAI-compatible endpoint, or any other OpenAI-chat-shaped vision API — only
-`baseUrl` and the path prefix change.
+`Tools.fromSkillDir("./vision-skill", ...)` is resolved relative to the process
+CWD. Run the script from the directory that contains `vision-skill/` (in this
+repo, `examples/`).
 
-## 2. POST the image as a base64 data URL through the proxy
+## Call the provider from the skill
 
-Inside the run, the skill builds the OpenAI-compatible chat-completions body. The
-image is **base64-inlined as a data URL** in an `image_url` content part — it is
-not uploaded:
+Inside the run, the skill reads `DOUBAO_API_KEY` and makes an
+OpenAI-compatible chat-completions request with Python's standard HTTP client.
+The image is base64-inlined as a data URL in the request body:
 
 ```python
-import base64, json
+import base64, json, os, urllib.request
+
 b64 = base64.b64encode(open("/workspace/files/frame.jpg", "rb").read()).decode()
 request_body = {
     "model": "doubao-seed-1-6-vision-250815",
@@ -81,63 +65,30 @@ request_body = {
         ]}
     ]
 }
-```
-
-Write the body to a file and hand it to the mounted CLI with `--data @<file>`
-(the mount has no execute bit, so invoke through `bun`; see `credentials.md`):
 
-```python
-import subprocess
-body_path = "/workspace/.aex/_ark_request.json"
-open(body_path, "w").write(json.dumps(request_body))
-
-result = subprocess.run(
-    ["bun", "/mnt/session/uploads/aex/aex", "proxy", "doubao-ark",
-     "--method", "POST",
-     "--path", "/api/v3/chat/completions",
-     "--header", "content-type=application/json",
-     "--data", f"@{body_path}",
-     "--response-mode", "full"],
-    capture_output=True, text=True, timeout=90,
+req = urllib.request.Request(
+    "https://ark.ap-southeast.bytepluses.com/api/v3/chat/completions",
+    data=json.dumps(request_body).encode("utf-8"),
+    headers={
+        "Authorization": f"Bearer {os.environ['DOUBAO_API_KEY']}",
+        "Content-Type": "application/json"
+    },
+    method="POST",
 )
 ```
 
-In `--response-mode full` the CLI prints a `ProxyResponseEnvelope` on stdout. The
-upstream JSON is **base64-encoded** in `upstreamBodyBase64`; an error instead
-carries an `error` field. Unwrap it:
-
-```python
-envelope = json.loads(result.stdout)
-if "error" in envelope:
-    raise RuntimeError(f"proxy error: {envelope['error']}: {envelope['message']}")
-upstream = json.loads(base64.b64decode(envelope["upstreamBodyBase64"]).decode())
-content = upstream["choices"][0]["message"]["content"]  # the model's JSON answer
-```
-
-The key is injected by the hosted proxy on the outbound call; it never appears on disk in
-the container or in the model's context.
-
-## `maxRequestBytes` and timeout defaults
+The same pattern works for OpenAI, Gemini's OpenAI-compatible endpoint, or any
+other HTTPS model API. Put the key in `environment.secrets`, allow-list the host
+when using limited networking, and use the provider's normal SDK or HTTP API.
 
-The per-endpoint `maxRequestBytes` default is **10 MiB** and the default timeout
-is **5 minutes**. That fits typical base64 image/model POSTs without extra
-configuration. If a body does exceed the cap, the proxy rejects it before any
-upstream call with an explicit error naming the observed size, the configured
-cap, and how to raise it:
+## Payload size
 
-> request body is 2400000 bytes, which exceeds this endpoint's maxRequestBytes
-> (10485760). Raise the per-endpoint maxRequestBytes in the proxy endpoint policy …
+Base64 images are larger than their source files. Scale frames before captioning
+when possible, for example:
 
-Two ways to stay under the cap: raise `maxRequestBytes`, and/or scale frames
-before captioning (`ffmpeg -i source.mp4 -vf fps=1,scale=960:-1 frame_%03d.jpg`)
-so full-res frames do not add payload and model cost without useful signal.
-
-## Notes
+```bash
+ffmpeg -i source.mp4 -vf fps=1,scale=960:-1 frame_%03d.jpg
+```
 
-- **Host selection.** Use the provider endpoint that matches your account and
-  declare it as the proxy endpoint `baseUrl`.
-- **Keyless model hosts.** If the upstream takes no credential, declare the
-  endpoint with `ProxyEndpoint.none(...)` (see `credentials.md`).
-- **Response size.** `responseMode: "full"` is required to read the model's reply
-  back. Leave `maxResponseBytes` at its default (`0` = unlimited, streamed) unless
-  you want a truncation cap.
+This keeps upload size and model cost bounded without losing the signal most
+vision models need.

package/docs/webhooks.md

@@ -0,0 +1,132 @@
+---
+title: Webhooks
+---
+
+# Webhooks
+
+aex can notify your endpoint when a run finishes. Webhooks are **per-run**: you
+pass a callback URL with the submission, and the platform delivers exactly one
+`run.finished` event to it when the run reaches its terminal state.
+
+> **Availability note:** terminal webhook delivery for session-based runs
+> requires the next platform deploy — on the current hosted plane a session
+> run's webhook may not fire. This note will be removed once the deploy lands.
+
+## Register a callback
+
+```ts
+import { Aex, Models } from "@aexhq/sdk";
+
+const aex = new Aex(process.env.AEX_API_TOKEN!);
+
+const session = await aex.openSession({
+  model: Models.CLAUDE_HAIKU_4_5,
+  webhook: { url: "https://hooks.example.com/aex" },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+```bash
+aex run \
+  --api-token "$AEX_API_TOKEN" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --prompt "Write the report." \
+  --webhook https://hooks.example.com/aex
+```
+
+The URL must be `https`. The callback URL is an operational concern, not part
+of the submission fingerprint: retrying the same submission with the same
+idempotency key but a different callback URL never conflicts.
+
+## What gets delivered
+
+One POST carrying the terminal `run.finished` event, sent at the
+settle-consistent barrier — when you receive it, the run record is already
+terminal and its outputs are complete and readable. The body is built once at
+settle, frozen, and re-sent byte-identical on every retry or manual redelivery:
+
+```json
+{
+  "specversion": "1.0",
+  "id": "<delivery id — matches the webhook-id header>",
+  "source": "aex",
+  "type": "run.finished",
+  "subject": "<the run id>",
+  "time": "2026-07-02T12:34:56.000Z",
+  "data": {
+    "runId": "<the run id>",
+    "status": "succeeded",
+    "terminalAt": "2026-07-02T12:34:56.000Z",
+    "reason": null,
+    "failureClass": null,
+    "costTelemetry": { "billedCostUsd": 0.42 }
+  }
+}
+```
+
+`reason` / `failureClass` carry the failure detail on non-success terminals;
+`costTelemetry` is present when the billed cost is known.
+
+## Verify deliveries
+
+Deliveries are signed [Standard Webhooks](https://www.standardwebhooks.com/)
+style: HMAC-SHA256 over `` `${webhook-id}.${webhook-timestamp}.${rawBody}` ``,
+sent in three headers — `webhook-id` (stable across retries; your dedupe key),
+`webhook-timestamp` (unix seconds), and `webhook-signature` (a space-delimited
+list of `v1,<base64>` entries).
+
+The signing key is a per-workspace secret. Reveal it (it is created on first
+use) with either surface:
+
+```bash
+aex webhooks secret --api-token "$AEX_API_TOKEN"   # prints whsec_...
+```
+
+```ts
+const { whsec } = await aex.webhookSigningSecret();
+```
+
+Verify inbound requests with the exported `verifyAexWebhook` — pure Web Crypto,
+identical under Bun and Node, and interoperable with the `standardwebhooks`
+reference library:
+
+```ts
+import { verifyAexWebhook } from "@aexhq/sdk";
+
+// In your HTTP handler — use the EXACT raw body bytes, never re-serialize.
+const ok = await verifyAexWebhook({
+  rawBody,
+  headers: request.headers,
+  secret: process.env.AEX_WEBHOOK_SECRET! // the whsec_... value
+});
+if (!ok) return new Response("bad signature", { status: 401 });
+```
+
+`verifyAexWebhook` rejects stale timestamps (default tolerance 300 seconds) and
+compares signatures constant-time. It accepts every `v1` entry in the signature
+list, so it is already rotation-ready — but **server-side rotation of the
+signing secret is not available yet**: `aex webhooks secret` reveals or creates
+the one workspace secret and there is no rotate endpoint today. If your secret
+is compromised, contact <support@aex.dev>.
+
+## Delivery ledger and redelivery
+
+Each run keeps a delivery ledger — attempts, last status code, and last error:
+
+```ts
+const deliveries = await session.webhooks().list();
+await session.webhooks().redeliver(deliveries[0]!.id);
+```
+
+```bash
+aex deliveries <session-id> --api-token "$AEX_API_TOKEN"
+```
+
+Redelivery re-sends the frozen payload with the **same** `webhook-id`, so a
+consumer that dedupes on `webhook-id` handles retries, redeliveries, and
+at-least-once delivery uniformly. An empty ledger means the run carried no
+`webhook` or has not reached a terminal state yet.
+
+For the terminal-event mechanics behind delivery timing, see
+[Events](events.md).

package/examples/feature-tour.ts

@@ -2,7 +2,7 @@
  * SDK feature tour: one managed session that uses typed model/runtime constants,
  * inline AGENTS.md guidance, uploaded files, a custom tool bundle, selected
  * built-in tools, runtime env vars/secrets, streamed events, output reads, and
- * corpus-scoped data tools.
+ * a follow-up session turn.
  *
  * Run from the repository root after building the workspace package:
  *
@@ -20,13 +20,11 @@ import {
   AgentsMd,
   Aex,
   BuiltinTools,
-  createCorpusTools,
   File,
   isRateLimited,
   isTextMessage,
   McpServer,
   Models,
-  ProxyEndpoint,
   Providers,
   Secret,
   Sizes,
@@ -132,17 +130,6 @@ const environmentSecrets = demoRuntimeSecret
   ? { DEMO_RUNTIME_SECRET: Secret.value(demoRuntimeSecret) }
   : undefined;
 
-const proxyEndpoints = [
-  ProxyEndpoint.none({
-    name: "httpbin",
-    baseUrl: "https://httpbin.org",
-    allowMethods: ["GET"],
-    allowPathPrefixes: ["/json"],
-    responseMode: "full",
-    timeoutMs: 10_000
-  })
-];
-
 console.log("creating feature-tour session...");
 console.log(`optional mcp: ${mcpServers.length > 0 ? "enabled" : "disabled"}`);
 console.log(`optional runtime secret: ${environmentSecrets ? "enabled" : "disabled"}`);
@@ -165,7 +152,6 @@ const session = await aex.openSession({
     BuiltinTools.code_execution,
     metricLookup
   ],
-  proxyEndpoints,
   mcpServers,
   environment: {
     networking: { mode: "open" },
@@ -201,8 +187,7 @@ const prompt = [
   "Analyze the attached quarterly metrics.",
   "Call metric_lookup for atlas, beacon, and cinder.",
   "Create /workspace/outputs/feature-tour-report.md with a short table, a ranking by q2_revenue_usd, and two risks.",
-  "Create /workspace/outputs/summary.json with keys topProduct, totalQ2RevenueUsd, highestActivationProduct, and riskCount.",
-  "Mention whether the httpbin proxy endpoint is declared, but do not call it unless you need to."
+  "Create /workspace/outputs/summary.json with keys topProduct, totalQ2RevenueUsd, highestActivationProduct, and riskCount."
 ].join(" ");
 
 const firstTurn = session.send(prompt);
@@ -272,10 +257,8 @@ if (report) {
   console.log(reportPreview.text || "(no risk lines found)");
 }
 
-const corpusTools = createCorpusTools(aex, { sessionIds: [session.id] }, { defaultReadBytes: 4_000 });
-const corpusOutputs = await corpusTools.execute("list_outputs", { session_id: session.id });
-console.log("corpus-scoped list_outputs result:");
-console.log(JSON.stringify(corpusOutputs, null, 2));
+const reopenedOutputs = await aex.sessions.outputs(session.id).list();
+console.log(`outputs via aex.sessions.outputs(...): ${reopenedOutputs.length}`);
 
 if (downloadPath) {
   const bytes = await session.download({ to: downloadPath });

package/package.json

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