@aexhq/sdk 0.57.4 → 0.58.0

package/README.md

@@ -1,105 +1,60 @@
-# `@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 { bash, read, 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: {
+    provider: "openai",
+    name: "gpt-5.4",
+    apiKey: process.env.OPENAI_API_KEY!,
+  },
+  loop: pi({ instructions: "Work carefully and verify changes." }),
+  environments: { workspace },
+  tools: [bash(), read(), write()],
 });
-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.
+There is no default loop or environment. Every tool is bound to one declared environment before
+the request is sent. An unbound tool is bound automatically only when exactly one declared
+environment satisfies it; otherwise creation fails with the eligible or missing capabilities.
 
-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.
+## Tools
 
-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:
-
-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.
+`tool()` creates an immutable tool extension from a Zod input schema and a handler:
 
 ```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:
-
-```ts
-import { createReadStream } from "node:fs";
-import { Readable } from "node:stream";
+import { tool } from "@aexhq/sdk";
+import { z } from "zod";
 
-await session.storage.upload("inputs/archive.tar", {
-  bytes: stat.size,
-  sha256: digest,
-  stream: () => Readable.toWeb(createReadStream(filename)),
-});
-const body = await session.storage.downloadStream("inputs/archive.tar");
+export default 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() }))
+  .needs({ env: ["ORDERS_TOKEN"], network: [{ host: "orders.example.com", port: 443 }] })
+  .setup(async function prepareIndex() {
+    await database.prepareIndex();
+  });
 ```
 
-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.
+Use `tool.bind(environmentRef)` when more than one environment is compatible. Source tools run
+through an `app()` callback environment. `aex tools build` prepares computer tools with their
+runtime and dependencies; tool authors do not pass `import.meta.url` or choose a provider.
 
-`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.
+Environment references are opaque values returned by environment-extension factories. A created
+session preserves their types, so `session.environment(ref)` returns that extension's typed handle.
+Durable objects remain available through `session.storage`, independently of environment lifetime.

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { ApiError, ApiErrorCode } from "@aexhq/brain/session";
+import type { ApiError, ApiErrorCode } from "@aexhq/session-protocol/session";
 /** One Aex trusted-output validation failure, expressed as a JSON Pointer. */
 export interface OutputValidationIssue {
     path: string;

package/dist/index.d.ts

@@ -1,24 +1,22 @@
 import { Sessions } from "./session.js";
 import type { Fetch } from "./transport.js";
-import type { WebSocketFactory } from "@aexhq/brain";
+import type { WebSocketFactory } from "@aexhq/session-protocol";
 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 { 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, Loop, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.js";
+export { SessionChild, SessionChildren, SessionStorage, } from "./resources.js";
+export type { BinarySource, ChildSummary, EnvironmentFile, 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 { BoundTool, EnvironmentMap, EnvironmentValue, PreparedArtifact, Tool, ToolContract, ToolContext, ToolHandler, ToolRequirements, ToolSelection, ToolSetupHandler, } from "./tools.js";
+export type { NetworkPolicy, WebSocketFactory } from "@aexhq/session-protocol";
+export type { EnvironmentRef, HandleOf } from "@aexhq/environment";
 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/internal.d.ts

@@ -0,0 +1,2 @@
+export { withPreparedArtifact } from "./tools.js";
+export type { PreparedArtifact, Tool } from "./tools.js";

package/dist/internal.js

@@ -0,0 +1 @@
+export { withPreparedArtifact } from "./tools.js";

package/dist/resources.d.ts

@@ -1,6 +1,7 @@
-import { SessionChildren as BrainChildren, SessionSandbox as BrainSandbox } from "@aexhq/brain";
-import type { SandboxFileEntry as BrainSandboxFileEntry, SandboxStatus as BrainSandboxStatus } from "@aexhq/brain";
-import type { Event, Session as BrainSession } from "@aexhq/brain/session";
+import { SessionChildren as BrainChildren } from "@aexhq/session-protocol";
+import type { EnvironmentFileEntry as BrainEnvironmentFileEntry } from "@aexhq/session-protocol";
+import type { Event, Session as BrainSession } from "@aexhq/session-protocol/session";
+import type { EnvironmentRef } from "@aexhq/environment";
 import type { EventOptions } from "./transport.js";
 import { Transport } from "./transport.js";
 export type BinarySource = string | ArrayBuffer | ArrayBufferView | Blob;
@@ -22,57 +23,13 @@ export interface PageOptions extends OperationOptions {
     cursor?: string;
     limit?: number;
 }
-export interface SandboxStatus {
-    state: BrainSandboxStatus["state"];
-    generation?: string;
-    reason?: string;
-    changedAt?: string;
-    expiresAt?: string;
-}
-export interface SandboxFile {
+export interface EnvironmentFile {
     path: string;
-    kind: BrainSandboxFileEntry["kind"];
+    kind: BrainEnvironmentFileEntry["kind"];
     bytes: number;
     sha256?: string;
     modifiedAt: string;
 }
-export interface SandboxFilePage {
-    data: SandboxFile[];
-    hasMore: boolean;
-    nextCursor?: string;
-    generation: string;
-}
-export interface SandboxFileOptions extends OperationOptions {
-    generation: string;
-}
-export interface SandboxFilePageOptions extends SandboxFileOptions, PageOptions {
-}
-export declare class SandboxFiles {
-    #private;
-    constructor(inner: BrainSandbox["files"], transport: Transport);
-    list(path: string, options: SandboxFilePageOptions): Promise<SandboxFilePage>;
-    stat(path: string, options: SandboxFileOptions): Promise<SandboxFile>;
-    download(path: string, options: SandboxFileOptions): Promise<Uint8Array>;
-    downloadStream(path: string, options: SandboxFileOptions): Promise<ReadableStream<Uint8Array>>;
-    upload(path: string, source: UploadSource, options: SandboxFileOptions & {
-        overwrite?: boolean;
-    }): Promise<SandboxFile>;
-    find(input: {
-        path: string;
-        glob: string;
-    }, options: SandboxFilePageOptions): Promise<SandboxFilePage>;
-    grep(input: {
-        path: string;
-        query: string;
-    }, options: SandboxFilePageOptions): Promise<SandboxFilePage>;
-}
-export declare class SessionSandbox {
-    #private;
-    readonly files: SandboxFiles;
-    constructor(transport: Transport, sessionId: string);
-    status(options?: OperationOptions): Promise<SandboxStatus>;
-    create(options?: OperationOptions): Promise<SandboxStatus>;
-}
 export interface StorageObject {
     key: string;
     bytes: number;
@@ -88,7 +45,7 @@ export interface StoragePage {
 }
 export declare class SessionStorage {
     #private;
-    constructor(transport: Transport, sessionId: string);
+    constructor(transport: Transport, sessionId: string, environmentNames?: ReadonlyMap<EnvironmentRef, string>);
     list(options?: PageOptions & {
         prefix?: string;
     }): Promise<StoragePage>;
@@ -100,18 +57,18 @@ export declare class SessionStorage {
         overwrite?: boolean;
     }): Promise<StorageObject>;
     delete(key: string, options?: OperationOptions): Promise<void>;
-    copyFromSandbox(input: {
+    copyFromEnvironment(environment: EnvironmentRef, input: {
         key: string;
         path: string;
-        sandboxGeneration: string;
+        generation: string;
         overwrite?: boolean;
     }, options?: OperationOptions): Promise<StorageObject>;
-    copyToSandbox(input: {
+    copyToEnvironment(environment: EnvironmentRef, input: {
         key: string;
         path: string;
-        sandboxGeneration: string;
+        generation: string;
         overwrite?: boolean;
-    }, options?: OperationOptions): Promise<SandboxFile>;
+    }, options?: OperationOptions): Promise<EnvironmentFile>;
 }
 export interface ChildSummary {
     id: string;
@@ -155,3 +112,4 @@ export declare class SessionChildren {
     }>;
     get(childId: string): SessionChild;
 }
+export declare function encodeBase64(bytes: Uint8Array): string;

package/dist/resources.js

@@ -1,110 +1,14 @@
-import { MAX_INLINE_FILE_BYTES, SessionChildren as BrainChildren, SessionSandbox as BrainSandbox, SessionStorage as BrainStorage, } from "@aexhq/brain";
+import { MAX_INLINE_FILE_BYTES, SessionChildren as BrainChildren, SessionStorage as BrainStorage, } from "@aexhq/session-protocol";
 import { SessionError, abortError } from "./errors.js";
 import { randomIdempotencyKey } from "./json.js";
-export class SandboxFiles {
-    #inner;
-    #transport;
-    constructor(inner, transport) {
-        this.#inner = inner;
-        this.#transport = transport;
-    }
-    async list(path, options) {
-        const page = await this.#inner.list({
-            path,
-            generation: options.generation,
-            ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
-            ...(options.limit === undefined ? {} : { limit: options.limit }),
-        }, request(options));
-        return filePage(page);
-    }
-    async stat(path, options) {
-        return file(await this.#inner.stat({ path, generation: options.generation }, request(options)));
-    }
-    async download(path, options) {
-        return collect(await this.downloadStream(path, options));
-    }
-    async downloadStream(path, options) {
-        const entry = await this.#inner.stat({ path, generation: options.generation }, request(options));
-        if (entry.bytes <= MAX_INLINE_FILE_BYTES) {
-            const result = await this.#inner.readInline({ path, generation: options.generation }, request(options));
-            return byteStream(decodeBase64(result.content_base64));
-        }
-        const ticket = await this.#inner.prepareDownload({ path, generation: options.generation }, request(options));
-        return this.#transport.downloadTransferStream(ticket, options.signal, entry.bytes);
-    }
-    async upload(path, source, options) {
-        const base = {
-            path,
-            generation: options.generation,
-            ...(options.overwrite === undefined ? {} : { overwrite: options.overwrite }),
-        };
-        let entry;
-        if (isStreamingSource(source)) {
-            assertStreamingSource(source);
-            entry = source.bytes <= MAX_INLINE_FILE_BYTES
-                ? await this.#inner.writeInline({ ...base, content_base64: encodeBase64(await collectDeclared(source, options.signal)) }, request(options))
-                : await this.#uploadStream(base, source, options);
-        }
-        else {
-            const content = await bytesOf(source);
-            entry = content.byteLength <= MAX_INLINE_FILE_BYTES
-                ? await this.#inner.writeInline({ ...base, content_base64: encodeBase64(content) }, request(options))
-                : await this.#upload(base, content, options);
-        }
-        return file(entry);
-    }
-    async #upload(input, content, options) {
-        const ticket = await this.#inner.prepareUpload({ ...input, bytes: content.byteLength, sha256: await sha256(content) }, request(options));
-        await this.#transport.uploadTransfer(ticket, content, content.byteLength, options.signal);
-        // Direct sandbox transfers are intentionally happy-path only. Do not automatically replay an
-        // ambiguous import: surface the error so the caller can inspect the generation/path and
-        // prepare a fresh transfer. Durable storage completion has separate retry-safe semantics.
-        return this.#inner.completeUpload(ticket.transfer_id, request(options));
-    }
-    async #uploadStream(input, source, options) {
-        const ticket = await this.#inner.prepareUpload({ ...input, bytes: source.bytes, sha256: source.sha256 }, request(options));
-        await this.#transport.uploadTransfer(ticket, () => source.stream(), source.bytes, options.signal);
-        return this.#inner.completeUpload(ticket.transfer_id, request(options));
-    }
-    async find(input, options) {
-        const page = await this.#inner.find({
-            ...input,
-            generation: options.generation,
-            ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
-            ...(options.limit === undefined ? {} : { limit: options.limit }),
-        }, request(options));
-        return filePage(page);
-    }
-    async grep(input, options) {
-        const page = await this.#inner.grep({
-            ...input,
-            generation: options.generation,
-            ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
-            ...(options.limit === undefined ? {} : { limit: options.limit }),
-        }, request(options));
-        return filePage(page);
-    }
-}
-export class SessionSandbox {
-    #inner;
-    files;
-    constructor(transport, sessionId) {
-        this.#inner = new BrainSandbox(transport, sessionId);
-        this.files = new SandboxFiles(this.#inner.files, transport);
-    }
-    async status(options = {}) {
-        return sandboxStatus(await this.#inner.status(request(options)));
-    }
-    async create(options = {}) {
-        return sandboxStatus(await this.#inner.create(intrinsicRequest(options)));
-    }
-}
 export class SessionStorage {
     #inner;
     #transport;
-    constructor(transport, sessionId) {
+    #environmentNames;
+    constructor(transport, sessionId, environmentNames = new Map()) {
         this.#inner = new BrainStorage(transport, sessionId);
         this.#transport = transport;
+        this.#environmentNames = environmentNames;
     }
     async list(options = {}) {
         const page = await this.#inner.list({
@@ -158,22 +62,28 @@ export class SessionStorage {
     delete(key, options = {}) {
         return this.#inner.delete(key, request(options));
     }
-    async copyFromSandbox(input, options = {}) {
-        return storageObject(await this.#inner.copyFromSandbox({
+    async copyFromEnvironment(environment, input, options = {}) {
+        return storageObject(await this.#inner.copyFromEnvironment(this.#environmentName(environment), {
             key: input.key,
             path: input.path,
-            sandbox_generation: input.sandboxGeneration,
+            environment_generation: input.generation,
             ...(input.overwrite === undefined ? {} : { overwrite: input.overwrite }),
         }, request(options)));
     }
-    async copyToSandbox(input, options = {}) {
-        return file(await this.#inner.copyToSandbox({
+    async copyToEnvironment(environment, input, options = {}) {
+        return environmentFile(await this.#inner.copyToEnvironment(this.#environmentName(environment), {
             key: input.key,
             path: input.path,
-            sandbox_generation: input.sandboxGeneration,
+            environment_generation: input.generation,
             ...(input.overwrite === undefined ? {} : { overwrite: input.overwrite }),
         }, request(options)));
     }
+    #environmentName(environment) {
+        const name = this.#environmentNames.get(environment);
+        if (name === undefined)
+            throw new TypeError("EnvironmentRef does not belong to this Session");
+        return name;
+    }
 }
 export class SessionChild {
     #inner;
@@ -249,16 +159,7 @@ function idempotentRequest(options) {
         retry: true,
     };
 }
-function sandboxStatus(value) {
-    return {
-        state: value.state,
-        ...(value.generation == null ? {} : { generation: value.generation }),
-        ...(value.reason == null ? {} : { reason: value.reason }),
-        ...(value.changed_at_ms == null ? {} : { changedAt: timestamp(value.changed_at_ms) }),
-        ...(value.expires_at_ms == null ? {} : { expiresAt: timestamp(value.expires_at_ms) }),
-    };
-}
-function file(value) {
+function environmentFile(value) {
     return {
         path: value.path,
         kind: value.kind,
@@ -267,14 +168,6 @@ function file(value) {
         modifiedAt: timestamp(value.modified_at_ms),
     };
 }
-function filePage(value) {
-    return {
-        data: value.data.map(file),
-        hasMore: value.has_more,
-        ...(value.next_cursor === undefined ? {} : { nextCursor: value.next_cursor }),
-        generation: value.generation,
-    };
-}
 function storageObject(value) {
     return {
         key: value.key,
@@ -413,7 +306,7 @@ async function collectDeclared(source, signal) {
     }
     return result;
 }
-function encodeBase64(bytes) {
+export function encodeBase64(bytes) {
     let binary = "";
     for (let offset = 0; offset < bytes.byteLength; offset += 32_768) {
         binary += String.fromCharCode(...bytes.subarray(offset, offset + 32_768));

package/dist/session.d.ts

@@ -1,10 +1,11 @@
-import type { Event, Provider, Session as SessionData, SessionState } from "@aexhq/brain/session";
-import type { NetworkPolicy, WebSocketFactory } from "@aexhq/brain";
+import type { Event, Provider, Session as SessionData, SessionState } from "@aexhq/session-protocol/session";
+import { type EnvironmentRef, type HandleOf } from "@aexhq/environment";
+import type { NetworkPolicy, WebSocketFactory } from "@aexhq/session-protocol";
 import * as z from "zod";
 import type { EventOptions } from "./transport.js";
 import { Transport } from "./transport.js";
-import type { Tool } from "./tools.js";
-import { SessionChildren, SessionSandbox, SessionStorage } from "./resources.js";
+import type { EnvironmentMap, EnvironmentValue, ToolSelection } from "./tools.js";
+import { SessionChildren, SessionStorage } from "./resources.js";
 export type SessionInput = string;
 export interface ModelOptions {
     provider: Provider;
@@ -14,24 +15,33 @@ export interface ModelOptions {
     maxOutputTokens?: number;
     /** Immutable context capacity used for admission and compaction; Brain never guesses by name. */
     contextWindowTokens?: number;
-    temperature?: number;
-    reasoningEffort?: "low" | "medium" | "high";
 }
-export interface CreateSessionOptions {
+/**
+ * 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 Loop {
+    /** 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<Environments extends EnvironmentMap = EnvironmentMap> {
     model: ModelOptions;
+    /** The imported agent loop that drives this session and every child unless spawn overrides it. */
+    loop: Loop;
     /** Omitted or empty grants no tools. A non-empty list is the exact grant. */
-    tools?: readonly Tool[];
-    systemPrompt?: string;
+    environments?: Environments;
+    tools?: readonly ToolSelection<EnvironmentValue<Environments>>[];
     /** Write-only values for environment names declared by managed Tools. */
     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;
@@ -81,19 +91,19 @@ export interface SessionSummary {
 }
 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>;
+    create<Environments extends EnvironmentMap>(options: CreateSessionOptions<Environments>, request?: RequestOptions): Promise<Session<Environments>>;
     get(id: string, options?: Pick<RequestOptions, "signal">): Promise<Session>;
     list(options?: ListSessionsOptions): Promise<SessionList>;
 }
-export declare class Session implements SessionSummary {
+export declare class Session<Environments extends EnvironmentMap = EnvironmentMap> implements SessionSummary {
     #private;
-    readonly sandbox: SessionSandbox;
     readonly storage: SessionStorage;
     readonly children: SessionChildren;
-    constructor(transport: Transport, data: SessionData);
+    constructor(transport: Transport, data: SessionData, environmentNames?: ReadonlyMap<EnvironmentRef, string>);
+    environment<Environment extends EnvironmentValue<Environments>>(environment: Environment): HandleOf<Environment>;
     get id(): string;
     get state(): SessionState;
     get turnState(): SessionData["turn_state"];