@aexhq/sdk 0.57.5 → 0.58.0

package/dist/tools.js

@@ -1 +1,424 @@
-export { compileTools } from "@aexhq/brain";
+import { inspectEnvironment, isEnvironmentRef, } from "@aexhq/environment";
+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;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+const SHA256 = /^[0-9a-f]{64}$/u;
+export function tool(inputOrHandler, maybeHandler) {
+    if (typeof inputOrHandler === "function") {
+        return makeTool({
+            ...(inputOrHandler.name === "" ? {} : { name: inputOrHandler.name }),
+            input: EMPTY_INPUT,
+            handler: inputOrHandler,
+            requirements: Object.freeze({}),
+        });
+    }
+    if (typeof maybeHandler !== "function")
+        throw new TypeError("tool(schema, handler) requires a function");
+    return makeTool({
+        ...(maybeHandler.name === "" ? {} : { name: maybeHandler.name }),
+        input: inputOrHandler,
+        handler: maybeHandler,
+        requirements: Object.freeze({}),
+    });
+}
+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 }),
+        requirements: draft.requirements,
+        handler: draft.handler,
+        ...(draft.setupHandler === undefined ? {} : { setupHandler: draft.setupHandler }),
+        ...(draft.artifact === undefined ? {} : { artifact: draft.artifact }),
+        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 });
+        },
+        needs(requirements) {
+            return makeTool({ ...draft, requirements: normalizeRequirements(requirements) });
+        },
+        setup(handler) {
+            if (typeof handler !== "function")
+                throw new TypeError("Tool setup requires a function");
+            return makeTool({ ...draft, setupHandler: handler });
+        },
+        bind(environment) {
+            if (!isEnvironmentRef(environment))
+                throw new TypeError("Tool binding requires an EnvironmentRef");
+            return Object.freeze({ kind: "aex.bound-tool", tool: makeTool(draft), environment });
+        },
+    });
+}
+export function withPreparedArtifact(value, artifact) {
+    assertTool(value);
+    assertArtifact(artifact);
+    return makeTool({
+        ...(value.name === undefined ? {} : { name: value.name }),
+        ...(value.description === undefined ? {} : { description: value.description }),
+        input: value.input,
+        ...(value.output === undefined ? {} : { output: value.output }),
+        requirements: value.requirements,
+        handler: value.handler,
+        ...(value.setupHandler === undefined ? {} : { setupHandler: value.setupHandler }),
+        artifact: Object.freeze({
+            ...artifact,
+            layers: Object.freeze(artifact.layers.map((layer) => Object.freeze({ ...layer }))),
+        }),
+    });
+}
+export async function compileTools(selections, declared, secrets = {}) {
+    const environments = normalizeEnvironments(declared);
+    const selected = [...(selections ?? [])];
+    if (selected.length > 0 && environments.byName.size === 0) {
+        throw new TypeError("Tools require at least one declared environment");
+    }
+    const items = [];
+    const bundles = new Map();
+    const layers = new Map();
+    const registrations = [];
+    const names = new Set();
+    let callbackClientId;
+    for (const selection of selected) {
+        const value = selection.kind === "aex.bound-tool" ? selection.tool : selection;
+        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 explicit = selection.kind === "aex.bound-tool" ? selection.environment : undefined;
+        const environment = chooseEnvironment(contract.name, value, explicit, environments);
+        const environmentName = environments.byRef.get(environment);
+        const environmentProfile = inspectEnvironment(environment).serialized.profile;
+        for (const key of value.requirements.env ?? []) {
+            if (!(key in secrets))
+                throw new TypeError(`Tool ${JSON.stringify(contract.name)} requires missing secret ${JSON.stringify(key)}`);
+        }
+        const definition = {
+            name: contract.name,
+            ...(contract.description === undefined ? {} : { description: contract.description }),
+            input_schema: contract.inputSchema,
+            output_schema: contract.outputSchema ?? {},
+            contract_digest: contract.contractDigest,
+        };
+        if (environmentProfile.kind === "callbacks") {
+            const descriptor = inspectEnvironment(environment).serialized;
+            const id = descriptor.configuration.id;
+            if (typeof id !== "string" || id.trim() === "") {
+                throw new TypeError(`Callback environment ${JSON.stringify(environmentName)} must serialize a non-empty id`);
+            }
+            if (callbackClientId !== undefined && callbackClientId !== id) {
+                throw new TypeError("A session currently supports one callback process id");
+            }
+            callbackClientId = id;
+            const registration = `tool:${contract.contractDigest}`;
+            registrations.push(Object.freeze({
+                registration,
+                name: contract.name,
+                contractDigest: contract.contractDigest,
+                input: value.input,
+                ...(value.output === undefined ? {} : { output: value.output }),
+                handler: value.handler,
+            }));
+            items.push({
+                definition,
+                executor: {
+                    kind: "environment",
+                    environment: environmentName,
+                    callback_registration: registration,
+                    requirements: wireRequirements(value.requirements),
+                },
+            });
+            continue;
+        }
+        if (value.artifact === undefined) {
+            throw new TypeError(`Tool ${JSON.stringify(contract.name)} has no prepared computer artifact`);
+        }
+        assertArtifact(value.artifact);
+        const layerRefs = [];
+        for (const layer of value.artifact.layers) {
+            const bytes = await readArtifactLayer(layer);
+            const existing = layers.get(layer.digest);
+            const payload = {
+                checksum: layer.digest,
+                bytes: layer.bytes,
+                media_type: layer.mediaType,
+                content: bytes,
+            };
+            if (existing !== undefined &&
+                (existing.bytes !== payload.bytes || existing.media_type !== payload.media_type)) {
+                throw new TypeError(`Prepared artifact layer ${layer.digest} conflicts with an earlier layer`);
+            }
+            layers.set(layer.digest, payload);
+            layerRefs.push({
+                checksum: layer.digest,
+                bytes: layer.bytes,
+                media_type: layer.mediaType,
+                mount_path: layer.mountPath,
+                unpack: layer.unpack,
+            });
+        }
+        const manifest = {
+            checksum: value.artifact.digest,
+            bytes: value.artifact.bytes,
+            target: value.artifact.target,
+            execute_path: value.artifact.execute,
+            ...(value.artifact.setup === undefined ? {} : { setup_path: value.artifact.setup }),
+            layers: layerRefs,
+        };
+        const manifestIdentity = {
+            profile: "computer/v1",
+            target: value.artifact.target,
+            execute_path: value.artifact.execute,
+            setup_path: value.artifact.setup ?? null,
+            layers: layerRefs,
+        };
+        if (await jcsSha256(manifestIdentity) !== value.artifact.digest) {
+            throw new TypeError(`Prepared artifact ${value.artifact.digest} manifest digest changed`);
+        }
+        const existingManifest = bundles.get(value.artifact.digest);
+        if (existingManifest !== undefined && JSON.stringify(existingManifest) !== JSON.stringify(manifest)) {
+            throw new TypeError(`Prepared artifact ${value.artifact.digest} conflicts with an earlier manifest`);
+        }
+        bundles.set(value.artifact.digest, manifest);
+        items.push({
+            definition,
+            executor: {
+                kind: "environment",
+                environment: environmentName,
+                artifact_digest: value.artifact.digest,
+                requirements: wireRequirements(value.requirements),
+            },
+        });
+    }
+    return {
+        items: Object.freeze(items),
+        bundles: Object.freeze([...bundles.values()]),
+        layers: Object.freeze([...layers.values()]),
+        clientRegistrations: Object.freeze(registrations),
+        environments: environments.serialized,
+        environmentNames: environments.byRef,
+        ...(callbackClientId === undefined ? {} : { callbackClientId }),
+    };
+}
+function normalizeEnvironments(declared) {
+    const byName = new Map();
+    const byRef = new Map();
+    const serialized = Object.create(null);
+    for (const [name, environment] of Object.entries(declared ?? {})) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(name)) {
+            throw new TypeError(`Invalid environment name ${JSON.stringify(name)}`);
+        }
+        if (!isEnvironmentRef(environment))
+            throw new TypeError(`Environment ${JSON.stringify(name)} is not an EnvironmentRef`);
+        const previous = byRef.get(environment);
+        if (previous !== undefined) {
+            throw new TypeError(`The same EnvironmentRef was declared as ${JSON.stringify(previous)} and ${JSON.stringify(name)}`);
+        }
+        byName.set(name, environment);
+        byRef.set(environment, name);
+        serialized[name] = inspectEnvironment(environment).serialized;
+    }
+    return { byName, byRef, serialized: Object.freeze(serialized) };
+}
+function chooseEnvironment(toolName, value, explicit, environments) {
+    if (explicit !== undefined) {
+        const name = environments.byRef.get(explicit);
+        if (name === undefined)
+            throw new TypeError(`Tool ${JSON.stringify(toolName)} is bound to an environment absent from environments`);
+        const reasons = incompatibilities(value, inspectEnvironment(explicit).serialized.profile);
+        if (reasons.length > 0) {
+            throw new TypeError(`Tool ${JSON.stringify(toolName)} is bound to ${JSON.stringify(name)}, which ${reasons.join(" and ")}`);
+        }
+        return explicit;
+    }
+    const matches = [];
+    const failures = [];
+    for (const [name, environment] of environments.byName) {
+        const reasons = incompatibilities(value, inspectEnvironment(environment).serialized.profile);
+        if (reasons.length === 0)
+            matches.push(environment);
+        else
+            failures.push(`- ${JSON.stringify(name)} ${reasons.join(" and ")}`);
+    }
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0) {
+        throw new TypeError(`Tool ${JSON.stringify(toolName)} has no compatible environment:\n${failures.join("\n")}`);
+    }
+    const names = matches.map((environment) => JSON.stringify(environments.byRef.get(environment))).join(", ");
+    throw new TypeError(`Tool ${JSON.stringify(toolName)} matches more than one environment: ${names}. Bind it explicitly.`);
+}
+function incompatibilities(value, profile) {
+    const reasons = [];
+    if (profile.kind === "computer") {
+        if (value.artifact === undefined || profile.platform !== value.artifact.target) {
+            reasons.push(`cannot launch target ${JSON.stringify(value.artifact?.target ?? "application-callback")}`);
+        }
+    }
+    else {
+        if (value.artifact !== undefined)
+            reasons.push("does not run prepared artifacts");
+        if (value.setupHandler !== undefined)
+            reasons.push("does not provide tool setup");
+    }
+    const needs = value.requirements;
+    if (needs.workspace === true && profile.kind !== "computer")
+        reasons.push("is missing workspace");
+    if (needs.processes === true && profile.kind !== "computer")
+        reasons.push("is missing processes");
+    if (needs.network !== undefined && needs.network.length > 0 && profile.network !== "allowlist") {
+        reasons.push("cannot enforce network allowlists");
+    }
+    if (needs.recovery !== undefined && needs.recovery !== profile.recovery) {
+        reasons.push(`provides ${profile.recovery} recovery instead of ${needs.recovery}`);
+    }
+    return reasons;
+}
+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 wireRequirements(requirements) {
+    return {
+        ...(requirements.env === undefined ? {} : { env: [...requirements.env] }),
+        ...(requirements.workspace === undefined ? {} : { workspace: requirements.workspace }),
+        ...(requirements.processes === undefined ? {} : { processes: requirements.processes }),
+        ...(requirements.network === undefined
+            ? {}
+            : { network: requirements.network.map(({ host, port }) => ({ host, ports: [port], protocol: "tls" })) }),
+        ...(requirements.streaming === undefined ? {} : { streaming: requirements.streaming }),
+        ...(requirements.recovery === undefined
+            ? {}
+            : { recovery: requirements.recovery === "replay-safe" ? "replay_safe" : requirements.recovery }),
+    };
+}
+function normalizeRequirements(requirements) {
+    const env = [...(requirements.env ?? [])];
+    if (new Set(env).size !== env.length)
+        throw new TypeError("Tool environment requirements contain duplicates");
+    for (const key of env)
+        if (!ENV_NAME.test(key))
+            throw new TypeError(`Invalid required environment name ${JSON.stringify(key)}`);
+    const network = [...(requirements.network ?? [])];
+    if (network.length > 32)
+        throw new TypeError("Tool network requirements exceed 32 destinations");
+    for (const destination of network) {
+        if (destination.host.trim() === "" || destination.host.length > 253)
+            throw new TypeError("Invalid tool network host");
+        if (!Number.isInteger(destination.port) || destination.port < 1 || destination.port > 65535) {
+            throw new TypeError("Invalid tool network port");
+        }
+    }
+    return Object.freeze({
+        ...(env.length === 0 ? {} : { env: Object.freeze(env) }),
+        ...(requirements.workspace === undefined ? {} : { workspace: requirements.workspace }),
+        ...(requirements.processes === undefined ? {} : { processes: requirements.processes }),
+        ...(network.length === 0 ? {} : { network: Object.freeze(network.map((item) => Object.freeze({ ...item }))) }),
+        ...(requirements.streaming === undefined ? {} : { streaming: requirements.streaming }),
+        ...(requirements.recovery === undefined ? {} : { recovery: requirements.recovery }),
+    });
+}
+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)}`);
+}
+function assertArtifact(artifact) {
+    if (!SHA256.test(artifact.digest))
+        throw new TypeError("Prepared artifact digest must be lower-case SHA-256 hex");
+    if (!Number.isSafeInteger(artifact.bytes) || artifact.bytes < 1)
+        throw new TypeError("Prepared artifact bytes are invalid");
+    if (!artifact.execute.startsWith("/"))
+        throw new TypeError("Prepared artifact execute entrypoint must be absolute");
+    if (artifact.setup !== undefined && !artifact.setup.startsWith("/")) {
+        throw new TypeError("Prepared artifact setup entrypoint must be absolute");
+    }
+    if (!Array.isArray(artifact.layers) || artifact.layers.length === 0) {
+        throw new TypeError("Prepared artifact must contain at least one immutable layer");
+    }
+    let bytes = 0;
+    for (const layer of artifact.layers) {
+        if (!SHA256.test(layer.digest))
+            throw new TypeError("Prepared artifact layer digest must be lower-case SHA-256 hex");
+        if (!Number.isSafeInteger(layer.bytes) || layer.bytes < 1)
+            throw new TypeError("Prepared artifact layer bytes are invalid");
+        if (!(layer.source instanceof URL))
+            throw new TypeError("Prepared artifact layer source must be a URL");
+        if (!layer.mountPath.startsWith("/"))
+            throw new TypeError("Prepared artifact layer mount path must be absolute");
+        bytes += layer.bytes;
+    }
+    if (bytes !== artifact.bytes)
+        throw new TypeError("Prepared artifact bytes do not equal its layers");
+}
+async function readArtifactLayer(layer) {
+    let bytes;
+    if (layer.source.protocol === "file:") {
+        const { readFile } = await import("node:fs/promises");
+        bytes = await readFile(layer.source);
+    }
+    else if (layer.source.protocol === "https:" || layer.source.protocol === "data:") {
+        const response = await fetch(layer.source);
+        if (!response.ok)
+            throw new TypeError(`Could not read artifact layer ${layer.digest}: HTTP ${response.status}`);
+        bytes = new Uint8Array(await response.arrayBuffer());
+    }
+    else {
+        throw new TypeError(`Unsupported artifact layer source protocol ${layer.source.protocol}`);
+    }
+    if (bytes.byteLength !== layer.bytes)
+        throw new TypeError(`Artifact layer ${layer.digest} byte length changed`);
+    const actual = await sha256(bytes);
+    if (actual !== layer.digest)
+        throw new TypeError(`Artifact layer ${layer.digest} content digest changed`);
+    return bytes;
+}
+async function sha256(bytes) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", Uint8Array.from(bytes).buffer);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
-import type { Event } from "@aexhq/brain/session";
-import type { JsonRequestOptions, TransferTicket } from "@aexhq/brain";
+import type { Event } from "@aexhq/session-protocol/session";
+import type { JsonRequestOptions, TransferTicket } from "@aexhq/session-protocol";
 export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export interface EventOptions {
     after?: number;
@@ -10,17 +10,18 @@ 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>;
+    ensureArtifactLayer(digest: string, mediaType: string, content: Uint8Array, signal?: AbortSignal): Promise<void>;
     json<T>(method: "GET" | "POST" | "DELETE", path: string, options?: JsonRequestOptions): Promise<T>;
     /** Accept one durable deletion job; strict callers poll its short status resource client-side. */
     deleteSession(sessionId: string, waitForCompletion: boolean, signal?: AbortSignal): Promise<void>;

package/dist/transport.js

@@ -1,8 +1,8 @@
-import { MAX_CREATE_SESSION_REQUEST_BYTES, MAX_CUSTOMER_OBSERVATION_BYTES, MAX_MESSAGE_REQUEST_BYTES, MAX_PUBLIC_EVENT_BYTES, } from "@aexhq/brain";
+import { MAX_CREATE_SESSION_REQUEST_BYTES, MAX_CUSTOMER_OBSERVATION_BYTES, MAX_MESSAGE_REQUEST_BYTES, MAX_PUBLIC_EVENT_BYTES, } from "@aexhq/session-protocol";
 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);
@@ -127,6 +127,38 @@ export class Transport {
             });
         }
     }
+    async ensureArtifactLayer(digest, mediaType, content, signal) {
+        const path = `/v1/artifacts/${encodeURIComponent(digest)}`;
+        const authorization = `Bearer ${this.#apiKey}`;
+        const existing = await this.#fetch(`${this.baseUrl}${path}`, {
+            method: "HEAD",
+            redirect: "error",
+            headers: { Authorization: authorization },
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (existing.ok) {
+            const bytes = Number(existing.headers.get("content-length"));
+            const storedMediaType = existing.headers.get("content-type");
+            if (bytes !== content.byteLength || storedMediaType !== mediaType) {
+                throw new SessionError(`Uploaded Tool artifact ${digest} has conflicting metadata`);
+            }
+            return;
+        }
+        if (existing.status !== 404)
+            throw await this.responseError(existing);
+        const uploaded = await this.#fetch(`${this.baseUrl}${path}`, {
+            method: "PUT",
+            redirect: "error",
+            headers: {
+                Authorization: authorization,
+                "Content-Type": mediaType,
+            },
+            body: arrayBufferBody(content),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (!uploaded.ok)
+            throw await this.responseError(uploaded);
+    }
     async json(method, path, options = {}) {
         const attempts = options.retry === true ? 2 : 1;
         // Serialize once before the first await. A caller mutating its source object after a lost
@@ -419,7 +451,7 @@ 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");
     }
@@ -435,7 +467,7 @@ 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 });
@@ -447,7 +479,7 @@ function validateCustomerHandGrant(baseUrl, grant) {
         throw new SessionError("Aex customer Hand 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.58.0",
   "description": "TypeScript SDK for Aex sessions",
   "license": "Apache-2.0",
   "homepage": "https://aex.dev",
@@ -23,6 +23,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -34,7 +38,8 @@
     "test": "tsc -p tsconfig.json && node --test"
   },
   "dependencies": {
-    "@aexhq/brain": "0.3.0"
+    "@aexhq/session-protocol": "0.3.1",
+    "@aexhq/environment": "0.1.0"
   },
   "peerDependencies": {
     "zod": "4.4.3"