@aexhq/sdk 0.29.0 → 0.31.0

package/docs/secrets.md

@@ -8,20 +8,22 @@ 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_TOKEN` 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 { AgentExecutor, Models, Providers } from "@aexhq/sdk";
+import { AgentExecutor, Models } 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: "Write the report and save outputs.",
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 
@@ -54,7 +56,7 @@ await aex.submit({
   model: Models.CLAUDE_HAIKU_4_5,
   prompt: "Inspect the repository issues.",
   secretEnv: { GITHUB_TOKEN: githubToken },
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 
@@ -109,7 +111,7 @@ await aex.submit({
   secretEnv: {
     SERPER_API_KEY: Secret.ref("serper-api-key")
   },
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
+  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
 });
 ```
 

package/docs/skills.md

@@ -24,12 +24,6 @@ All three sources normalize to the same content-addressed asset. Identical bytes
 dedup by hash, so repeated submissions of the same bundle are no-op uploads.
 There is no per-run auto-suffixed `skl_*` row for inline skills.
 
-Provider-hosted skill refs (`kind:"provider"`, e.g. Anthropic prebuilt Agent
-Skills or custom provider skill IDs) are not supported on the managed runtime.
-Every new submission dispatches to managed, so a `kind:"provider"` ref is
-rejected at submission time with `feature_runtime_mismatch`. Supply the bytes as
-an aex asset instead.
-
 ## Materialization
 
 For each run, the platform copies referenced skill assets into durable run asset
@@ -68,7 +62,7 @@ await aex.submit({
   model: RunModels.CLAUDE_HAIKU_4_5,
   prompt,
   skills: [await Skill.fromPath("./skills/rules", { name: "rules" })],
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 
@@ -80,9 +74,7 @@ flow:
 2. The SDK PUTs bytes directly to object storage with the signed checksum headers.
 3. `POST /assets/finalize` confirms the object exists.
 
-When direct upload credentials are not configured, small bundles fall back to
-the buffered `/assets` upload path. The runner re-verifies the content hash when
-it downloads the asset.
+The runner re-verifies the content hash when it downloads the asset.
 
 ## Pre-Upload For Reuse
 
@@ -97,7 +89,7 @@ await aex.submit({
   model: RunModels.CLAUDE_HAIKU_4_5,
   prompt,
   skills: [uploaded],
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 
@@ -134,7 +126,7 @@ await aex.submit({
   model: RunModels.CLAUDE_HAIKU_4_5,
   prompt,
   skills: [Skill.fromCatalog(record)],
-  secrets: { apiKey }
+  secrets: { apiKeys: { anthropic: apiKey } }
 });
 ```
 

package/docs/vision-skills.md

@@ -58,7 +58,7 @@ const runId = await aex.submit({
   skills: [await Skill.fromPath("./vision-skill", { name: "frame-vision-gate" })],
   proxyEndpoints,
   secrets: {
-    apiKey: process.env.ANTHROPIC_API_KEY!,
+    apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
     proxyEndpointAuth
   }
 });

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.31.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.31.0"
   },
   "engines": {
     "bun": ">=1.3.14"