@aexhq/sdk 0.57.5 → 0.59.0

package/README.md

@@ -1,105 +1,63 @@
-# `@aexhq/sdk`
+# @aexhq/sdk
 
-TypeScript client for durable Aex sessions.
+TypeScript SDK for Aex sessions and tool extensions.
 
 ```ts
-import { Aex, tool } from "@aexhq/sdk";
-import { z } from "zod";
+import { Aex } from "@aexhq/sdk";
+import { awsMicrovm } from "@aexhq/env-aws-microvm";
+import { pi } from "@aexhq/loop-pi";
+import { openai } from "@aexhq/model-openai";
+import { bash, read, task, write } from "@aexhq/tools";
 
-const lookup = tool(
-  z.object({ id: z.string() }),
-  async function lookup({ id }) {
-    return database.customers.find(id);
-  },
-).client();
+const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
+const workspace = awsMicrovm();
 
-const aex = new Aex({
-  apiKey: process.env.AEX_API_KEY!,
-  client: { id: "customer-api" },
+const session = await aex.sessions.create({
+  model: {
+    component: openai(),
+    provider: "openai",
+    name: "gpt-5.4",
+    apiKey: process.env.OPENAI_API_KEY!,
+  },
+  agentloop: pi({ instructions: "Work carefully and verify changes." }),
+  environments: { workspace },
+  tools: [bash(), read(), write(), task()],
 });
-const model = {
-  provider: "openai" as const,
-  name: "gpt-5.4",
-  apiKey: process.env.OPENAI_API_KEY!,
-};
-const session = await aex.sessions.create({ model, tools: [lookup] });
 
-const result = await session.send("Answer the question.", {
-  output: z.object({ answer: z.string() }),
-});
+console.log(await session.send("Inspect the workspace."));
 ```
 
-`send()` returns text by default. Passing `output` returns a typed Promise. The client uses
-`https://api.aex.dev` by default; the model `baseUrl` is independent of the Aex API origin.
-`send()` resolves only the durable winning assistant message after provider recovery. The lower-
-level `session.events()` stream is raw and attempt-aware: provisional frames have no durable cursor
-and can later be superseded, so live renderers must key them by `attempt_id` and process
-`model.attempt_superseded` instead of concatenating attempts.
-The SDK always generates and reuses an `Idempotency-Key` for root/child creation and messages; pass
-`idempotencyKey` explicitly when the application must recover the same operation across its own
-process restart. Raw hosted REST calls must supply that header for those operations.
-
-Hosted alpha has one managed-compute shape, `1gb` (0.5 vCPU and 1 GiB), so the SDK exposes no shape
-selector. Child sessions and managed sandboxes inherit the root's physical seal.
+There is no default Agentloop, Model, Tool, or Environment. A Tool component that requests the
+Environment capability requires the session's one declared Environment in the MVP.
 
-Tools are immutable once the session is created. `.client()` keeps closures in this application;
-`.server(import.meta.url)` bundles a module whose default export is the completed Tool value for the
-session's shared managed computer. One customer-app socket is shared across sessions; call
-`aex.close()` during graceful process shutdown to stop it and interrupt process-local work. A
-closed `Aex` instance cannot create another session. The
-default `.client()` registration
-is derived from its contract. If one application intentionally has different closures with the
-same name and schemas, give each a stable `.client({ registration: "..." })`; a live runner rejects
-a registration collision instead of invoking the wrong closure. Sessions grant no execution
-capabilities by default. Add only the official capabilities needed. Aex's reserved output protocol is
-present but inert unless a particular `send({ output })` request arms it:
+## Application Tools
 
-Hosted `.server()` bindings use distinct generation-lifetime unprivileged users, separate from the
-ordinary shell, while sharing the workspace through a group. Declared environment secrets are not
-written by Aex to the workspace, arguments, results, or logs. This blocks ordinary sibling reads,
-not guest-root compromise or a Tool deliberately writing the value. Use `.client()` or an external
-service for that stronger boundary; local mode is intentionally unsandboxed.
+Application callbacks use the same Tool and Environment component ABI while the handler remains in
+your process. Declare one `app()` Environment; Aex registers each selected callback over one
+authenticated, reconnecting connection. Handler source and captured application state are never
+uploaded to Brain.
 
 ```ts
-import { bash, edit, read, sandbox, storage, subagents, write } from "@aexhq/tools";
-
-const session = await aex.sessions.create({
-  model,
-  tools: [bash(), read(), write(), edit(), storage(), sandbox(), subagents()],
-  network: { outbound: "none" },
-});
-```
-
-Omitting `tools` and passing `tools: []` are equivalent. Zod schemas must be representable as JSON
-Schema; process-local refinements and transforms fail before model work starts. Temporary files are
-available through `session.sandbox.files`; durable objects use `session.storage`. Large transfers
-automatically bypass the Brain actor. Durable direct children use `session.children`.
-Sandbox file operations honor guest permissions; they do not bypass a `.server()` binding's
-deliberate mode-0600 files. The binding must explicitly export or relax those permissions.
-
-Buffered `upload()` and `download()` are convenient for small objects. Large transfers can stay
-O(1)-heap with `downloadStream()` and a replayable declared source:
+import { Aex, tool } from "@aexhq/sdk";
+import { app } from "@aexhq/env-app";
+import { z } from "zod";
 
-```ts
-import { createReadStream } from "node:fs";
-import { Readable } from "node:stream";
+const lookupOrder = tool(
+  z.object({ orderId: z.string() }),
+  async function lookupOrder({ orderId }) {
+    return database.lookup(orderId);
+  },
+)
+  .describe("Look up an order")
+  .returns(z.object({ status: z.string() }));
 
-await session.storage.upload("inputs/archive.tar", {
-  bytes: stat.size,
-  sha256: digest,
-  stream: () => Readable.toWeb(createReadStream(filename)),
+await new Aex({ apiKey: process.env.AEX_API_KEY! }).sessions.create({
+  model,
+  agentloop,
+  environments: { application: app({ id: "orders-ui" }) },
+  tools: [lookupOrder],
 });
-const body = await session.storage.downloadStream("inputs/archive.tar");
 ```
 
