@aexhq/sdk 0.58.0 → 0.59.0

package/README.md

@@ -6,55 +6,58 @@ TypeScript SDK for Aex sessions and tool extensions.
 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";
+import { openai } from "@aexhq/model-openai";
+import { bash, read, task, write } from "@aexhq/tools";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
 const workspace = awsMicrovm();
 
 const session = await aex.sessions.create({
   model: {
+    component: openai(),
     provider: "openai",
     name: "gpt-5.4",
     apiKey: process.env.OPENAI_API_KEY!,
   },
-  loop: pi({ instructions: "Work carefully and verify changes." }),
+  agentloop: pi({ instructions: "Work carefully and verify changes." }),
   environments: { workspace },
-  tools: [bash(), read(), write()],
+  tools: [bash(), read(), write(), task()],
 });
 
 console.log(await session.send("Inspect the workspace."));
 ```
 
-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.
+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
+## Application Tools
 
-`tool()` creates an immutable tool extension from a Zod input schema and a handler:
+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 { tool } from "@aexhq/sdk";
+import { Aex, tool } from "@aexhq/sdk";
+import { app } from "@aexhq/env-app";
 import { z } from "zod";
 
-export default tool(
+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() }))
-  .needs({ env: ["ORDERS_TOKEN"], network: [{ host: "orders.example.com", port: 443 }] })
-  .setup(async function prepareIndex() {
-    await database.prepareIndex();
-  });
-```
+  .returns(z.object({ status: z.string() }));
 
