@aexhq/sdk 0.57.5 → 0.58.0

package/dist/session.js

@@ -1,38 +1,38 @@
-import { CustomerHand } from "@aexhq/brain";
+import { CustomerEnvironment } from "@aexhq/session-protocol";
+import { inspectEnvironment } from "@aexhq/environment";
 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 { encodeBase64, SessionChildren, 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 environment of this.#customerEnvironmentInstances.values())
+            environment.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 } })");
-        }
-        await this.#ensureCustomerHand(compiledTools.clientRegistrations, request.signal);
+        if (options.loop === undefined)
+            throw new TypeError("sessions.create requires an imported loop");
+        const compiledTools = await compileTools(options.tools, options.environments, options.secrets);
+        await Promise.all(compiledTools.layers.map((layer) => this.#transport.ensureArtifactLayer(layer.checksum, layer.media_type, layer.content, request.signal)));
+        await this.#ensureCustomerEnvironment(compiledTools.callbackClientId, compiledTools.clientRegistrations, request.signal);
         const body = {
             model: {
                 provider: options.model.provider,
@@ -45,26 +45,20 @@ export class Sessions {
                 ...(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,
             },
-            ...(compiledTools.bundles.length === 0 ? {} : { tool_bundles: compiledTools.bundles }),
-            ...(options.agentloop === undefined
+            ...(Object.keys(compiledTools.environments).length === 0
                 ? {}
-                : {
-                    agentloop: {
-                        source_bundle_sha256: options.agentloop.sha256,
-                        toolchain: options.agentloop.toolchain,
-                        bundle_base64: encodeBase64(new TextEncoder().encode(options.agentloop.source)),
-                    },
-                }),
+                : { environments: compiledTools.environments }),
+            ...(compiledTools.bundles.length === 0 ? {} : { tool_bundles: compiledTools.bundles }),
+            agentloop: {
+                source_bundle_sha256: options.loop.sha256,
+                toolchain: options.loop.toolchain,
+                bundle_base64: encodeBase64(new TextEncoder().encode(options.loop.source)),
+            },
             ...(options.secrets === undefined ? {} : { secrets: options.secrets }),
-            ...(options.systemPrompt === undefined ? {} : { system_prompt: options.systemPrompt }),
             ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
             ...(options.network === undefined
                 ? {}
@@ -72,14 +66,11 @@ export class Sessions {
             ...(options.providerRecoveryRetries === undefined
                 ? {}
                 : { provider_recovery_retries: options.providerRecoveryRetries }),
-            ...(this.#clientId === undefined
+            ...(compiledTools.callbackClientId === undefined
                 ? {}
                 : {
                     client: {
-                        id: this.#clientId,
-                        ...(options.client?.submitRetries === undefined
-                            ? {}
-                            : { submit_retries: options.client.submitRetries }),
+                        id: compiledTools.callbackClientId,
                     },
                 }),
             ...(options.children === undefined
@@ -104,7 +95,7 @@ export class Sessions {
             signal: request.signal,
             retry: true,
         });
-        return new Session(this.#transport, data);
+        return new Session(this.#transport, data, compiledTools.environmentNames);
     }
     async get(id, options = {}) {
         const data = await this.#transport.json("GET", `/v1/sessions/${encodeURIComponent(id)}`, { signal: options.signal });
@@ -128,29 +119,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 +154,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,10 +168,10 @@ export class Sessions {
             await waitWithSignal(starting, signal);
             return;
         }
-        const hand = await waitWithSignal(this.#customerHand, signal);
+        const environment = await waitWithSignal(existing, signal);
         if (this.#closed)
             throw new SessionError("Aex client is closed");
-        await waitWithSignal(hand.register(registrations), signal);
+        await waitWithSignal(environment.register(registrations), signal);
     }
 }
 function waitWithSignal(promise, signal) {
@@ -200,16 +192,32 @@ function waitWithSignal(promise, signal) {
 export class Session {
     #transport;
     #data;
-    sandbox;
     storage;
     children;
-    constructor(transport, data) {
+    #environmentNames;
+    #environmentHandles = new Map();
+    constructor(transport, data, environmentNames = new Map()) {
         this.#transport = transport;
         this.#data = data;
-        this.sandbox = new SessionSandbox(transport, data.id);
-        this.storage = new SessionStorage(transport, data.id);
+        this.#environmentNames = environmentNames;
+        this.storage = new SessionStorage(transport, data.id, environmentNames);
         this.children = new SessionChildren(transport, data.id);
     }
+    environment(environment) {
+        const name = this.#environmentNames.get(environment);
+        if (name === undefined)
+            throw new TypeError("EnvironmentRef does not belong to this Session");
+        const existing = this.#environmentHandles.get(environment);
+        if (existing !== undefined)
+            return existing;
+        const handle = inspectEnvironment(environment).createHandle({
+            sessionId: this.id,
+            environment: name,
+            request: async (method, path, body) => await this.#transport.json(method, path, body === undefined ? {} : { body }),
+        });
+        this.#environmentHandles.set(environment, handle);
+        return handle;
+    }
     get id() {
         return this.#data.id;
     }

package/dist/tools.d.ts

@@ -1,2 +1,100 @@
-export { compileTools } from "@aexhq/brain";
-export type { ClientRegistration, CompiledTools, Tool } from "@aexhq/brain";
+import { type ComputerProfile, type EnvironmentRef } from "@aexhq/environment";
+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;
+    readonly workspace?: string;
+}
+export type ToolHandler<Input extends z.ZodType, Output = unknown> = (input: z.output<Input>, context: ToolContext) => Output | Promise<Output>;
+export type ToolSetupHandler = () => void | Promise<void>;
+export interface ToolRequirements {
+    readonly env?: readonly string[];
+    readonly workspace?: boolean;
+    readonly processes?: boolean;
+    readonly network?: readonly {
+        readonly host: string;
+        readonly port: number;
+    }[];
+    readonly streaming?: boolean;
+    readonly recovery?: "retained" | "connection" | "replay-safe";
+}
+export interface PreparedArtifact {
+    readonly digest: string;
+    readonly target: ComputerProfile["platform"];
+    readonly bytes: number;
+    readonly execute: string;
+    readonly setup?: string;
+    readonly layers: readonly PreparedArtifactLayer[];
+}
+export interface PreparedArtifactLayer {
+    readonly digest: string;
+    readonly bytes: number;
+    readonly mediaType: "application/javascript+esm" | "application/x-xz";
+    readonly mountPath: string;
+    readonly unpack: "file" | "tar.xz";
+    readonly source: URL;
+}
+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 requirements: ToolRequirements;
+    readonly handler: ToolHandler<Input, Output>;
+    readonly setupHandler?: ToolSetupHandler;
+    readonly artifact?: PreparedArtifact;
+    describe(description: string): Tool<Input, Output>;
+    named(name: string): Tool<Input, Output>;
+    returns<Schema extends z.ZodType>(schema: Schema): Tool<Input, z.output<Schema>>;
+    needs(requirements: ToolRequirements): Tool<Input, Output>;
+    setup(handler: ToolSetupHandler): Tool<Input, Output>;
+    bind<Environment extends EnvironmentRef>(environment: Environment): BoundTool<Environment, Input, Output>;
+}
+export interface BoundTool<Environment extends EnvironmentRef = EnvironmentRef, Input extends z.ZodType = z.ZodType, Output = unknown> {
+    readonly kind: "aex.bound-tool";
+    readonly tool: Tool<Input, Output>;
+    readonly environment: Environment;
+}
+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 declare function withPreparedArtifact<Input extends z.ZodType, Output>(value: Tool<Input, Output>, artifact: PreparedArtifact): Tool<Input, Output>;
+export type EnvironmentMap = Record<string, EnvironmentRef>;
+export type EnvironmentValue<Environments extends EnvironmentMap> = Environments[keyof Environments];
+export type ToolSelection<Environment extends EnvironmentRef = EnvironmentRef> = Tool | BoundTool<Environment>;
+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 CompiledTools {
+    readonly items: readonly unknown[];
+    readonly bundles: readonly unknown[];
+    readonly layers: readonly CompiledArtifactLayer[];
+    readonly clientRegistrations: readonly ClientRegistration[];
+    readonly environments: Readonly<Record<string, unknown>>;
+    readonly environmentNames: ReadonlyMap<EnvironmentRef, string>;
+    readonly callbackClientId?: string;
+}
+export interface CompiledArtifactLayer {
+    readonly checksum: string;
+    readonly bytes: number;
+    readonly media_type: string;
+    readonly content: Uint8Array;
+}
+export declare function compileTools(selections: readonly ToolSelection[] | undefined, declared: EnvironmentMap | undefined, secrets?: Readonly<Record<string, string>>): Promise<CompiledTools>;
+export {};