-The same methods are available on `session.sandbox.files`; the SDK enforces upload length, ticket
-ceilings, abort signals, and the downloaded object's exact metadata length while bytes bypass
-Brain. Direct large sandbox transfers are a happy-path convenience: the SDK does not automatically
-retry an ambiguous completion or recover a ticket after Brain restart or expiry. Inspect the
-generation and path, then prepare a fresh transfer. Put bytes in `session.storage` and copy them to
-or from the sandbox when the transfer itself must be recovery-safe.
-
-`await session.end()` closes work but retains journal and storage. Both deletion modes first make
-the same short, durable deletion-job request. `await session.delete()` then polls the status
-resource for confirmed removal; `{ queue: true }` returns after acceptance. No HTTP request stays
-open while sandbox and storage cleanup runs.
+Source callback Tools are routed automatically to the single `app()` Environment. Durable objects
+remain available through `session.storage`, independently of Environment lifetime.

package/dist/index.d.ts

@@ -4,21 +4,18 @@ import type { WebSocketFactory } from "@aexhq/brain";
 export { AbortError, AexError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, } from "./errors.js";
 export type { AexErrorOptions, OutputValidationIssue } from "./errors.js";
 export { Session, Sessions, } from "./session.js";
-export type { AgentloopBundle, CreateSessionOptions, ListSessionsOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
-export { SandboxFiles, SessionChild, SessionChildren, SessionSandbox, SessionStorage, } from "./resources.js";
-export type { BinarySource, ChildSummary, IdempotentOperationOptions, OperationOptions, PageOptions, SandboxFile, SandboxFileOptions, SandboxFilePage, SandboxFilePageOptions, SandboxStatus, StorageObject, StoragePage, StreamingUploadSource, UploadSource, } from "./resources.js";
+export type { CreateSessionOptions, ListSessionsOptions, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
+export { SessionChild, SessionChildren, SessionStorage, } from "./resources.js";
+export type { BinarySource, ChildSummary, IdempotentOperationOptions, OperationOptions, PageOptions, StorageObject, StoragePage, StreamingUploadSource, UploadSource, } from "./resources.js";
 export type { EventOptions } from "./transport.js";
-export { tool } from "@aexhq/brain";
-export type { ClientToolOptions, Tool, ToolBuilder, ToolContract, ToolContext, ToolHandler, ServerToolOptions, NetworkDestination, NetworkPolicy, WebSocketFactory, } from "@aexhq/brain";
+export { tool } from "./tools.js";
+export type { Tool, ToolContract, ToolContext, ToolHandler, } from "./tools.js";
+export type { NetworkPolicy, WebSocketFactory } from "@aexhq/brain";
 export interface AexOptions {
     apiKey: string;
     baseUrl?: string;
     fetch?: Fetch;
     webSocketFactory?: WebSocketFactory;
-    /** Stable tenant-scoped identity for this exact customer-application runner. */
-    client?: {
-        id: string;
-    };
 }
 export declare class Aex {
     readonly sessions: Sessions;

package/dist/index.js

@@ -2,8 +2,8 @@ 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 { SandboxFiles, SessionChild, SessionChildren, SessionSandbox, SessionStorage, } from "./resources.js";
-export { tool } from "@aexhq/brain";
+export { SessionChild, SessionChildren, SessionStorage, } from "./resources.js";
+export { tool } from "./tools.js";
 const DEFAULT_API_URL = "https://api.aex.dev";
 export class Aex {
     sessions;
@@ -14,16 +14,12 @@ export class Aex {
         if (fetchImplementation === undefined) {
             throw new TypeError("This runtime does not provide fetch; pass a fetch implementation to Aex");
         }
-        if (options.client !== undefined &&
-            !/^[A-Za-z0-9_.:-]{1,128}$/u.test(options.client.id)) {
-            throw new TypeError("Aex client.id must contain 1 through 128 letters, digits, dots, colons, underscores, or hyphens");
-        }
         const transport = new Transport(options.apiKey, options.baseUrl ?? DEFAULT_API_URL, fetchImplementation);
         const webSocketFactory = options.webSocketFactory ??
             (globalThis.WebSocket === undefined
                 ? undefined
                 : (request) => new globalThis.WebSocket(request.url, request.protocol));
-        this.sessions = new Sessions(transport, webSocketFactory, options.client?.id);
+        this.sessions = new Sessions(transport, webSocketFactory);
     }
     /** Stop customer-app execution permanently; this Aex instance cannot create another session. */
     close() {

package/dist/resources.d.ts

@@ -101,12 +101,14 @@ export declare class SessionStorage {
     }): Promise<StorageObject>;
     delete(key: string, options?: OperationOptions): Promise<void>;
     copyFromSandbox(input: {
+        environment: string;
         key: string;
         path: string;
         sandboxGeneration: string;
         overwrite?: boolean;
     }, options?: OperationOptions): Promise<StorageObject>;
     copyToSandbox(input: {
+        environment: string;
         key: string;
         path: string;
         sandboxGeneration: string;

package/dist/resources.js

@@ -159,18 +159,18 @@ export class SessionStorage {
         return this.#inner.delete(key, request(options));
     }
     async copyFromSandbox(input, options = {}) {
-        return storageObject(await this.#inner.copyFromSandbox({
+        return storageObject(await this.#inner.copyFromEnvironment(input.environment, {
             key: input.key,
             path: input.path,
-            sandbox_generation: input.sandboxGeneration,
+            environment_generation: input.sandboxGeneration,
             ...(input.overwrite === undefined ? {} : { overwrite: input.overwrite }),
         }, request(options)));
     }
     async copyToSandbox(input, options = {}) {
-        return file(await this.#inner.copyToSandbox({
+        return file(await this.#inner.copyToEnvironment(input.environment, {
             key: input.key,
             path: input.path,
-            sandbox_generation: input.sandboxGeneration,
+            environment_generation: input.sandboxGeneration,
             ...(input.overwrite === undefined ? {} : { overwrite: input.overwrite }),
         }, request(options)));
     }

package/dist/session.d.ts

@@ -1,56 +1,37 @@
-import type { Event, Provider, Session as SessionData, SessionState } from "@aexhq/brain/session";
+import type { Event, Session as BrainSessionData, SessionState } from "@aexhq/brain/session";
+import { type ComponentExtension, type SessionTool as ComponentSessionTool } from "@aexhq/brain";
 import type { NetworkPolicy, WebSocketFactory } from "@aexhq/brain";
 import * as z from "zod";
 import type { EventOptions } from "./transport.js";
 import { Transport } from "./transport.js";
-import type { Tool } from "./tools.js";
+import { type Tool } from "./tools.js";
 import { SessionChildren, SessionSandbox, SessionStorage } from "./resources.js";
+type SessionData = BrainSessionData & {
+    retain_until: string;
+};
 export type SessionInput = string;
 export interface ModelOptions {
-    provider: Provider;
+    /** Imported Model component. */
+    component: ComponentExtension<"model">;
+    provider: string;
     name: string;
     apiKey: string;
     baseUrl?: string;
     maxOutputTokens?: number;
-    /** Immutable context capacity used for admission and compaction; Brain never guesses by name. */
-    contextWindowTokens?: number;
-    temperature?: number;
-    reasoningEffort?: "low" | "medium" | "high";
-}
-/**
- * A built agentloop implementation, as exported by a loop package or produced by
- * `buildLoopBundle` from `@aexhq/agentloop`. Assignment is by import, never by name:
- * the sealed identity is the content digest plus the pinned toolchain.
- */
-export interface AgentloopBundle {
-    /** The complete deterministic ESM source bundle — the exact bytes sealed and uploaded. */
-    source: string;
-    /** SHA-256 hex of the UTF-8 source bytes. */
-    sha256: string;
-    /** The pinned loop-toolchain identity the bundle was built for. */
-    toolchain: string;
 }
 export interface CreateSessionOptions {
     model: ModelOptions;
+    /** The imported agent loop that drives this session and every child unless spawn overrides it. */
+    agentloop: ComponentExtension<"agentloop">;
     /** Omitted or empty grants no tools. A non-empty list is the exact grant. */
-    tools?: readonly Tool[];
-    /**
-     * The agentloop driving this session's turns, assigned by importing its implementation.
-     * Sealed at create for the life of the session; children inherit it. Omission seals the
-     * official aex loop.
-     */
-    agentloop?: AgentloopBundle;
-    systemPrompt?: string;
-    /** Write-only values for environment names declared by managed Tools. */
+    environments?: Readonly<Record<string, ComponentExtension<"environment">>>;
+    tools?: readonly (Tool | ComponentSessionTool)[];
+    /** Write-only values for components that explicitly consume session secrets. */
     secrets?: Record<string, string>;
     /** Maximum direct outbound network authority sealed for managed sandboxes. Omission is deny-all. */
     network?: NetworkPolicy;
     /** Replacement attempts after an unrecoverable provider outcome. Defaults to one. */
     providerRecoveryRetries?: 0 | 1;
-    client?: {
-        /** Replacement sends to the same customer process and operation. Defaults to one. */
-        submitRetries?: 0 | 1;
-    };
     /** Optional ceilings for durable child sessions. Omitted fields use the hosted defaults. */
     children?: {
         maxDepth?: number;
@@ -58,6 +39,8 @@ export interface CreateSessionOptions {
         maxDescendants?: number;
     };
     metadata?: Record<string, string>;
+    /** Finite durable-history deadline. Omit to use the Brain deployment default. */
+    retainUntil?: Date | string;
 }
 export interface RequestOptions {
     signal?: AbortSignal;
@@ -81,7 +64,7 @@ export interface SessionList {
     nextCursor?: string;
 }
 export interface ModelSummary {
-    provider: Provider;
+    provider: string;
     name: string;
     baseUrl?: string;
     contextWindowTokens: number;
@@ -96,11 +79,12 @@ export interface SessionSummary {
     model: ModelSummary;
     createdAt: string;
     updatedAt: string;
+    retainUntil: string;
     metadata: Readonly<Record<string, string | undefined>>;
 }
 export declare class Sessions {
     #private;
-    constructor(transport: Transport, webSocketFactory?: WebSocketFactory, clientId?: string);
+    constructor(transport: Transport, webSocketFactory?: WebSocketFactory);
     /** @internal Called by `Aex.close()`. */
     close(): void;
     create(options: CreateSessionOptions, request?: RequestOptions): Promise<Session>;
@@ -122,6 +106,7 @@ export declare class Session implements SessionSummary {
     get model(): ModelSummary;
     get createdAt(): string;
     get updatedAt(): string;
+    get retainUntil(): string;
     get metadata(): Readonly<Record<string, string | undefined>>;
     refresh(options?: Pick<RequestOptions, "signal">): Promise<this>;
     send(input: SessionInput, options?: RequestOptions): Promise<string>;
@@ -133,9 +118,15 @@ export declare class Session implements SessionSummary {
      */
     events(options?: EventOptions): AsyncGenerator<Event>;
     cancel(options?: Pick<RequestOptions, "signal">): Promise<this>;
+    suspend(options?: Pick<RequestOptions, "signal">): Promise<this>;
+    resume(options?: Pick<RequestOptions, "signal">): Promise<this>;
+    setRetention(value: Date | string, options?: Pick<RequestOptions, "signal"> & {
+        allowShorten?: boolean;
+    }): Promise<this>;
     end(options?: Pick<RequestOptions, "signal">): Promise<this>;
     delete(options?: Pick<RequestOptions, "signal"> & {
         queue?: boolean;
     }): Promise<void>;
     private markIdle;
 }
+export {};

package/dist/session.js

@@ -1,40 +1,127 @@
-import { CustomerHand } from "@aexhq/brain";
+import { CustomerEnvironment, prepareComponents, } from "@aexhq/brain";
 import * as z from "zod";
 import { AbortError, OutputRefusalError, OutputSchemaError, OutputValidationError, SessionError, abortError, errorFromApi, } from "./errors.js";
 import { canonicalize, jcsSha256, randomIdempotencyKey } from "./json.js";
-import { compileTools } from "./tools.js";
-import { encodeBase64, SessionChildren, SessionSandbox, SessionStorage } from "./resources.js";
+import { compileCallbacks } from "./tools.js";
+import { SessionChildren, SessionSandbox, SessionStorage } from "./resources.js";
 export class Sessions {
     #transport;
     #webSocketFactory;
-    #clientId;
-    #customerHand;
-    #customerHandInstance;
+    #customerEnvironments = new Map();
+    #customerEnvironmentInstances = new Map();
     #closed = false;
-    constructor(transport, webSocketFactory, clientId) {
+    constructor(transport, webSocketFactory) {
         this.#transport = transport;
         this.#webSocketFactory = webSocketFactory;
-        this.#clientId = clientId;
     }
     /** @internal Called by `Aex.close()`. */
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
-        this.#customerHandInstance?.close();
-        this.#customerHandInstance = undefined;
-        this.#customerHand = undefined;
+        for (const hand of this.#customerEnvironmentInstances.values())
+            hand.close();
+        this.#customerEnvironmentInstances.clear();
+        this.#customerEnvironments.clear();
     }
     async create(options, request = {}) {
         if (this.#closed)
             throw new SessionError("Aex client is closed");
-        const compiledTools = await compileTools(options.tools);
-        if (options.client?.submitRetries !== undefined && this.#clientId === undefined) {
-            throw new TypeError("client.submitRetries requires Aex({ client: { id } })");
+        if (options.model?.component === undefined) {
+            throw new TypeError("sessions.create requires an imported Model component");
         }
-        await this.#ensureCustomerHand(compiledTools.clientRegistrations, request.signal);
+        if (options.agentloop === undefined) {
+            throw new TypeError("sessions.create requires an imported Agentloop component");
+        }
+        const model = options.model.component;
+        const agentloop = options.agentloop;
+        const tools = [...(options.tools ?? [])];
+        const componentTools = tools.filter(isComponentTool);
+        const callbackTools = tools.filter((tool) => !isComponentTool(tool));
+        const environments = Object.entries(options.environments ?? {});
+        if (environments.some(([, environment]) => !isEnvironmentComponent(environment))) {
+            throw new TypeError("component sessions accept only precompiled Environment component values");
+        }
+        const environmentComponents = environments.map(([name, environment]) => {
+            if (!isEnvironmentComponent(environment)) {
+                throw new TypeError(`Environment ${JSON.stringify(name)} is not a component`);
+            }
+            return [name, environment];
+        });
+        const applicationEnvironments = environmentComponents.filter(([, environment]) => isApplicationEnvironment(environment));
+        if (callbackTools.length > 0 && applicationEnvironments.length !== 1) {
+            throw new TypeError("application callback Tools require exactly one app() Environment");
+        }
+        const callbacks = await compileCallbacks(callbackTools);
+        const allComponentTools = [...componentTools, ...callbacks.components];
+        const toolDefinitions = allComponentTools.map(componentToolDefinition);
+        const names = new Set();
+        for (const definition of toolDefinitions) {
+            if (names.has(definition.name)) {
+                throw new TypeError(`Tool ${JSON.stringify(definition.name)} was selected twice`);
+            }
+            names.add(definition.name);
+        }
+        const callbackEnvironment = applicationEnvironments[0];
+        if (callbackEnvironment !== undefined) {
+            await this.#ensureCustomerEnvironment(applicationEnvironmentId(callbackEnvironment[1]), callbacks.registrations, request.signal);
+        }
+        const prepared = await prepareComponents([
+            model,
+            agentloop,
+            ...allComponentTools,
+            ...environmentComponents.map(([, environment]) => environment),
+        ]);
+        const modelBinding = prepared.bindings[0];
+        const agentloopBinding = prepared.bindings[1];
+        if (modelBinding === undefined || agentloopBinding === undefined) {
+            throw new TypeError("component session bindings are incomplete");
+        }
+        const toolBindings = prepared.bindings.slice(2, 2 + allComponentTools.length);
+        const environmentBindings = prepared.bindings.slice(2 + allComponentTools.length);
+        const toolItems = allComponentTools.map((tool, index) => {
+            const binding = toolBindings[index];
+            if (binding === undefined)
+                throw new TypeError("Tool component binding is missing");
+            const definition = toolDefinitions[index];
+            if (definition === undefined)
+                throw new TypeError("Tool component definition is missing");
+            const needsEnvironment = binding.grants.includes("environment");
+            const isCallback = index >= componentTools.length;
+            if (needsEnvironment && !isCallback && environmentComponents.length !== 1) {
+                throw new TypeError("a Tool with the environment grant requires exactly one declared Environment");
+            }
+            const environmentName = isCallback
+                ? callbackEnvironment?.[0]
+                : environmentComponents[0]?.[0];
+            return {
+                definition,
+                executor: {
+                    kind: "component",
+                    component_digest: binding.component_digest,
+                    world: binding.world,
+                    config: binding.config,
+                    grants: binding.grants,
+                    ...(needsEnvironment ? { environment: environmentName } : {}),
+                },
+            };
+        });
+        const environmentConfig = Object.fromEntries(environmentComponents.map(([name], index) => {
+            const binding = environmentBindings[index];
+            if (binding === undefined) {
+                throw new TypeError(`Environment component binding ${JSON.stringify(name)} is missing`);
+            }
+            return [name, {
+                    component_digest: binding.component_digest,
+                    world: binding.world,
+                    config: binding.config,
+                }];
+        }));
         const body = {
             model: {
+                component_digest: modelBinding.component_digest,
+                world: modelBinding.world,
+                config: modelBinding.config,
                 provider: options.model.provider,
                 name: options.model.name,
                 api_key: options.model.apiKey,
@@ -42,46 +129,24 @@ export class Sessions {
                 ...(options.model.maxOutputTokens === undefined
                     ? {}
                     : { max_output_tokens: options.model.maxOutputTokens }),
-                ...(options.model.contextWindowTokens === undefined
-                    ? {}
-                    : { context_window_tokens: options.model.contextWindowTokens }),
-                ...(options.model.temperature === undefined ? {} : { temperature: options.model.temperature }),
-                ...(options.model.reasoningEffort === undefined
-                    ? {}
-                    : { reasoning_effort: options.model.reasoningEffort }),
             },
-            tools: {
-                items: compiledTools.items,
+            agentloop: {
+                component_digest: agentloopBinding.component_digest,
+                world: agentloopBinding.world,
+                config: agentloopBinding.config,
             },
-            ...(compiledTools.bundles.length === 0 ? {} : { tool_bundles: compiledTools.bundles }),
-            ...(options.agentloop === undefined
-                ? {}
-                : {
-                    agentloop: {
-                        source_bundle_sha256: options.agentloop.sha256,
-                        toolchain: options.agentloop.toolchain,
-                        bundle_base64: encodeBase64(new TextEncoder().encode(options.agentloop.source)),
-                    },
-                }),
+            component_artifacts: prepared.artifacts,
+            tools: { items: toolItems },
+            ...(environmentComponents.length === 0 ? {} : { environments: environmentConfig }),
             ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
-            ...(options.systemPrompt === undefined ? {} : { system_prompt: options.systemPrompt }),
             ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
-            ...(options.network === undefined
+            ...(options.retainUntil === undefined
                 ? {}
-                : { network: options.network }),
+                : { retain_until: normalizeTimestamp(options.retainUntil, "retainUntil") }),
+            ...(options.network === undefined ? {} : { network: options.network }),
             ...(options.providerRecoveryRetries === undefined
                 ? {}
                 : { provider_recovery_retries: options.providerRecoveryRetries }),
-            ...(this.#clientId === undefined
-                ? {}
-                : {
-                    client: {
-                        id: this.#clientId,
-                        ...(options.client?.submitRetries === undefined
-                            ? {}
-                            : { submit_retries: options.client.submitRetries }),
-                    },
-                }),
             ...(options.children === undefined
                 ? {}
                 : {
@@ -128,29 +193,29 @@ export class Sessions {
             ...(list.next_cursor === undefined ? {} : { nextCursor: list.next_cursor }),
         };
     }
-    async #ensureCustomerHand(registrations, signal) {
+    async #ensureCustomerEnvironment(clientId, registrations, signal) {
         if (this.#closed)
             throw new SessionError("Aex client is closed");
         if (registrations.length === 0)
             return;
-        if (this.#clientId === undefined) {
-            throw new TypeError("Customer-app Tools require Aex({ client: { id } })");
-        }
+        if (clientId === undefined)
+            throw new TypeError("Callback Tools require an app() environment");
         if (this.#webSocketFactory === undefined) {
             throw new TypeError("This runtime does not provide WebSocket; pass webSocketFactory to Aex");
         }
-        if (this.#customerHand === undefined) {
+        const existing = this.#customerEnvironments.get(clientId);
+        if (existing === undefined) {
             let partial;
             const starting = (async () => {
                 try {
-                    partial = new CustomerHand(async () => {
-                        const grant = await this.#transport.customerHandGrant(this.#clientId);
+                    partial = new CustomerEnvironment(async () => {
+                        const grant = await this.#transport.customerEnvironmentGrant(clientId);
                         return {
                             request: { url: grant.url, protocol: grant.protocol },
-                            observe: (observation) => this.#transport.customerHandObserve(grant.observationUrl, grant.observationToken, observation),
+                            observe: (observation) => this.#transport.customerEnvironmentObserve(grant.observationUrl, grant.observationToken, observation),
                         };
-                    }, registrations, this.#webSocketFactory, { clientId: this.#clientId });
-                    this.#customerHandInstance = partial;
+                    }, registrations, this.#webSocketFactory, { clientId });
+                    this.#customerEnvironmentInstances.set(clientId, partial);
                     await partial.ready;
                     if (this.#closed) {
                         partial.close();
@@ -163,12 +228,13 @@ export class Sessions {
                     throw error;
                 }
             })();
-            this.#customerHand = starting;
+            this.#customerEnvironments.set(clientId, starting);
             void starting.catch(() => {
-                if (this.#customerHand === starting) {
-                    this.#customerHand = undefined;
-                    if (this.#customerHandInstance === partial)
-                        this.#customerHandInstance = undefined;
+                if (this.#customerEnvironments.get(clientId) === starting) {
+                    this.#customerEnvironments.delete(clientId);
+                    if (this.#customerEnvironmentInstances.get(clientId) === partial) {
+                        this.#customerEnvironmentInstances.delete(clientId);
+                    }
                 }
             });
             // The request may stop waiting, but the process-scoped runner remains reconnectable for
@@ -176,12 +242,48 @@ export class Sessions {
             await waitWithSignal(starting, signal);
             return;
         }
-        const hand = await waitWithSignal(this.#customerHand, signal);
+        const hand = await waitWithSignal(existing, signal);
         if (this.#closed)
             throw new SessionError("Aex client is closed");
         await waitWithSignal(hand.register(registrations), signal);
     }
 }
+function isApplicationEnvironment(value) {
+    const config = value.config;
+    return config !== null && typeof config === "object" && !Array.isArray(config) &&
+        config.driver === "customer";
+}
+function applicationEnvironmentId(value) {
+    const config = value.config;
+    const id = config.configuration?.registration;
+    if (typeof id !== "string" || !/^[A-Za-z0-9_.:-]{1,128}$/u.test(id)) {
+        throw new TypeError("app() Environment registration is invalid");
+    }
+    return id;
+}
+function isComponentTool(value) {
+    return value !== null
+        && typeof value === "object"
+        && value.kind === "brain.component"
+        && value.extension === "tool";
+}
+function isEnvironmentComponent(value) {
+    return value !== null
+        && typeof value === "object"
+        && value.kind === "brain.component"
+        && value.extension === "environment";
+}
+function componentToolDefinition(value) {
+    const config = value.config;
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+        throw new TypeError("Tool component config must be an object containing definition");
+    }
+    const definition = config.definition;
+    if (definition === null || typeof definition !== "object" || Array.isArray(definition)) {
+        throw new TypeError("Tool component config.definition is required");
+    }
+    return definition;
+}
 function waitWithSignal(promise, signal) {
     if (signal === undefined)
         return promise;
@@ -242,6 +344,9 @@ export class Session {
     get updatedAt() {
         return this.#data.updated_at;
     }
+    get retainUntil() {
+        return this.#data.retain_until;
+    }
     get metadata() {
         return this.#data.metadata;
     }
@@ -343,6 +448,25 @@ export class Session {
         this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/cancel`, { signal: options.signal, retry: true });
         return this;
     }
+    async suspend(options = {}) {
+        this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/suspend`, { signal: options.signal, retry: true });
+        return this;
+    }
+    async resume(options = {}) {
+        this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/resume`, { signal: options.signal, retry: true });
+        return this;
+    }
+    async setRetention(value, options = {}) {
+        this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/retention`, {
+            body: {
+                retain_until: normalizeTimestamp(value, "retainUntil"),
+                allow_shorten: options.allowShorten ?? false,
+            },
+            signal: options.signal,
+            retry: true,
+        });
+        return this;
+    }
     async end(options = {}) {
         this.#data = await this.#transport.json("POST", `/v1/sessions/${encodeURIComponent(this.id)}/end`, { signal: options.signal, retry: true });
         return this;
@@ -361,6 +485,12 @@ export class Session {
 function isOutputOptions(options) {
     return "output" in options;
 }
+function normalizeTimestamp(value, field) {
+    const parsed = value instanceof Date ? value : new Date(value);
+    if (!Number.isFinite(parsed.getTime()))
+        throw new TypeError(`${field} must be a valid timestamp`);
+    return parsed.toISOString();
+}
 async function compileOutputSchema(schema, retries) {
     let jsonSchema;
     try {

package/dist/tools.d.ts

@@ -1,2 +1,48 @@
-export { compileTools } from "@aexhq/brain";
-export type { ClientRegistration, CompiledTools, Tool } from "@aexhq/brain";
+import type { ComponentExtension } from "@aexhq/brain";
+import type { ToolDefinition } from "@aexhq/brain/session";
+import * as z from "zod";
+export type JsonSchema = Record<string, unknown>;
+export interface ToolContext {
+    readonly signal: AbortSignal;
+    readonly operationId: string;
+    readonly sessionId: string;
+    readonly deadlineMs: number;
+}
+export type ToolHandler<Input extends z.ZodType, Output = unknown> = (input: z.output<Input>, context: ToolContext) => Output | Promise<Output>;
+export interface ToolContract {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+    readonly contractDigest: string;
+}
+export interface Tool<Input extends z.ZodType = z.ZodType, Output = unknown> {
+    readonly kind: "aex.tool";
+    readonly name?: string;
+    readonly description?: string;
+    readonly input: Input;
+    readonly output?: z.ZodType;
+    readonly handler: ToolHandler<Input, Output>;
+    describe(description: string): Tool<Input, Output>;
+    named(name: string): Tool<Input, Output>;
+    returns<Schema extends z.ZodType>(schema: Schema): Tool<Input, z.output<Schema>>;
+}
+declare const EMPTY_INPUT: z.ZodObject<{}, z.core.$strip>;
+export declare function tool<Output>(handler: ToolHandler<typeof EMPTY_INPUT, Output>): Tool<typeof EMPTY_INPUT, Output>;
+export declare function tool<Input extends z.ZodType, Output>(input: Input, handler: ToolHandler<Input, Output>): Tool<Input, Output>;
+export interface ClientRegistration {
+    readonly registration: string;
+    readonly name: string;
+    readonly contractDigest: string;
+    readonly input: z.ZodType;
+    readonly output?: z.ZodType;
+    readonly handler: ToolHandler<z.ZodType>;
+}
+export interface CompiledCallbacks {
+    readonly components: readonly ComponentExtension<"tool", Readonly<Record<string, unknown>> & {
+        readonly definition: ToolDefinition;
+    }>[];
+    readonly registrations: readonly ClientRegistration[];
+}
+export declare function compileCallbacks(selections: readonly Tool[]): Promise<CompiledCallbacks>;
+export {};

package/dist/tools.js

@@ -1 +1,119 @@
-export { compileTools } from "@aexhq/brain";
+import { callback as callbackComponent } from "@aexhq/env-app";
+import * as z from "zod";
+import { jcsSha256 } from "./json.js";
+const EMPTY_INPUT = z.object({});
+const TOOL_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/u;
+export function tool(inputOrHandler, maybeHandler) {
+    if (typeof inputOrHandler === "function") {
+        return makeTool({
+            ...(inputOrHandler.name === "" ? {} : { name: inputOrHandler.name }),
+            input: EMPTY_INPUT,
+            handler: inputOrHandler,
+        });
+    }
+    if (typeof maybeHandler !== "function")
+        throw new TypeError("tool(schema, handler) requires a function");
+    return makeTool({
+        ...(maybeHandler.name === "" ? {} : { name: maybeHandler.name }),
+        input: inputOrHandler,
+        handler: maybeHandler,
+    });
+}
+function makeTool(draft) {
+    return Object.freeze({
+        kind: "aex.tool",
+        ...(draft.name === undefined ? {} : { name: draft.name }),
+        ...(draft.description === undefined ? {} : { description: draft.description }),
+        input: draft.input,
+        ...(draft.output === undefined ? {} : { output: draft.output }),
+        handler: draft.handler,
+        describe(description) {
+            if (description.trim() === "" || description.length > 4096) {
+                throw new TypeError("Tool description must contain 1 through 4096 characters");
+            }
+            return makeTool({ ...draft, description });
+        },
+        named(name) {
+            assertToolName(name);
+            return makeTool({ ...draft, name });
+        },
+        returns(output) {
+            schemaOf(output, `${draft.name ?? "Tool"} output`);
+            return makeTool({ ...draft, output });
+        },
+    });
+}
+export async function compileCallbacks(selections) {
+    const components = [];
+    const registrations = [];
+    const names = new Set();
+    for (const value of selections) {
+        assertTool(value);
+        const contract = await compileContract(value);
+        if (names.has(contract.name)) {
+            throw new TypeError(`Tool ${JSON.stringify(contract.name)} was selected twice`);
+        }
+        names.add(contract.name);
+        const definition = {
+            name: contract.name,
+            ...(contract.description === undefined ? {} : { description: contract.description }),
+            input_schema: contract.inputSchema,
+            output_schema: contract.outputSchema ?? {},
+            contract_digest: contract.contractDigest,
+        };
+        const registration = `tool:${contract.contractDigest}`;
+        components.push(callbackComponent(definition, registration));
+        registrations.push(Object.freeze({
+            registration,
+            name: contract.name,
+            contractDigest: contract.contractDigest,
+            input: value.input,
+            ...(value.output === undefined ? {} : { output: value.output }),
+            handler: value.handler,
+        }));
+    }
+    return {
+        components: Object.freeze(components),
+        registrations: Object.freeze(registrations),
+    };
+}
+async function compileContract(value) {
+    const name = value.name;
+    if (name === undefined)
+        throw new TypeError("Tool functions must be named; use .named(name) when build tooling removes the name");
+    assertToolName(name);
+    const inputSchema = schemaOf(value.input, `${name} input`);
+    const outputSchema = value.output === undefined ? undefined : schemaOf(value.output, `${name} output`);
+    const canonical = {
+        name,
+        ...(value.description === undefined ? {} : { description: value.description }),
+        input_schema: inputSchema,
+        ...(outputSchema === undefined ? {} : { output_schema: outputSchema }),
+    };
+    return {
+        name,
+        ...(value.description === undefined ? {} : { description: value.description }),
+        inputSchema,
+        ...(outputSchema === undefined ? {} : { outputSchema }),
+        contractDigest: await jcsSha256(canonical),
+    };
+}
+function schemaOf(schema, label) {
+    try {
+        const value = z.toJSONSchema(schema, { target: "draft-2020-12", unrepresentable: "throw" });
+        if (Object.keys(value).length === 0)
+            throw new TypeError(`${label} schema is empty`);
+        return value;
+    }
+    catch (cause) {
+        throw new TypeError(`${label} cannot be represented as JSON Schema`, { cause });
+    }
+}
+function assertTool(value) {
+    if (value?.kind !== "aex.tool")
+        throw new TypeError("Tool selection is invalid");
+}
+function assertToolName(name) {
+    if (!TOOL_NAME.test(name))
+        throw new TypeError(`Invalid Tool name ${JSON.stringify(name)}`);
+}

package/dist/transport.d.ts

@@ -10,14 +10,14 @@ export declare class Transport {
     #private;
     readonly baseUrl: string;
     constructor(apiKey: string, baseUrl: string, fetchImplementation: Fetch);
-    customerHandGrant(clientId: string, signal?: AbortSignal): Promise<{
+    customerEnvironmentGrant(clientId: string, signal?: AbortSignal): Promise<{
         url: string;
         protocol: string;
         expiresAt: string;
         observationUrl: string;
         observationToken: string;
     }>;
-    customerHandObserve(url: string, token: string, observation: unknown): Promise<void>;
+    customerEnvironmentObserve(url: string, token: string, observation: unknown): Promise<void>;
     downloadTransfer(ticket: TransferTicket, signal?: AbortSignal, expectedBytes?: number): Promise<Uint8Array>;
     downloadTransferStream(ticket: TransferTicket, signal?: AbortSignal, expectedBytes?: number): Promise<ReadableStream<Uint8Array>>;
     uploadTransfer(ticket: TransferTicket, content: Uint8Array | (() => ReadableStream<Uint8Array>), bytes: number, signal?: AbortSignal): Promise<void>;

package/dist/transport.js

@@ -2,7 +2,7 @@ import { MAX_CREATE_SESSION_REQUEST_BYTES, MAX_CUSTOMER_OBSERVATION_BYTES, MAX_M
 import { AbortError, AexError, SessionError, abortError, errorFromApi } from "./errors.js";
 const MAX_ORDINARY_JSON_BYTES = 2 * 1024 * 1024;
 const MAX_ERROR_RESPONSE_BYTES = 64 * 1024;
-const CUSTOMER_HAND_OBSERVATION_TIMEOUT_MS = 15_000;
+const CUSTOMER_ENVIRONMENT_OBSERVATION_TIMEOUT_MS = 15_000;
 export class Transport {
     baseUrl;
     #apiKey;
@@ -15,9 +15,9 @@ export class Transport {
         this.baseUrl = baseUrl.slice(0, end);
         this.#fetch = fetchImplementation;
     }
-    async customerHandGrant(clientId, signal) {
-        const grant = await this.json("POST", "/v1/customer-hand/grants", { body: { client_id: clientId }, signal });
-        const observationUrl = validateCustomerHandGrant(this.baseUrl, grant);
+    async customerEnvironmentGrant(clientId, signal) {
+        const grant = await this.json("POST", "/v1/customer-environment/grants", { body: { client_id: clientId }, signal });
+        const observationUrl = validateCustomerEnvironmentGrant(this.baseUrl, grant);
         return {
             url: grant.url,
             protocol: grant.protocol,
@@ -26,8 +26,8 @@ export class Transport {
             observationToken: grant.observation_token,
         };
     }
-    async customerHandObserve(url, token, observation) {
-        const body = encodeJsonOnce(observation, MAX_CUSTOMER_OBSERVATION_BYTES, "Customer Hand observation");
+    async customerEnvironmentObserve(url, token, observation) {
+        const body = encodeJsonOnce(observation, MAX_CUSTOMER_OBSERVATION_BYTES, "Customer Environment observation");
         const response = await this.#fetch(url, {
             method: "POST",
             redirect: "error",
@@ -37,13 +37,13 @@ export class Transport {
                 "Content-Type": "application/json",
             },
             body,
-            signal: AbortSignal.timeout(CUSTOMER_HAND_OBSERVATION_TIMEOUT_MS),
+            signal: AbortSignal.timeout(CUSTOMER_ENVIRONMENT_OBSERVATION_TIMEOUT_MS),
         });
         if (response.ok)
             return;
         const preview = await readResponseText(response, 4096)
             .catch(() => "<response too large or unreadable>");
-        throw new SessionError(`Customer Hand observation ingress returned HTTP ${response.status}: ${preview}`, { status: response.status, requestId: response.headers.get("x-request-id") ?? undefined });
+        throw new SessionError(`Customer Environment observation ingress returned HTTP ${response.status}: ${preview}`, { status: response.status, requestId: response.headers.get("x-request-id") ?? undefined });
     }
     async downloadTransfer(ticket, signal, expectedBytes) {
         const stream = await this.downloadTransferStream(ticket, signal, expectedBytes);
@@ -419,15 +419,15 @@ function assertTransferTicket(ticket, method) {
         throw new SessionError("Aex file transfers require HTTPS (or loopback HTTP for development)");
     }
 }
-function validateCustomerHandGrant(baseUrl, grant) {
+function validateCustomerEnvironmentGrant(baseUrl, grant) {
     if (!/^[A-Za-z0-9_.-]{1,128}$/u.test(grant.grant_id)) {
-        throw new SessionError("Aex returned an invalid customer Hand grant id");
+        throw new SessionError("Aex returned an invalid customer Environment grant id");
     }
     if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]{1,2048}$/u.test(grant.protocol)) {
-        throw new SessionError("Aex returned an invalid customer Hand WebSocket protocol");
+        throw new SessionError("Aex returned an invalid customer Environment WebSocket protocol");
     }
     if (!/^[\x21-\x7e]{1,2048}$/u.test(grant.observation_token)) {
-        throw new SessionError("Aex returned an invalid customer Hand observation token");
+        throw new SessionError("Aex returned an invalid customer Environment observation token");
     }
     let socket;
     let observation;
@@ -435,19 +435,19 @@ function validateCustomerHandGrant(baseUrl, grant) {
     try {
         socket = new URL(grant.url);
         observation = new URL(grant.observation_url);
-        expectedObservation = new URL(`${baseUrl}/v1/customer-hand/observations/${encodeURIComponent(grant.grant_id)}`);
+        expectedObservation = new URL(`${baseUrl}/v1/customer-environment/observations/${encodeURIComponent(grant.grant_id)}`);
     }
     catch (cause) {
-        throw new SessionError("Aex returned an invalid customer Hand URL", { cause });
+        throw new SessionError("Aex returned an invalid customer Environment URL", { cause });
     }
     const secureSocket = socket.protocol === "wss:" ||
         (socket.protocol === "ws:" && isLoopback(socket.hostname));
     if (!secureSocket || socket.username !== "" || socket.password !== "" ||
         socket.search !== "" || socket.hash !== "") {
-        throw new SessionError("Aex customer Hand sockets require credential-free WSS (or loopback WS for development)");
+        throw new SessionError("Aex customer Environment sockets require credential-free WSS (or loopback WS for development)");
     }
     if (observation.href !== expectedObservation.href) {
-        throw new SessionError("Aex returned an unsafe customer Hand observation URL");
+        throw new SessionError("Aex returned an unsafe customer Environment observation URL");
     }
     if (observation.href.includes(grant.observation_token)) {
         throw new SessionError("Aex returned an observation URL containing its bearer token");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.57.5",
+  "version": "0.59.0",
   "description": "TypeScript SDK for Aex sessions",
   "license": "Apache-2.0",
   "homepage": "https://aex.dev",
@@ -34,7 +34,8 @@
     "test": "tsc -p tsconfig.json && node --test"
   },
   "dependencies": {
-    "@aexhq/brain": "0.3.0"
+    "@aexhq/brain": "0.3.1",
+    "@aexhq/env-app": "0.2.0"
   },
   "peerDependencies": {
     "zod": "4.4.3"