-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 new Aex({ apiKey: process.env.AEX_API_KEY! }).sessions.create({
+  model,
+  agentloop,
+  environments: { application: app({ id: "orders-ui" }) },
+  tools: [lookupOrder],
+});
+```
 
-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.
+Source callback Tools are routed automatically to the single `app()` Environment. 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/session-protocol/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;

package/dist/index.d.ts

@@ -1,17 +1,16 @@
 import { Sessions } from "./session.js";
 import type { Fetch } from "./transport.js";
-import type { WebSocketFactory } from "@aexhq/session-protocol";
+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 { CreateSessionOptions, ListSessionsOptions, Loop, ModelSummary, ModelOptions, OutputOptions, RequestOptions, SessionInput, SessionList, SessionSummary, } from "./session.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, EnvironmentFile, IdempotentOperationOptions, OperationOptions, PageOptions, StorageObject, StoragePage, StreamingUploadSource, UploadSource, } 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 "./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 type { Tool, ToolContract, ToolContext, ToolHandler, } from "./tools.js";
+export type { NetworkPolicy, WebSocketFactory } from "@aexhq/brain";
 export interface AexOptions {
     apiKey: string;
     baseUrl?: string;

package/dist/resources.d.ts

@@ -1,7 +1,6 @@
-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 { 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 type { EventOptions } from "./transport.js";
 import { Transport } from "./transport.js";
 export type BinarySource = string | ArrayBuffer | ArrayBufferView | Blob;
@@ -23,13 +22,57 @@ export interface PageOptions extends OperationOptions {
     cursor?: string;
     limit?: number;
 }
-export interface EnvironmentFile {
+export interface SandboxStatus {
+    state: BrainSandboxStatus["state"];
+    generation?: string;
+    reason?: string;
+    changedAt?: string;
+    expiresAt?: string;
+}
+export interface SandboxFile {
     path: string;
-    kind: BrainEnvironmentFileEntry["kind"];
+    kind: BrainSandboxFileEntry["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;
@@ -45,7 +88,7 @@ export interface StoragePage {
 }
 export declare class SessionStorage {
     #private;
-    constructor(transport: Transport, sessionId: string, environmentNames?: ReadonlyMap<EnvironmentRef, string>);
+    constructor(transport: Transport, sessionId: string);
     list(options?: PageOptions & {
         prefix?: string;
     }): Promise<StoragePage>;
@@ -57,18 +100,20 @@ export declare class SessionStorage {
         overwrite?: boolean;
     }): Promise<StorageObject>;
     delete(key: string, options?: OperationOptions): Promise<void>;
-    copyFromEnvironment(environment: EnvironmentRef, input: {
+    copyFromSandbox(input: {
+        environment: string;
         key: string;
         path: string;
-        generation: string;
+        sandboxGeneration: string;
         overwrite?: boolean;
     }, options?: OperationOptions): Promise<StorageObject>;
-    copyToEnvironment(environment: EnvironmentRef, input: {
+    copyToSandbox(input: {
+        environment: string;
         key: string;
         path: string;
-        generation: string;
+        sandboxGeneration: string;
         overwrite?: boolean;
-    }, options?: OperationOptions): Promise<EnvironmentFile>;
+    }, options?: OperationOptions): Promise<SandboxFile>;
 }
 export interface ChildSummary {
     id: string;

package/dist/resources.js

@@ -1,14 +1,110 @@
-import { MAX_INLINE_FILE_BYTES, SessionChildren as BrainChildren, SessionStorage as BrainStorage, } from "@aexhq/session-protocol";
+import { MAX_INLINE_FILE_BYTES, SessionChildren as BrainChildren, SessionSandbox as BrainSandbox, SessionStorage as BrainStorage, } from "@aexhq/brain";
 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;
-    #environmentNames;
-    constructor(transport, sessionId, environmentNames = new Map()) {
+    constructor(transport, sessionId) {
         this.#inner = new BrainStorage(transport, sessionId);
         this.#transport = transport;
-        this.#environmentNames = environmentNames;
     }
     async list(options = {}) {
         const page = await this.#inner.list({
@@ -62,28 +158,22 @@ export class SessionStorage {
     delete(key, options = {}) {
         return this.#inner.delete(key, request(options));
     }
-    async copyFromEnvironment(environment, input, options = {}) {
-        return storageObject(await this.#inner.copyFromEnvironment(this.#environmentName(environment), {
+    async copyFromSandbox(input, options = {}) {
+        return storageObject(await this.#inner.copyFromEnvironment(input.environment, {
             key: input.key,
             path: input.path,
-            environment_generation: input.generation,
+            environment_generation: input.sandboxGeneration,
             ...(input.overwrite === undefined ? {} : { overwrite: input.overwrite }),
         }, request(options)));
     }
-    async copyToEnvironment(environment, input, options = {}) {
-        return environmentFile(await this.#inner.copyToEnvironment(this.#environmentName(environment), {
+    async copyToSandbox(input, options = {}) {
+        return file(await this.#inner.copyToEnvironment(input.environment, {
             key: input.key,
             path: input.path,
-            environment_generation: input.generation,
+            environment_generation: input.sandboxGeneration,
             ...(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;
@@ -159,7 +249,16 @@ function idempotentRequest(options) {
         retry: true,
     };
 }
-function environmentFile(value) {
+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) {
     return {
         path: value.path,
         kind: value.kind,
@@ -168,6 +267,14 @@ function environmentFile(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,

package/dist/session.d.ts

@@ -1,42 +1,32 @@
-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 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 { EnvironmentMap, EnvironmentValue, ToolSelection } from "./tools.js";
-import { SessionChildren, SessionStorage } from "./resources.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;
 }
-/**
- * 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> {
+export interface CreateSessionOptions {
     model: ModelOptions;
     /** The imported agent loop that drives this session and every child unless spawn overrides it. */
-    loop: Loop;
+    agentloop: ComponentExtension<"agentloop">;
     /** Omitted or empty grants no tools. A non-empty list is the exact grant. */
-    environments?: Environments;
-    tools?: readonly ToolSelection<EnvironmentValue<Environments>>[];
-    /** 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;
@@ -49,6 +39,8 @@ export interface CreateSessionOptions<Environments extends EnvironmentMap = Envi
         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;
@@ -72,7 +64,7 @@ export interface SessionList {
     nextCursor?: string;
 }
 export interface ModelSummary {
-    provider: Provider;
+    provider: string;
     name: string;
     baseUrl?: string;
     contextWindowTokens: number;
@@ -87,6 +79,7 @@ export interface SessionSummary {
     model: ModelSummary;
     createdAt: string;
     updatedAt: string;
+    retainUntil: string;
     metadata: Readonly<Record<string, string | undefined>>;
 }
 export declare class Sessions {
@@ -94,16 +87,16 @@ export declare class Sessions {
     constructor(transport: Transport, webSocketFactory?: WebSocketFactory);
     /** @internal Called by `Aex.close()`. */
     close(): void;
-    create<Environments extends EnvironmentMap>(options: CreateSessionOptions<Environments>, request?: RequestOptions): Promise<Session<Environments>>;
+    create(options: CreateSessionOptions, request?: RequestOptions): Promise<Session>;
     get(id: string, options?: Pick<RequestOptions, "signal">): Promise<Session>;
     list(options?: ListSessionsOptions): Promise<SessionList>;
 }
-export declare class Session<Environments extends EnvironmentMap = EnvironmentMap> implements SessionSummary {
+export declare class Session implements SessionSummary {
     #private;
+    readonly sandbox: SessionSandbox;
     readonly storage: SessionStorage;
     readonly children: SessionChildren;
-    constructor(transport: Transport, data: SessionData, environmentNames?: ReadonlyMap<EnvironmentRef, string>);
-    environment<Environment extends EnvironmentValue<Environments>>(environment: Environment): HandleOf<Environment>;
+    constructor(transport: Transport, data: SessionData);
     get id(): string;
     get state(): SessionState;
     get turnState(): SessionData["turn_state"];
@@ -113,6 +106,7 @@ export declare class Session<Environments extends EnvironmentMap = EnvironmentMa
     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>;
@@ -124,9 +118,15 @@ export declare class Session<Environments extends EnvironmentMap = EnvironmentMa
      */
     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 {};