@aexhq/sdk 0.46.4-canary → 0.50.0

package/docs/telemetry.md

@@ -1,66 +0,0 @@
----
-title: OpenTelemetry export
----
-
-# OpenTelemetry export
-
-aex exposes each session's customer-visible trace and log timeline as
-standards-pure OTLP/HTTP JSON. The session journal remains the source of truth;
-the API derives telemetry from that durable history when you read it. This is
-a pull surface. It does not configure a push drain or create another telemetry
-store.
-
-## SDK
-
-Open a session and iterate its trace or log pages:
-
-```ts
-import { Aex } from "aex";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-const session = await aex.sessions.open("ses_...");
-
-for await (const request of session.otel.traces()) {
-  // `request` is an OTLP ExportTraceServiceRequest JSON body.
-  await fetch("http://localhost:4318/v1/traces", {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(request)
-  });
-}
-
-for await (const request of session.otel.logs()) {
-  // `request` is an OTLP ExportLogsServiceRequest JSON body.
-}
-```
-
-The SDK follows the API's opaque `x-aex-next-cursor` response header. Cursor
-metadata is never inserted into the OTLP body. Each yielded value can therefore
-be posted directly to the corresponding OTLP/HTTP endpoint.
-
-## CLI
-
-Export all trace pages as one OTLP body:
-
-```bash
-aex otel <session-id> --signal traces --json > traces.otlp.json
-curl -H 'content-type: application/json' \
-  --data-binary @traces.otlp.json \
-  http://localhost:4318/v1/traces
-```
-
-Use `--signal logs` for an `ExportLogsServiceRequest`. Without `--json`, the
-same body is printed with indentation for reading. A local OpenTelemetry
-Collector can forward these requests to Jaeger or another compatible backend.
-
-## Data boundary
-
-Only customer-visible, public-safe attributes are projected. Arbitrary event
-payload fields, prompts, credentials, private provider metadata, URLs, and
-operational details do not become telemetry attributes. Trace and span IDs on
-the event envelope let this external projection correlate with the same turn
-without exposing a private journal contract.
-
-The OpenTelemetry `gen_ai.*` semantic conventions are pre-1.0 and may evolve.
-aex keeps its documented public projection stable, while a future release may
-adopt renamed upstream attributes through the normal versioned release process.

package/docs/testing.md

@@ -1,35 +0,0 @@
----
-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` and `AEX_API_KEY`. Model access uses the managed
-gateway; no customer provider key is part of test configuration.

package/docs/vision-skills.md

@@ -1,94 +0,0 @@
----
-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 `model` slug selects the reasoning
-model for the session; if a skill needs image understanding mid-session, ship a
-skill that calls the vision API with normal HTTP and pass that API's key as a
-runtime secret. (That key is yours and unrelated to model access — aex serves the
-session's own model through its managed gateway.)
-
-The runnable example lives at [`vision-skill/` in aexhq/examples](https://github.com/aexhq/examples/tree/main/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 session
-
-```ts
-import { Aex, Secret, Skill } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-const result = await aex.start({
-  model: "anthropic/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"]
-    }
-  },
-});
-
-console.log(result.sessionId, result.text);
-```
-
-`Skill.fromDir("./vision-skill", ...)` is resolved relative to the process
-CWD. Run the script from the directory that contains `vision-skill/` (the
-root of the examples repo).
-
-## Call the provider from the skill
-
-Inside the session, 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.

package/docs/webhooks.md

@@ -1,143 +0,0 @@
----
-title: Webhooks
----
-
-# Webhooks
-
-aex can notify your endpoint whenever a run finishes. Register the callback on a
-session and the platform delivers one run-scoped event after each run finalizes:
-`run.finished` for AG-UI `RUN_FINISHED`, or `run.error` for `RUN_ERROR`. Sending
-another message on the same session produces another independently identifiable
-delivery.
-
-## Register a callback
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-
-const session = await aex.sessions.create({
-  model: "anthropic/claude-haiku-4-5",
-  webhook: { url: "https://hooks.example.com/aex" },
-});
-```
-
-```bash
-aex start \
-  --api-key "$AEX_API_KEY" \
-  --model anthropic/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
-
-Each finalized run produces one frozen CloudEvents envelope. A successful
-`run.finished` delivery is sent only after its checkpoint and session-file
-revision are committed and the session read model is consistent. A `run.error`
-delivery represents the corresponding finalized `RUN_ERROR`; `checkpoint` is
-present only when that run committed one. Retries and manual redelivery resend
-the same bytes and `webhook-id`.
-
-```json
-{
-  "specversion": "1.0",
-  "id": "whd_run_01J...",
-  "source": "aex",
-  "type": "run.finished",
-  "subject": "run_01J...",
-  "time": "2026-07-02T12:34:56.000Z",
-  "data": {
-    "sessionId": "session_01J...",
-    "runId": "run_01J...",
-    "turnSeq": 3,
-    "outcome": "succeeded",
-    "terminalAt": "2026-07-02T12:34:56.000Z",
-    "checkpoint": {
-      "checkpointId": "checkpoint_01J...",
-      "runId": "run_01J...",
-      "turnSeq": 3,
-      "committedAt": "2026-07-02T12:34:55.900Z",
-      "throughSeq": 4097
-    },
-    "reason": null,
-    "failureClass": null,
-    "costTelemetry": { "billedCostUsd": 0.42 }
-  }
-}
-```
-
-`subject` and `data.runId` identify the run; `data.sessionId` identifies the
-resumable thread. `outcome` is the terminal run outcome. `reason` and
-`failureClass` carry failure detail for `run.error`; `checkpoint` and
-`costTelemetry` are included when available.
-
-## 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 for that run 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-key "$AEX_API_KEY"   # 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 session keeps a ledger with one row per finalized run, including its
-`runId`, `turnSeq`, event type, 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-key "$AEX_API_KEY"
-```
-
-Redelivery re-sends that run's frozen payload with the **same** `webhook-id`, so
-a consumer that dedupes on `webhook-id` handles retries, redeliveries, and
-at-least-once delivery uniformly. Different runs have different delivery IDs.
-An empty ledger means the session carried no `webhook` or no run has finalized
-yet.
-
-For the terminal-event mechanics behind delivery timing, see
-[Events](events.md).