@aexhq/sdk 0.40.4 → 0.40.6

package/docs/secrets.md

@@ -1,134 +1,129 @@
----
-title: Secrets
----
-
-# Secrets
-
-aex supports BYOK provider keys, per-run credentials, and reusable workspace
-secrets. Secret values are excluded from the idempotency fingerprint and do not
-belong in run config.
-
-Runnable examples need both `AEX_API_KEY` for aex and the matching BYOK
-provider key, such as `ANTHROPIC_API_KEY` for Claude.
-
-## Use A Provider Key For One Run
-
-### TypeScript
-
-```ts
-import { Aex, Models } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  message: "Write a short report and save it as a file.",
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-### CLI
-
-```bash
-aex run \
-  --api-key "$AEX_API_KEY" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --model claude-haiku-4-5 \
-  --prompt "Write a short report and save it as a file."
-```
-
-## Upload An Env Secret
-
-Use `Secret.value(...).upload(...)` when you start with an ephemeral value and
-want to persist it as a named workspace secret for later runs.
-
-```ts
-import { Aex, Models, Providers, Secret } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-const githubToken = await Secret.value(process.env.GITHUB_TOKEN!).upload(aex, {
-  name: "github-token"
-});
-
-await aex.run({
-  provider: Providers.ANTHROPIC,
-  model: Models.CLAUDE_HAIKU_4_5,
-  message: "Inspect the repository issues.",
-  environment: { secrets: { GITHUB_TOKEN: githubToken } },
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-## Set Or Rotate A Workspace Secret
-
-Use `client.secrets.set(...)` to create a named secret directly. Use
-`client.secrets.rotate(...)` to replace its value while keeping the same name.
-
-```ts
-await aex.secrets.set({
-  name: "serper-api-key",
-  value: process.env.SERPER_API_KEY!
-});
-
-await aex.secrets.rotate({
-  name: "serper-api-key",
-  value: process.env.SERPER_API_KEY_NEXT!
-});
-```
-
-## Retrieve Secret Metadata
-
-`list` and `get` return metadata only. They never return the secret value.
-
-```ts
-const secrets = await aex.secrets.list();
-const metadata = await aex.secrets.get("serper-api-key");
-```
-
+---
+title: Secrets
+---
+
+# Secrets
+
+aex supports BYOK provider keys, per-run credentials, and reusable workspace
+secrets. Secret values are excluded from the idempotency fingerprint and do not
+belong in run config.
+
+Runnable examples need both `AEX_API_KEY` for aex and the matching BYOK
+provider key, such as `ANTHROPIC_API_KEY` for Claude.
+
+## Use A Provider Key For One Run
+
+### TypeScript
+
+```ts
+import { Aex, Models } from "@aexhq/sdk";
+
+const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
+
+await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Write a short report and save it as a file.",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+### CLI
+
+```bash
+aex run \
+  --api-key "$AEX_API_KEY" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --model claude-haiku-4-5 \
+  --prompt "Write a short report and save it as a file."
+```
+
+## Upload An Env Secret
+
+Use `Secret.value(...).upload(...)` when you start with an ephemeral value and
+want to persist it as a named workspace secret for later runs.
+
+```ts
+import { Aex, Models, Providers, Secret } from "@aexhq/sdk";
+
+const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
+
+const githubToken = await Secret.value(process.env.GITHUB_TOKEN!).upload(aex, {
+  name: "github-token"
+});
+
+await aex.run({
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Inspect the repository issues.",
+  environment: { secrets: { GITHUB_TOKEN: githubToken } },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+## Set Or Rotate A Workspace Secret
+
+Use `client.secrets.set(...)` to create a named secret directly. Use
+`client.secrets.rotate(...)` to replace its value while keeping the same name.
+
+```ts
+await aex.secrets.set({
+  name: "serper-api-key",
+  value: process.env.SERPER_API_KEY!
+});
+
+await aex.secrets.rotate({
+  name: "serper-api-key",
+  value: process.env.SERPER_API_KEY_NEXT!
+});
+```
+
+## Retrieve Secret Metadata
+
+`list` and `get` return metadata only. They never return the secret value.
+
+```ts
+const secrets = await aex.secrets.list();
+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.
-
-```ts
-import { Models, Providers, Secret } from "@aexhq/sdk";
-
-await aex.run({
-  provider: Providers.ANTHROPIC,
-  model: Models.CLAUDE_HAIKU_4_5,
-  message: "Use SERPER_API_KEY for web search.",
-  environment: {
-    secrets: { SERPER_API_KEY: Secret.ref("serper-api-key") }
-  },
-  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-## Delete A Workspace Secret
-
-```ts
-await aex.secrets.delete("serper-api-key");
-```
-
-The CLI supports per-run provider and MCP credentials. Workspace secret
-administration is exposed through the SDK.
-
-## Redaction Scope And Output Files
-
-Registered secret values are redacted from the run's **event stream** (both tool
-output and model-authored surfaces) — a value you inject via `environment.secrets`
-is masked regardless of its shape. Two surfaces are intentionally *not* scrubbed:
-
-- **Captured output files** (`outputs().download()` / `read()` / the `aex download`
-  zip) are returned **verbatim**. They are your run's own artifacts, so the platform
-  does not rewrite their bytes — if the agent writes a secret into a deliverable file,
-  that file contains it. Treat downloaded outputs as unredacted.
-- An **unregistered** secret (a credential the run produces itself and never declared
-  via `environment.secrets`) can only be masked heuristically by shape; register the
-  values you care about so they are masked by value.
+
+```ts
+import { Models, Providers, Secret } from "@aexhq/sdk";
+
+await aex.run({
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Use SERPER_API_KEY for web search.",
+  environment: {
+    secrets: { SERPER_API_KEY: Secret.ref("serper-api-key") }
+  },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
+});
+```
+
+## Delete A Workspace Secret
+
+```ts
+await aex.secrets.delete("serper-api-key");
+```
+
+The CLI supports per-run provider and MCP credentials. Workspace secret
+administration is exposed through the SDK.
+
+## Redaction Scope And Output Files
+
+Registered secret values are redacted from the run's **event stream** (both tool
+output and model-authored surfaces) — a value you inject via `environment.secrets`
+is masked regardless of its shape. Two surfaces are intentionally *not* scrubbed:
+
+- **Captured output files** (`outputs().download()` / `read()` / the `aex download`
+  zip) are returned **verbatim**. They are your run's own artifacts, so the platform
+  does not rewrite their bytes — if the agent writes a secret into a deliverable file,
+  that file contains it. Treat downloaded outputs as unredacted.
+- An **unregistered** secret (a credential the run produces itself and never declared
+  via `environment.secrets`) can only be masked heuristically by shape; register the
+  values you care about so they are masked by value.

package/docs/testing.md

@@ -1,35 +1,35 @@
----
-title: Testing
----
-
-# Testing
-
-aex uses test-first development.
-For repository changes, default the first meaningful test to blackbox behavior
-from requirements, public contracts, docs, logs, or user-visible evidence before
-reading or changing implementation.
-
-Workspace-wide commands:
-
-```text
-bun run lint                                      # typecheck/build prerequisites + lint
-bun run test                                      # unit, all packages, deterministic
-bun run test:user:offline                         # clean Bun install of packed/published SDK, no live API
-bun run test:user                                 # live hosted API user tests
-bun run test:user:heavy                           # explicit heavy live canary
-bun run docs:build                                # generated docs + Next build
-bun run pack:sdk                                  # SDK pack dry-run + public boundary check
-```
-
-Unit tests are deterministic and may use fakes. Offline user tests install the
-packed or published SDK into clean Bun temp projects and do not need provider
-credentials.
-
-When neither `AEX_USER_TEST_TARBALL` nor `AEX_USER_TEST_VERSION` is set, the
-user-test fixture packs the current workspace SDK into a tempdir and installs
-that artifact. CI or release validation can pin an explicit artifact with
-exactly one of `AEX_USER_TEST_TARBALL` or `AEX_USER_TEST_VERSION`.
-
-Live user tests run against a hosted aex API and fail loudly when required env
-is missing: `AEX_API_URL`, `AEX_API_KEY`, `ANTHROPIC_API_KEY`, and
-`DEEPSEEK_API_KEY`.
+---
+title: Testing
+---
+
+# Testing
+
+aex uses test-first development.
+For repository changes, default the first meaningful test to blackbox behavior
+from requirements, public contracts, docs, logs, or user-visible evidence before
+reading or changing implementation.
+
+Workspace-wide commands:
+
+```text
+bun run lint                                      # typecheck/build prerequisites + lint
+bun run test                                      # unit, all packages, deterministic
+bun run test:user:offline                         # clean Bun install of packed/published SDK, no live API
+bun run test:user                                 # live hosted API user tests
+bun run test:user:heavy                           # explicit heavy live canary
+bun run docs:build                                # generated docs + Next build
+bun run pack:sdk                                  # SDK pack dry-run + public boundary check
+```
+
+Unit tests are deterministic and may use fakes. Offline user tests install the
+packed or published SDK into clean Bun temp projects and do not need provider
+credentials.
+
+When neither `AEX_USER_TEST_TARBALL` nor `AEX_USER_TEST_VERSION` is set, the
+user-test fixture packs the current workspace SDK into a tempdir and installs
+that artifact. CI or release validation can pin an explicit artifact with
+exactly one of `AEX_USER_TEST_TARBALL` or `AEX_USER_TEST_VERSION`.
+
+Live user tests run against a hosted aex API and fail loudly when required env
+is missing: `AEX_API_URL`, `AEX_API_KEY`, `ANTHROPIC_API_KEY`, and
+`DEEPSEEK_API_KEY`.

package/docs/vision-skills.md

@@ -1,94 +1,94 @@
----
-title: Call a vision 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 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.
-
-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.
-
-## Submit the run
-
-```ts
+---
+title: Call a vision 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 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.
+
+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.
+
+## Submit the run
+
+```ts
 import { Aex, Models, Secret, Skill } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-const result = await aex.run({
-  model: Models.CLAUDE_HAIKU_4_5,
-  message: "Read skills/frame-vision-gate/SKILL.md, then caption and verify the frame.",
+
+const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
+
+const result = await aex.run({
+  model: Models.CLAUDE_HAIKU_4_5,
+  message: "Read skills/frame-vision-gate/SKILL.md, then caption and verify the frame.",
   skills: [await Skill.fromDir("./vision-skill", { name: "frame-vision-gate" })],
-  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);
-```
-
+  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);
+```
+
 `Skill.fromDir("./vision-skill", ...)` is resolved relative to the process
-CWD. Run the script from the directory that contains `vision-skill/` (in this
-repo, `examples/`).
-
-## Call the provider from the skill
-
-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, os, urllib.request
-
-b64 = base64.b64encode(open("/workspace/files/frame.jpg", "rb").read()).decode()
-request_body = {
-    "model": "doubao-seed-1-6-vision-250815",
-    "temperature": 0,
-    "response_format": {"type": "json_object"},
-    "messages": [
-        {"role": "system", "content": "Describe only what the pixels show."},
-        {"role": "user", "content": [
-            {"type": "text", "text": "Does this frame depict an owlbear? Answer as JSON."},
-            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}
-        ]}
-    ]
-}
-
-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",
-)
-```
-
-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.
-
-## Payload size
-
-Base64 images are larger than their source files. Scale frames before captioning
-when possible, for example:
-
-```bash
-ffmpeg -i source.mp4 -vf fps=1,scale=960:-1 frame_%03d.jpg
-```
-
-This keeps upload size and model cost bounded without losing the signal most
-vision models need.
+CWD. Run the script from the directory that contains `vision-skill/` (in this
+repo, `examples/`).
+
+## Call the provider from the skill
+
+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, os, urllib.request
+
+b64 = base64.b64encode(open("/workspace/files/frame.jpg", "rb").read()).decode()
+request_body = {
+    "model": "doubao-seed-1-6-vision-250815",
+    "temperature": 0,
+    "response_format": {"type": "json_object"},
+    "messages": [
+        {"role": "system", "content": "Describe only what the pixels show."},
+        {"role": "user", "content": [
+            {"type": "text", "text": "Does this frame depict an owlbear? Answer as JSON."},
+            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}
+        ]}
+    ]
+}
+
+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",
+)
+```
+
+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.
+
+## Payload size
+
+Base64 images are larger than their source files. Scale frames before captioning
+when possible, for example:
+
+```bash
+ffmpeg -i source.mp4 -vf fps=1,scale=960:-1 frame_%03d.jpg
+```
+
+This keeps upload size and model cost bounded without losing the signal most
+vision models need.