@aexhq/sdk 0.55.0 → 0.56.0

package/README.md

@@ -13,12 +13,28 @@ const session = await aex.sessions.create({
   },
 });
 
-const result = await session.output(
-  z.object({ answer: z.string() }),
-  "Answer the question.",
-);
+const result = await session.send("Answer the question.", {
+  output: z.object({ answer: z.string() }),
+});
+```
+
+`send()` returns text by default. Passing `output` returns a normal typed Promise and uses
+`https://api.aex.dev` by default. Zod schemas must be representable as JSON Schema; process-local
+custom refinements and transforms fail before any model work is admitted.
+
+Sessions start with no model tools. Configure the exact capabilities at creation:
+
+```ts
+import { bash, edit, read, subagents, write } from "@aexhq/tools";
+
+const session = await aex.sessions.create({
+  model: {
+    provider: "anthropic",
+    name: "claude-sonnet-5",
+    apiKey: "sk-ant-...",
+  },
+  tools: [bash(), read(), write(), edit(), subagents()],
+});
 ```
 
-`send()` returns text. `output()` returns a normal typed Promise and uses `https://api.aex.dev` by
-default. Zod schemas must be representable as JSON Schema; process-local custom refinements and
-transforms fail before any model work is admitted.
+Omitting `tools` and passing `tools: []` are equivalent.

package/dist/errors.d.ts

