@aexhq/sdk 0.34.0 → 0.35.0

package/examples/feature-tour.ts

@@ -0,0 +1,301 @@
+/**
+ * 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.
+ *
+ * Run from the repository root after building the workspace package:
+ *
+ *   AEX_API_TOKEN=... DEEPSEEK_API_KEY=... bun packages/sdk/examples/feature-tour.ts
+ *
+ * Optional:
+ *
+ *   AEX_API_URL=https://api.aex.dev
+ *   AEX_FEATURE_TOUR_DOWNLOAD=./feature-tour-session.zip
+ *   AEX_DEMO_RUNTIME_SECRET=...       # mounted as a runtime secret; never printed
+ *   AEX_DEMO_MCP_URL=https://...      # declares an optional remote MCP server
+ *   AEX_DEMO_MCP_TOKEN=...            # optional bearer auth for that MCP server
+ */
+import {
+  AgentsMd,
+  Aex,
+  BuiltinTools,
+  createCorpusTools,
+  File,
+  isRateLimited,
+  isTextMessage,
+  McpServer,
+  Models,
+  ProxyEndpoint,
+  Providers,
+  Secret,
+  Sizes,
+  Tool
+} from "@aexhq/sdk";
+
+process.on("uncaughtException", handleFatal);
+process.on("unhandledRejection", handleFatal);
+
+const apiToken = required("AEX_API_TOKEN");
+const deepseekKey = required("DEEPSEEK_API_KEY");
+const apiUrl = process.env.AEX_API_URL;
+const demoMcpUrl = process.env.AEX_DEMO_MCP_URL;
+const demoMcpToken = process.env.AEX_DEMO_MCP_TOKEN;
+const demoRuntimeSecret = process.env.AEX_DEMO_RUNTIME_SECRET;
+const downloadPath = process.env.AEX_FEATURE_TOUR_DOWNLOAD;
+const textEncoder = new TextEncoder();
+
+const aex = new Aex({
+  apiToken,
+  ...(apiUrl ? { baseUrl: apiUrl } : {}),
+  retry: {
+    maxAttempts: 4,
+    initialDelayMs: 500,
+    maxDelayMs: 10_000,
+    maxElapsedMs: 90_000
+  }
+});
+
+const metricLookup = await Tool.fromFiles({
+  name: "metric_lookup",
+  description: "Looks up normalized demo metrics for one product line.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      product: {
+        type: "string",
+        enum: ["atlas", "beacon", "cinder"],
+        description: "Product line to inspect."
+      }
+    },
+    required: ["product"]
+  },
+  entry: "index.js",
+  files: {
+    "index.js": `
+const DATA = {
+  atlas: { customerCount: 118, activationHealthPct: 72.4, supportTickets: 11 },
+  beacon: { customerCount: 74, activationHealthPct: 65.1, supportTickets: 19 },
+  cinder: { customerCount: 43, activationHealthPct: 58.8, supportTickets: 7 }
+};
+
+export default async function ({ input }) {
+  const key = String(input.product ?? "").toLowerCase();
+  const row = DATA[key];
+  if (!row) {
+    return { content: [{ type: "text", text: \`unknown product: \${key}\` }], is_error: true };
+  }
+  return { content: [{ type: "text", text: JSON.stringify({ product: key, ...row }) }] };
+}
+`
+  }
+});
+
+const demoCsv = [
+  "product,region,q1_revenue_usd,q2_revenue_usd,activation_rate",
+  "atlas,na,120000,139500,0.84",
+  "beacon,emea,98000,104300,0.79",
+  "cinder,apac,67000,81000,0.91"
+].join("\n");
+
+const attachedFile = await File.fromBytes({
+  name: "quarterly-metrics.csv",
+  bytes: textEncoder.encode(`${demoCsv}\n`),
+  mountPath: "/workspace/input"
+});
+
+const runRules = await AgentsMd.fromContent(
+  [
+    "# Feature tour rules",
+    "- Use `/workspace/input/quarterly-metrics.csv` as the source table.",
+    "- Call `metric_lookup` for atlas, beacon, and cinder before writing conclusions.",
+    "- Write final artifacts under `/workspace/outputs`.",
+    "- Never print runtime secret values or provider keys."
+  ].join("\n"),
+  { name: "feature-tour-rules" }
+);
+
+const mcpServers = demoMcpUrl
+  ? [
+      McpServer.remote({
+        name: "demo-mcp",
+        url: demoMcpUrl,
+        ...(demoMcpToken
+          ? { headers: { Authorization: `Bearer ${demoMcpToken}` } }
+          : {})
+      })
+    ]
+  : [];
+
+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"}`);
+
+const session = await aex.openSession({
+  provider: Providers.DEEPSEEK,
+  model: Models.DEEPSEEK_V4_FLASH,
+  system: [
+    "You are a concise analytics agent.",
+    "Prefer exact calculations and write durable files for the caller."
+  ].join(" "),
+  agentsMd: [runRules],
+  files: [attachedFile],
+  includeBuiltinTools: false,
+  tools: [
+    BuiltinTools.read_file,
+    BuiltinTools.write_file,
+    BuiltinTools.bash,
+    BuiltinTools.grep,
+    BuiltinTools.code_execution,
+    metricLookup
+  ],
+  proxyEndpoints,
+  mcpServers,
+  environment: {
+    networking: { mode: "open" },
+    variables: {
+      FEATURE_TOUR: "true",
+      REPORT_DIR: "/workspace/outputs"
+    },
+    ...(environmentSecrets ? { secrets: environmentSecrets } : {})
+  },
+  outputs: {
+    allowedDirs: ["/workspace/outputs"],
+    deniedDirs: ["*.tmp"],
+    maxFiles: 10,
+    maxFileBytes: 1_000_000
+  },
+  outputMode: "stream",
+  runtime: Sizes.SHARED_0_25X_1GB,
+  metadata: {
+    example: "sdk-feature-tour",
+    sdkSurface: "public"
+  },
+  overrides: {
+    idleTtl: "5m",
+    timeout: "10m",
+    maxSpendUsd: 2
+  },
+  apiKeys: { deepseek: deepseekKey }
+});
+
+console.log(`session: ${session.id}`);
+
+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."
+].join(" ");
+
+const firstTurn = session.send(prompt);
+const firstTurnIterator = firstTurn[Symbol.asyncIterator]();
+let result: Awaited<ReturnType<typeof firstTurn.done>> | undefined;
+for (;;) {
+  const next = await firstTurnIterator.next();
+  if (next.done) {
+    result = next.value as Awaited<ReturnType<typeof firstTurn.done>>;
+    break;
+  }
+  const event = next.value;
+  if (isTextMessage(event)) {
+    process.stdout.write(event.data.text);
+  } else if (event.type === "TOOL_CALL_START") {
+    const name = typeof event.data.name === "string" ? event.data.name : "tool";
+    process.stdout.write(`\n[tool:start] ${name}\n`);
+  } else if (event.type === "TOOL_CALL_RESULT") {
+    process.stdout.write("[tool:result]\n");
+  }
+}
+
+if (!result) {
+  throw new Error("first turn stream ended without a result");
+}
+console.log(`\nfirst turn parked with status: ${result.status}`);
+
+const followUp = await session
+  .send("Read summary.json back and answer with one sentence confirming the top product and total Q2 revenue.")
+  .done();
+console.log(`follow-up status: ${followUp.status}`);
+if (followUp.text) {
+  console.log(`follow-up text: ${followUp.text.trim()}`);
+}
+
+const parked = await session.wait({ timeoutMs: 60_000, intervalMs: 2_000 });
+console.log(`settled session status: ${parked.status}`);
+
+const messages = await session.messages().list();
+console.log(`assistant messages: ${messages.length}`);
+
+const events = await session.events().list();
+console.log(`captured events: ${events.length}`);
+
+const outputs = await session.outputs().list();
+console.log("outputs:");
+for (const output of outputs) {
+  console.log(`- ${output.filename ?? output.id} (${output.contentType ?? "unknown"})`);
+}
+
+const summary = await session.outputs().read(
+  { path: "summary.json", match: "suffix" },
+  { maxBytes: 20_000 }
+);
+console.log("summary.json:");
+console.log(summary.text);
+
+const report = await session.outputs().findOne({
+  filename: "feature-tour-report.md"
+});
+if (report) {
+  const reportPreview = await session.outputs().read(report, {
+    maxBytes: 4_000,
+    grep: "risk"
+  });
+  console.log("report risk lines:");
+  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));
+
+if (downloadPath) {
+  const bytes = await session.download({ to: downloadPath });
+  console.log(`downloaded session archive: ${downloadPath} (${bytes.byteLength} bytes)`);
+}
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`Missing env var ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function handleFatal(err: unknown): void {
+  if (isRateLimited(err)) {
+    console.error(`rate limited after ${err.attempts} attempts; retry after ${err.retryAfterMs ?? "unknown"}ms`);
+    process.exit(1);
+  }
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  process.exit(1);
+}

package/package.json

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