@aexhq/sdk 0.83.0 → 0.84.1

package/README.md

@@ -8,7 +8,7 @@ tools, send messages, and read saved conversations without operating a Brain ser
 Create a key in the [dashboard](https://aex.dev/dashboard). With Node.js 22 or newer, install:
 
 ```sh
-npm install @aexhq/sdk@0.83.0 @aexhq/agentloop-pi@7.2.1 zod@4
+npm install @aexhq/sdk@0.84.1 @aexhq/agentloop-pi@7.2.3 zod@4.4.3
 ```
 
 Set `AEX_API_KEY` and `OPENAI_API_KEY` in your server environment. Save as `order.mjs` and
@@ -56,13 +56,85 @@ The SDK uses Brain's session API and extension helpers. You can import `tool`, `
 
 - [Sessions](https://aex.dev/brain/docs/concepts/sessions): send, submit, stream, reconnect and stop.
 - [Tools](https://aex.dev/brain/docs/guides/write-a-tool): application functions and packaged tools.
-- [Structured output](https://aex.dev/brain/docs/guides/structured-output): validated JSON answers.
+- [Structured output](#structured-output): validated JSON answers.
 - [Managed environments](https://github.com/aexhq/aex/blob/main/docs/environments.md): hosted tools and workspaces.
 - [Attachments](https://github.com/aexhq/aex/blob/main/docs/attachments.md): upload images and PDFs.
 
 Use `ctx.finish(value)` to complete a tool. Use `aex.close()` in `finally` to close client
 connections. Closing the client keeps stored sessions; tools in your process still require it.
 
+## Structured output
+
+Ask for a typed application answer on one send. Before ending the session, pass a Zod
+schema alongside the message:
+
+```ts
+const answer = await session.send("Return the order status", {
+  output: { type: z.object({ id: z.string(), status: z.string() }), maxRetries: 2 },
+});
+console.log(answer.status);
+```
+
+Aex adds schema instructions to the prompt, reads that completed turn's assistant output,
+parses JSON and validates it locally. The result has the schema's inferred output type.
+Ordinary sends still return session state. The
+[executable example](../../examples/structured-output.mjs) shows a complete session;
+the [hosted guide](https://aex.dev/docs#structured-output) describes the same contract.
+
+`maxRetries` counts additional correction turns and defaults to two. Zero validates one
+candidate. Invalid JSON or Zod issues produce a follow-up asking for a complete corrected
+answer. Fences and surrounding prose fail parsing. Normal Zod semantics apply: ordinary
+objects strip unknown properties, strict objects reject them, and defaults, transforms and
+async refinements run locally. The prompt describes the input shape; the returned value is
+the parsed output. Unrepresentable schemas fail before sending, and custom-validator
+exceptions propagate without corrections.
+
+Exhaustion throws `StructuredOutputError` with `attempts`, `lastOutput` and `issues`.
+Provider, transport, failed-turn and unsupported-output errors do not trigger corrections.
+The loop must emit an Agentloop-origin `output_emitted` assistant message, as Pi and Codex do.
+Aex reads the last such message within the exact completed turn, including idempotent
+receipts from earlier history. It does not scrape internal model calls or infer refusals
+from arbitrary text. No provider response format is set or cleared; avoid conflicting
+session-level `responseFormat` settings.
+
+Each attempt is an ordinary durable turn and can invoke Tools. Asking the agent not to
+repeat actions is not enforcement. The caller must remain alive; rejected answers stay in
+history and streams, and local validation failure does not rewrite a completed server turn.
+Use exclusive ownership of sends during a typed operation. Overlapping send/submit calls
+on the same wrapper fail; other handles and processes need application coordination.
+An optional top-level `signal` cancels the active turn, aborts event reads and stops further
+corrections. Async validators finish before their result is checked for cancellation.
+
+The initial turn uses the supplied `idempotencyKey`; corrections use distinct derived keys.
+Re-entry reuses completed turns when prompts and validation feedback are identical. This
+is not an atomic server operation; nondeterministic validation can conflict on replay.
+
+For work submitted by a short-lived caller, configure the official Agentloop with
+`output: { schema: z.toJSONSchema(answerType), maxCorrections: 2 }` and use `submit()`.
+That separate extension policy validates inside the hosted turn and prohibits Tools during
+correction. It supports JSON Schema, not arbitrary local Zod refinements or transforms.
+
+### Migrating from Brain SDK typed sends
+
+Brain SDK 0.34 removes typed sends and the corresponding types and errors. Aex SDK 0.84
+owns them. Existing Aex `send(..., { output })` calls keep the same syntax and behavior.
+Import `StructuredSendOptions` and `StructuredOutputError` from `@aexhq/sdk`.
+Use Pi/Codex 7.2.3 and extension packages pinned to Brain 0.34 with this SDK.
+Mixing exact Brain dependency versions creates different TypeScript extension brands.
+
+An existing standalone Brain handle can use Aex's policy without changing servers:
+
+```ts
+import { AexSessionHandle } from "@aexhq/sdk";
+const session = new AexSessionHandle(await brain.sessions.get(sessionId));
+```
+
+`Aex` and `AexSessionHandle` use composition, so they are not instances of the upstream
+`Brain` and `SessionHandle` classes. Use `AexSessionHandle` for explicit product-handle
+annotations. Neutral Brain classes and extension helpers are still re-exported with their
+original identities; `withToken()` still returns a raw Brain client. Stored sessions,
+server contracts, native model formats and Tool schemas are unchanged.
+
 ## Account and usage
 
 ```js

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export * from "@aexhq/brain";
 export type * from "./generated.js";
+export { AexSessionHandle } from "./session.js";
+export { StructuredOutputError } from "./structured-output.js";
+export type { StructuredSendOptions } from "./structured-output.js";
 import { Brain, type BrainOptions } from "@aexhq/brain";
+import { AexSessionHandle } from "./session.js";
 import type { EnvironmentCatalog, TokenUsage } from "./generated.js";
 import type { Attachment, Account, Usage, ApiKey, IssuedKey, KeyInput, LoginGrantInput, LoginGrant, LoginExchange, AccountSession, Wallet, BillingSettings, LedgerPage, Topup, TopupInput, Refund, RefundInput, SyncPayment } from "./generated.js";
 export type AexConnection = Omit<BrainOptions, "token" | "baseUrl"> & {
@@ -15,11 +19,28 @@ export type AexOptions = AexConnection & {
     accountToken: string;
     apiKey?: never;
 });
-export declare class Aex extends Brain {
-    private readonly maxCostMicroUsd?;
+export declare class Aex {
+    private readonly client;
     constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }: AexOptions);
-    /** Resource and legacy turn reservations use this ceiling; token hosting follows the account limit. */
-    request<T>(method: string, path: string, body?: unknown, idempotencyKey?: string, contentType?: string, signal?: AbortSignal, extraHeaders?: HeadersInit): Promise<T>;
+    get baseUrl(): string;
+    readonly sessions: Readonly<{
+        create: (options: import("@aexhq/brain").CreateSessionOptions, operation?: import("@aexhq/brain").OperationOptions | undefined) => Promise<AexSessionHandle>;
+        get: (sessionId: string, options?: {
+            tools?: readonly import("@aexhq/brain").PlacedTool[];
+        } | undefined) => Promise<AexSessionHandle>;
+        list: () => ReturnType<Brain["sessions"]["list"]>;
+    }>;
+    request<T>(...args: Parameters<Brain["request"]>): Promise<T>;
+    withToken(...args: Parameters<Brain["withToken"]>): ReturnType<Brain["withToken"]>;
+    close(): ReturnType<Brain["close"]>;
+    models(...args: Parameters<Brain["models"]>): ReturnType<Brain["models"]>;
+    stream(...args: Parameters<Brain["stream"]>): ReturnType<Brain["stream"]>;
+    streamPath(...args: Parameters<Brain["streamPath"]>): ReturnType<Brain["streamPath"]>;
+    admit(...args: Parameters<Brain["admit"]>): ReturnType<Brain["admit"]>;
+    admitAgentloop(...args: Parameters<Brain["admitAgentloop"]>): ReturnType<Brain["admitAgentloop"]>;
+    admitTool(...args: Parameters<Brain["admitTool"]>): ReturnType<Brain["admitTool"]>;
+    register(): ReturnType<Brain["register"]>;
+    credentials(): ReturnType<Brain["credentials"]>;
     static exchangeLogin(input: LoginExchange, options?: AexConnection): Promise<AccountSession>;
     readonly attachments: {
         limits: () => Promise<import("./generated.js").AttachmentLimits>;

package/dist/index.js

@@ -1,15 +1,16 @@
 export * from "@aexhq/brain";
+export { AexSessionHandle } from "./session.js";
+export { StructuredOutputError } from "./structured-output.js";
 import { Brain } from "@aexhq/brain";
+import { AexSessionHandle } from "./session.js";
 function nonnegativeInteger(value, name) {
     if (!Number.isSafeInteger(value) || value < 0)
         throw new TypeError(`${name} must be a nonnegative safe integer`);
 }
-export class Aex extends Brain {
+class HostedBrain extends Brain {
     maxCostMicroUsd;
-    constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }) {
-        if (!(apiKey || accountToken) || (apiKey && accountToken))
-            throw new TypeError("one apiKey or accountToken is required");
-        super({ baseUrl: "https://api.aex.dev", ...options, token: apiKey ?? accountToken });
+    constructor({ maxCostMicroUsd, ...options }) {
+        super(options);
         if (maxCostMicroUsd !== undefined)
             nonnegativeInteger(maxCostMicroUsd, "maxCostMicroUsd");
         this.maxCostMicroUsd = maxCostMicroUsd;
@@ -21,6 +22,31 @@ export class Aex extends Brain {
             headers.set("x-aex-max-cost-micro-usd", String(this.maxCostMicroUsd));
         return super.request(method, path, body, idempotencyKey, contentType, signal, headers);
     }
+}
+export class Aex {
+    client;
+    constructor({ apiKey, accountToken, maxCostMicroUsd, ...options }) {
+        if (!(apiKey || accountToken) || (apiKey && accountToken))
+            throw new TypeError("one apiKey or accountToken is required");
+        this.client = new HostedBrain({ baseUrl: "https://api.aex.dev", ...options, token: apiKey ?? accountToken, maxCostMicroUsd });
+    }
+    get baseUrl() { return this.client.baseUrl; }
+    sessions = Object.freeze({
+        create: async (...args) => new AexSessionHandle(await this.client.sessions.create(...args)),
+        get: async (...args) => new AexSessionHandle(await this.client.sessions.get(...args)),
+        list: () => this.client.sessions.list(),
+    });
+    request(...args) { return this.client.request(...args); }
+    withToken(...args) { return this.client.withToken(...args); }
+    close() { return this.client.close(); }
+    models(...args) { return this.client.models(...args); }
+    stream(...args) { return this.client.stream(...args); }
+    streamPath(...args) { return this.client.streamPath(...args); }
+    admit(...args) { return this.client.admit(...args); }
+    admitAgentloop(...args) { return this.client.admitAgentloop(...args); }
+    admitTool(...args) { return this.client.admitTool(...args); }
+    register() { return this.client.register(); }
+    credentials() { return this.client.credentials(); }
     static exchangeLogin(input, options = {}) {
         return new Brain({ baseUrl: "https://api.aex.dev", ...options }).request("POST", "/v1/auth/exchange", input);
     }

package/dist/session.d.ts

@@ -0,0 +1,22 @@
+import type { SessionHandle, SessionState, Schema, SchemaOutput, SendOptions, UserInput } from "@aexhq/brain";
+import { type StructuredSendOptions } from "./structured-output.js";
+export declare class AexSessionHandle {
+    private readonly session;
+    private activeSends;
+    private structuredSend;
+    constructor(session: SessionHandle);
+    get id(): string;
+    get state(): SessionState;
+    set state(value: SessionState);
+    get environments(): SessionHandle["environments"];
+    submit(...args: Parameters<SessionHandle["submit"]>): Promise<number>;
+    send<S extends Schema>(input: UserInput | string, operation: StructuredSendOptions<S>): Promise<SchemaOutput<S>>;
+    send(input: UserInput | string, operation?: SendOptions): Promise<SessionState>;
+    transcript(): ReturnType<SessionHandle["transcript"]>;
+    outcome(...args: Parameters<SessionHandle["outcome"]>): ReturnType<SessionHandle["outcome"]>;
+    events(...args: Parameters<SessionHandle["events"]>): ReturnType<SessionHandle["events"]>;
+    stream(...args: Parameters<SessionHandle["stream"]>): ReturnType<SessionHandle["stream"]>;
+    interrupt(...args: Parameters<SessionHandle["interrupt"]>): ReturnType<SessionHandle["interrupt"]>;
+    end(...args: Parameters<SessionHandle["end"]>): ReturnType<SessionHandle["end"]>;
+    delete(...args: Parameters<SessionHandle["delete"]>): ReturnType<SessionHandle["delete"]>;
+}

package/dist/session.js

@@ -0,0 +1,47 @@
+import { structuredOutput } from "./structured-output.js";
+export class AexSessionHandle {
+    session;
+    activeSends = 0;
+    structuredSend = false;
+    constructor(session) {
+        this.session = session;
+    }
+    get id() { return this.session.id; }
+    get state() { return this.session.state; }
+    set state(value) { this.session.state = value; }
+    get environments() { return this.session.environments; }
+    async submit(...args) {
+        if (args[1] !== undefined && "output" in args[1])
+            throw new TypeError("submit requires structured output to run in the hosted Agentloop");
+        if (this.structuredSend)
+            throw new Error("structured output requires exclusive sends on this session handle");
+        return this.session.submit(...args);
+    }
+    async send(input, operation = {}) {
+        const normalized = typeof input === "string" ? { message: input } : input;
+        if (typeof normalized?.message !== "string" || normalized.message === "")
+            throw new TypeError("send needs a non-empty message");
+        const output = "output" in operation ? operation.output : undefined;
+        if (this.structuredSend || (output !== undefined && this.activeSends !== 0))
+            throw new Error("structured output requires exclusive sends on this session handle");
+        this.activeSends++;
+        this.structuredSend = output !== undefined;
+        const options = { signal: operation.signal, idempotencyKey: operation.idempotencyKey };
+        try {
+            if (output === undefined)
+                return await this.session.send(normalized, options);
+            return await structuredOutput(normalized, { ...options, output }, options.idempotencyKey ?? crypto.randomUUID(), (message, sendOptions) => this.session.send(message, sendOptions), (after) => this.events(after, options.signal), () => this.state.lastSequence);
+        }
+        finally {
+            this.activeSends--;
+            this.structuredSend = false;
+        }
+    }
+    transcript() { return this.session.transcript(); }
+    outcome(...args) { return this.session.outcome(...args); }
+    events(...args) { return this.session.events(...args); }
+    stream(...args) { return this.session.stream(...args); }
+    interrupt(...args) { return this.session.interrupt(...args); }
+    end(...args) { return this.session.end(...args); }
+    delete(...args) { return this.session.delete(...args); }
+}

package/dist/structured-output.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { Schema, SchemaOutput, SendOptions, SessionEvent, SessionState, UserInput } from "@aexhq/brain";
+export interface StructuredSendOptions<S extends Schema> extends SendOptions {
+    readonly output: {
+        readonly type: S;
+        /** Additional correction turns after the first answer. Default 2; zero disables retries. */
+        readonly maxRetries?: number;
+    };
+}
+export declare class StructuredOutputError extends Error {
+    readonly attempts: number;
+    readonly lastOutput: string;
+    readonly issues: readonly z.core.$ZodIssue[];
+    readonly name = "StructuredOutputError";
+    constructor(attempts: number, lastOutput: string, issues: readonly z.core.$ZodIssue[]);
+}
+export declare function structuredOutput<S extends Schema>(input: UserInput, options: StructuredSendOptions<S>, key: string, send: (input: UserInput, options: SendOptions) => Promise<SessionState>, events: (after: number) => AsyncIterable<SessionEvent>, sequence: () => number): Promise<SchemaOutput<S>>;

package/dist/structured-output.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+export class StructuredOutputError extends Error {
+    attempts;
+    lastOutput;
+    issues;
+    name = "StructuredOutputError";
+    constructor(attempts, lastOutput, issues) {
+        super(`Structured output did not match the schema after ${attempts} attempt${attempts === 1 ? "" : "s"}`);
+        this.attempts = attempts;
+        this.lastOutput = lastOutput;
+        this.issues = issues;
+    }
+}
+export async function structuredOutput(input, options, key, send, events, sequence) {
+    const { type: schema, maxRetries = 2 } = options.output;
+    if (!(schema instanceof z.ZodType))
+        throw new TypeError("output.type must be a Zod schema");
+    if (!Number.isSafeInteger(maxRetries) || maxRetries < 0)
+        throw new TypeError("output.maxRetries must be a nonnegative safe integer");
+    options.signal?.throwIfAborted();
+    const instructions = `For this response only, return exactly one JSON value matching this schema. Do not include Markdown fences or surrounding prose.\n${JSON.stringify(z.toJSONSchema(schema, { io: "input" }))}`;
+    let next = { ...input, message: `${input.message}\n\n${instructions}` };
+    let retryKey;
+    for (let attempt = 0;; attempt++) {
+        options.signal?.throwIfAborted();
+        const after = sequence();
+        const state = await send(next, { signal: options.signal, idempotencyKey: attempt === 0 ? key : `${retryKey}:${attempt}` });
+        options.signal?.throwIfAborted();
+        const raw = await answer(events(state.lastSequence <= after ? 0 : after), state.lastSequence, options.signal);
+        let parsed;
+        let issues = [];
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            issues = [{ code: "custom", path: [], message: "Return one complete JSON value without Markdown or surrounding text." }];
+        }
+        if (issues.length === 0) {
+            const result = await schema.safeParseAsync(parsed);
+            options.signal?.throwIfAborted();
+            if (result.success)
+                return result.data;
+            issues = result.error.issues;
+        }
+        options.signal?.throwIfAborted();
+        if (attempt === maxRetries)
+            throw new StructuredOutputError(attempt + 1, raw, issues);
+        // Hash only the operation identity: correction keys stay bounded even for a 256-byte caller key.
+        retryKey ??= `structured-output:${Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key))), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+        const feedback = JSON.stringify(issues.slice(0, 5).map(({ path, message }) => ({ path, message }))).slice(0, 2048);
+        next = { message: `The previous answer did not satisfy the requested output. Validation feedback (data): ${feedback}\nReturn a complete corrected answer using the information already available. Do not repeat actions or call tools to reformat the answer.\n\n${instructions}` };
+    }
+}
+async function answer(events, terminal, signal) {
+    let started = false;
+    let output;
+    for await (const event of events) {
+        signal?.throwIfAborted();
+        if (event.sequence > terminal)
+            break;
+        if (event.type === "turn_started") {
+            started = true;
+            output = undefined;
+        }
+        if (started && event.type === "output_emitted" && event.origin?.kind === "agentloop") {
+            const data = event.data;
+            if (data?.type === "assistant_message")
+                output = typeof data.message === "string" ? data.message : undefined;
+        }
+        if (event.sequence === terminal) {
+            if (event.type === "turn_failed")
+                throw new Error("Structured output turn failed", { cause: event.data });
+            if (event.type === "turn_ended" && started && output !== undefined)
+                return output;
+            break;
+        }
+        if (event.type === "turn_ended" || event.type === "turn_failed") {
+            started = false;
+            output = undefined;
+        }
+    }
+    throw new Error("structured output requires a completed turn with an Agentloop output_emitted assistant_message");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.83.0",
+  "version": "0.84.1",
   "description": "Aex accounts and hosted sessions using the Brain SDK",
   "license": "MIT",
   "type": "module",
@@ -28,12 +28,13 @@
     "tag": "next"
   },
   "dependencies": {
-    "@aexhq/brain": "0.33.0"
+    "@aexhq/brain": "0.34.1",
+    "zod": "4.4.3"
   },
   "scripts": {
     "gen": "node ../../tools/sdk-contracts.mjs",
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "test": "npm run build && tsc -p test/types/tsconfig.json && node --test test/*.test.mjs",
     "prepack": "npm run build"
   }
 }