@@ -1,4 +1,10 @@
-import type { ApiError, ApiErrorCode, OutputValidationIssue } from "@aexhq/contracts/session";
+import type { ApiError, ApiErrorCode } from "@aexhq/brain/session";
+/** One Aex trusted-output validation failure, expressed as a JSON Pointer. */
+export interface OutputValidationIssue {
+    path: string;
+    message: string;
+    keyword?: string;
+}
 export interface AexErrorOptions {
     code?: ApiErrorCode | undefined;
     status?: number | undefined;

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 import { Sessions } from "./session.js";
 import type { Fetch } from "./transport.js";
 export { AbortError, AexError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, } from "./errors.js";
-export type { AexErrorOptions } from "./errors.js";
+export type { AexErrorOptions, OutputValidationIssue } from "./errors.js";
 export { Session, Sessions, } from "./session.js";
-export type { CreateSessionOptions, ListSessionsOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
+export type { CreateSessionOptions, ListSessionsOptions, McpServerOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
 export type { EventOptions } from "./transport.js";
+export { defineIntrinsicTool, definePreinstalledTool, defineServerTool, defineTool, } from "@aexhq/brain";
+export type { DefineIntrinsicToolOptions, DefinePreinstalledToolOptions, DefineServerToolOptions, DefineToolOptions, Tool, ToolContext, ToolHandler, } from "@aexhq/brain";
 export interface AexOptions {
     apiKey: string;
     baseUrl?: string;

package/dist/index.js

@@ -2,12 +2,13 @@ import { Sessions } from "./session.js";
 import { Transport } from "./transport.js";
 export { AbortError, AexError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, } from "./errors.js";
 export { Session, Sessions, } from "./session.js";
+export { defineIntrinsicTool, definePreinstalledTool, defineServerTool, defineTool, } from "@aexhq/brain";
 const DEFAULT_API_URL = "https://api.aex.dev";
 export class Aex {
     sessions;
     constructor(options) {
         if (options.apiKey.trim() === "")
-            throw new TypeError("AEX apiKey cannot be empty");
+            throw new TypeError("Aex apiKey cannot be empty");
         const fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
         if (fetchImplementation === undefined) {
             throw new TypeError("This runtime does not provide fetch; pass a fetch implementation to Aex");

package/dist/session.d.ts

@@ -1,7 +1,8 @@
-import type { Event, Provider, Session as SessionData, SessionState } from "@aexhq/contracts/session";
+import type { Event, Provider, Session as SessionData, SessionState } from "@aexhq/brain/session";
 import * as z from "zod";
 import type { EventOptions } from "./transport.js";
 import { Transport } from "./transport.js";
+import type { Tool } from "./tools.js";
 export type SessionInput = string;
 export interface ModelOptions {
     provider: Provider;
@@ -14,15 +15,33 @@ export interface ModelOptions {
 }
 export interface CreateSessionOptions {
     model: ModelOptions;
+    /** Omitted or empty grants no tools. A non-empty list is the exact grant. */
+    tools?: readonly Tool[];
+    /** Optional remote MCP servers discovered and sealed by Brain at session creation. */
+    mcp?: readonly McpServerOptions[];
     systemPrompt?: string;
+    hand?: {
+        enabled?: boolean;
+        env?: Record<string, string>;
+    };
     metadata?: Record<string, string>;
 }
+export interface McpServerOptions {
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+    protocol?: "auto" | "2026-07" | "legacy";
+    allowedTools?: readonly string[];
+}
 export interface RequestOptions {
     signal?: AbortSignal;
     idempotencyKey?: string;
     metadata?: Record<string, string>;
 }
-export interface OutputOptions extends RequestOptions {
+export interface OutputOptions<Schema extends z.ZodType = z.ZodType> extends RequestOptions {
+    output: Schema;
+    /** Extra attempts after the first invalid candidate. Defaults to 1; maximum 2. */
+    outputRetries?: 0 | 1 | 2;
 }
 export interface ListSessionsOptions {
     limit?: number;
@@ -66,7 +85,7 @@ export declare class Session implements SessionSummary {
     get metadata(): Readonly<Record<string, string | undefined>>;
     refresh(options?: Pick<RequestOptions, "signal">): Promise<this>;
     send(input: SessionInput, options?: RequestOptions): Promise<string>;
-    output<Schema extends z.ZodType>(schema: Schema, input?: SessionInput, options?: OutputOptions): Promise<z.output<Schema>>;
+    send<Schema extends z.ZodType>(input: SessionInput, options: OutputOptions<Schema>): Promise<z.output<Schema>>;
     events(options?: EventOptions): AsyncGenerator<Event>;
     cancel(options?: Pick<RequestOptions, "signal">): Promise<this>;
     delete(options?: Pick<RequestOptions, "signal">): Promise<void>;

package/dist/session.js

@@ -1,12 +1,17 @@
 import * as z from "zod";
-import { AbortError, OutputSchemaError, OutputValidationError, SessionError, abortError, errorFromApi, } from "./errors.js";
-import { jcsSha256, randomIdempotencyKey } from "./json.js";
+import { AbortError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, abortError, errorFromApi, } from "./errors.js";
+import { canonicalize, jcsSha256, randomIdempotencyKey } from "./json.js";
+import { compileTools } from "./tools.js";
 export class Sessions {
     #transport;
     constructor(transport) {
         this.#transport = transport;
     }
     async create(options, request = {}) {
+        const compiledTools = await compileTools(options.tools);
+        if (compiledTools.attached.size > 0) {
+            throw new TypeError("Attached-process Tools are not available through this Aex SDK revision; use the default Hand execution mode");
+        }
         const body = {
             model: {
                 provider: options.model.provider,
@@ -21,6 +26,31 @@ export class Sessions {
                     ? {}
                     : { reasoning_effort: options.model.reasoningEffort }),
             },
+            tools: {
+                items: compiledTools.items,
+                ...(options.mcp === undefined
+                    ? {}
+                    : {
+                        mcp: options.mcp.map((server) => ({
+                            name: server.name,
+                            url: server.url,
+                            ...(server.headers === undefined ? {} : { headers: server.headers }),
+                            ...(server.protocol === undefined ? {} : { protocol: server.protocol }),
+                            ...(server.allowedTools === undefined
+                                ? {}
+                                : { allowed_tools: [...server.allowedTools] }),
+                        })),
+                    }),
+            },
+            ...(compiledTools.bundles.length === 0 ? {} : { tool_bundles: compiledTools.bundles }),
+            ...(options.hand === undefined
+                ? {}
+                : {
+                    hand: {
+                        ...(options.hand.enabled === undefined ? {} : { enabled: options.hand.enabled }),
+                        ...(options.hand.env === undefined ? {} : { env: options.hand.env }),
+                    },
+                }),
             ...(options.systemPrompt === undefined ? {} : { system_prompt: options.systemPrompt }),
             ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
         };
@@ -89,15 +119,35 @@ export class Session {
         return this;
     }
     async send(input, options = {}) {
+        const outputOptions = isOutputOptions(options) ? options : undefined;
+        const compiled = outputOptions === undefined
+            ? undefined
+            : await compileOutputSchema(outputOptions.output, outputOptions.outputRetries);
         const accepted = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/messages`, {
             body: {
                 content: input,
                 ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+                ...(compiled === undefined
+                    ? {}
+                    : {
+                        output: {
+                            schema: compiled.jsonSchema,
+                            schema_hash: compiled.schemaHash,
+                            ...(compiled.retries === undefined ? {} : { retries: compiled.retries }),
+                        },
+                    }),
             },
             headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
             signal: options.signal,
             retry: true,
         });
+        if (compiled !== undefined) {
+            if (accepted.session_id !== this.id ||
+                accepted.output_id === undefined ||
+                accepted.schema_hash !== compiled.schemaHash) {
+                throw new SessionError("Aex returned an inconsistent typed-output admission");
+            }
+        }
         let answer = "";
         try {
             for await (const event of this.events({ after: Math.max(0, accepted.seq - 1), signal: options.signal })) {
@@ -105,79 +155,39 @@ export class Session {
                     answer = event.text;
                 }
                 else if (event.type === "turn.failed" && event.turn_id === accepted.turn_id) {
-                    throw errorFromApi(event.error);
+                    throw errorFromApi(event.error, undefined, outputIssues(event.error));
                 }
                 else if (event.type === "turn.completed" && event.turn_id === accepted.turn_id) {
                     this.markIdle();
                     if (event.stop_reason === "cancelled")
                         throw new AbortError();
-                    return answer;
-                }
-            }
-        }
-        catch (error) {
-            if (options.signal?.aborted === true)
-                throw abortError(error);
-            throw error;
-        }
-        throw new SessionError("The AEX event stream ended before the session finished its work");
-    }
-    async output(schema, input, options = {}) {
-        let jsonSchema;
-        try {
-            assertPortableOutputSchema(schema);
-            jsonSchema = z.toJSONSchema(schema, {
-                target: "draft-2020-12",
-                unrepresentable: "throw",
-            });
-        }
-        catch (cause) {
-            throw new OutputSchemaError(messageOf(cause, "The Zod schema cannot be represented as JSON Schema"), {
-                cause,
-            });
-        }
-        if (jsonSchema.type !== "object") {
-            throw new OutputSchemaError("session.output() requires a Zod object schema");
-        }
-        const schemaHash = await jcsSha256(jsonSchema);
-        const body = {
-            schema: jsonSchema,
-            schema_hash: schemaHash,
-            ...(input === undefined ? {} : { input }),
-            ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
-        };
-        const accepted = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/output`, {
-            body,
-            headers: { "Idempotency-Key": options.idempotencyKey ?? randomIdempotencyKey() },
-            signal: options.signal,
-            retry: true,
-        });
-        if (accepted.session_id !== this.id || accepted.schema_hash !== schemaHash) {
-            throw new SessionError("AEX returned an inconsistent output admission");
-        }
-        try {
-            for await (const event of this.events({ after: Math.max(0, accepted.seq - 1), signal: options.signal })) {
-                if (event.type === "output.failed" && event.output_id === accepted.output_id) {
-                    if (event.schema_hash !== schemaHash) {
-                        throw new SessionError("AEX returned an output failure for a different schema");
+                    if (compiled !== undefined && outputOptions !== undefined) {
+                        if (event.result === undefined) {
+                            if (event.stop_reason === "refusal") {
+                                throw new OutputRefusalError("The model refused the structured-output request");
+                            }
+                            throw new OutputValidationError("The model ended the turn without submitting the requested structured output", [{
+                                    path: "",
+                                    message: "The model did not call aex_submit_output",
+                                    keyword: "missing_output",
+                                }]);
+                        }
+                        if (event.result.name !== "aex_submit_output" ||
+                            event.result.metadata?.output_id !== accepted.output_id ||
+                            event.result.metadata?.schema_hash !== compiled.schemaHash) {
+                            throw new SessionError("Aex returned a typed result for a different request");
+                        }
+                        const parsed = await outputOptions.output.safeParseAsync(event.result.value);
+                        if (!parsed.success) {
+                            throw new OutputValidationError("The output passed the wire schema but failed the original Zod schema", parsed.error.issues.map((issue) => ({
+                                path: jsonPointer(issue.path),
+                                message: issue.message,
+                                keyword: issue.code,
+                            })));
+                        }
+                        return parsed.data;
                     }
-                    this.markIdle();
-                    throw outputEventError(event.error, event.issues);
-                }
-                if (event.type === "output.completed" && event.output_id === accepted.output_id) {
-                    if (event.output.schema_hash !== schemaHash) {
-                        throw new SessionError("AEX returned an output value for a different schema");
-                    }
-                    this.markIdle();
-                    const parsed = await schema.safeParseAsync(event.output.value);
-                    if (!parsed.success) {
-                        throw new OutputValidationError("The output passed the wire schema but failed the original Zod schema", parsed.error.issues.map((issue) => ({
-                            path: jsonPointer(issue.path),
-                            message: issue.message,
-                            keyword: issue.code,
-                        })));
-                    }
-                    return parsed.data;
+                    return answer;
                 }
             }
         }
@@ -188,7 +198,7 @@ export class Session {
             }
             throw error;
         }
-        throw new SessionError("The AEX event stream ended before the typed output completed");
+        throw new SessionError("The Aex event stream ended before the session finished its work");
     }
     events(options = {}) {
         return this.#transport.events(this.id, options);
@@ -207,8 +217,82 @@ export class Session {
         this.#data = { ...this.#data, state: "idle" };
     }
 }
-function outputEventError(error, issues) {
-    return errorFromApi(error, undefined, issues ?? []);
+function isOutputOptions(options) {
+    return "output" in options;
+}
+async function compileOutputSchema(schema, retries) {
+    let jsonSchema;
+    try {
+        assertPortableOutputSchema(schema);
+        jsonSchema = z.toJSONSchema(schema, {
+            target: "draft-2020-12",
+            unrepresentable: "throw",
+        });
+    }
+    catch (cause) {
+        throw new OutputSchemaError(messageOf(cause, "The Zod schema cannot be represented as JSON Schema"), {
+            cause,
+        });
+    }
+    if (jsonSchema.type !== "object") {
+        throw new OutputSchemaError("session.send() output requires a Zod object schema");
+    }
+    assertSupportedJsonSchema(jsonSchema);
+    return { jsonSchema, schemaHash: await jcsSha256(jsonSchema), retries };
+}
+function assertSupportedJsonSchema(schema) {
+    const bytes = new TextEncoder().encode(canonicalize(schema));
+    if (bytes.byteLength > 64 * 1024) {
+        throw new OutputSchemaError("The output schema exceeds the 65536-byte service limit");
+    }
+    let nodes = 0;
+    const visit = (value, depth) => {
+        if (depth > 64)
+            throw new OutputSchemaError("The output schema exceeds the service depth limit");
+        nodes += 1;
+        if (nodes > 4096)
+            throw new OutputSchemaError("The output schema exceeds the service node limit");
+        if (Array.isArray(value)) {
+            for (const child of value)
+                visit(child, depth + 1);
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        const object = value;
+        if ("pattern" in object || "patternProperties" in object) {
+            throw new OutputSchemaError("Regular-expression JSON Schema keywords are not supported for Aex structured output");
+        }
+        for (const keyword of ["$ref", "$dynamicRef", "$recursiveRef"]) {
+            const reference = object[keyword];
+            if (typeof reference === "string" && !reference.startsWith("#")) {
+                throw new OutputSchemaError("Remote JSON Schema references are not supported for Aex structured output");
+            }
+        }
+        for (const child of Object.values(object))
+            visit(child, depth + 1);
+    };
+    visit(schema, 0);
+}
+function outputIssues(error) {
+    const details = error.details;
+    if (details === undefined || details === null || typeof details !== "object")
+        return [];
+    const issues = details.issues;
+    if (!Array.isArray(issues))
+        return [];
+    return issues.flatMap((issue) => {
+        if (issue === null || typeof issue !== "object")
+            return [];
+        const value = issue;
+        if (typeof value.path !== "string" || typeof value.message !== "string")
+            return [];
+        return [{
+                path: value.path,
+                message: value.message,
+                ...(typeof value.keyword === "string" ? { keyword: value.keyword } : {}),
+            }];
+    });
 }
 function jsonPointer(path) {
     if (path.length === 0)
@@ -238,7 +322,7 @@ function assertPortableOutputSchema(schema) {
                 definition.type === "file" ||
                 definition.check === "overwrite";
             if (unsupported) {
-                throw new OutputSchemaError(`This Zod schema contains ${String(definition.type ?? definition.check)} behavior that cannot be enforced by the AEX output service`);
+                throw new OutputSchemaError(`This Zod schema contains ${String(definition.type ?? definition.check)} behavior that cannot be enforced by the Aex output service`);
             }
             visit(definition);
             return;

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+export { compileTools } from "@aexhq/brain";
+export type { CompiledTools, Tool } from "@aexhq/brain";

package/dist/tools.js

@@ -0,0 +1 @@
+export { compileTools } from "@aexhq/brain";

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import type { Event } from "@aexhq/contracts/session";
+import type { Event } from "@aexhq/brain/session";
 export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 interface JsonRequestOptions {
     body?: unknown;

package/dist/transport.js

@@ -41,7 +41,7 @@ export class Transport {
                 lastError = error;
             }
         }
-        throw new SessionError("Could not reach the AEX API", { cause: lastError });
+        throw new SessionError("Could not reach the Aex API", { cause: lastError });
     }
     async *events(sessionId, options = {}) {
         let cursor = options.after ?? 0;
@@ -62,7 +62,7 @@ export class Transport {
                 if (!response.ok)
                     throw await this.responseError(response);
                 if (response.body === null)
-                    throw new SessionError("The AEX event stream had no body");
+                    throw new SessionError("The Aex event stream had no body");
                 let received = false;
                 for await (const event of parseEventStream(response.body)) {
                     if (event.seq <= cursor)
@@ -86,7 +86,7 @@ export class Transport {
                 if (consecutiveFailures > 5) {
                     if (error instanceof AexError)
                         throw error;
-                    throw new SessionError("The AEX event stream disconnected", { cause: error });
+                    throw new SessionError("The Aex event stream disconnected", { cause: error });
                 }
             }
             await delay(Math.min(2_000, 100 * 2 ** (consecutiveFailures - 1)), options.signal);
@@ -102,7 +102,7 @@ export class Transport {
         }
         if (envelope?.error !== undefined)
             return errorFromApi(envelope.error, response.status);
-        return new SessionError(`AEX API request failed with HTTP ${response.status}`, {
+        return new SessionError(`Aex API request failed with HTTP ${response.status}`, {
             status: response.status,
             requestId: response.headers.get("x-request-id") ?? undefined,
         });
@@ -124,7 +124,7 @@ async function* parseEventStream(stream) {
             return JSON.parse(data);
         }
         catch (cause) {
-            throw new SessionError("AEX sent an invalid event", { cause });
+            throw new SessionError("Aex sent an invalid event", { cause });
         }
     };
     const line = (raw) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.55.0",
-  "description": "TypeScript SDK for AEX sessions",
+  "version": "0.56.0",
+  "description": "TypeScript SDK for Aex sessions",
   "license": "Apache-2.0",
   "homepage": "https://aex.dev",
   "repository": {
@@ -33,13 +33,13 @@
     "test": "tsc -p tsconfig.json && node --test"
   },
   "dependencies": {
-    "@aexhq/contracts": "0.26.0"
+    "@aexhq/brain": "0.1.0"
   },
   "peerDependencies": {
-    "zod": "^4.0.0"
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "typescript": "^5.9.2",
-    "zod": "^4.0.0"
+    "zod": "4.4.3"
   }
 }