@rool-dev/sdk 2.0.0-dev.4adc2c2 → 2.0.0-dev.66fd5c8

package/README.md

@@ -201,6 +201,8 @@ const path = "/rool-drive/documents/report.pdf";
 
 const storage = await files.getStorageUsage();
 console.log(storage.usedBytes, storage.availableBytes);
+const { maxUploadBytes } = await files.options(path);
+console.log(maxUploadBytes);
 await files.createDirectory("/rool-drive/documents");
 const written = await files.write(path, reportBlob, {
   contentType: "application/pdf",
@@ -209,6 +211,11 @@ const written = await files.write(path, reportBlob, {
     if (totalBytes) renderUploadProgress(transferredBytes / totalBytes);
   },
 });
+await files.write(
+  "/rool-drive/documents/archive.bin",
+  () => createArchiveStream(),
+  { contentType: "application/octet-stream" },
+);
 const info = await files.stat(path);
 const documents = await files.list("/rool-drive/documents");
 const response = await files.read(path, {
@@ -234,7 +241,7 @@ for (const result of deleted) {
 }
 ```
 
-Paths are absolute machine paths under `/space` or `/rool-drive`. `list()` without a path enumerates those storage roots; pass `{ recursive: true }` to enumerate a complete subtree. File and directory metadata has a discriminating `kind` field. Reads return the native `Response` so callers can stream the body. `readMultiple()` hydrates ordered small files in one request and returns an `ok` result with binary-safe bytes and validators, or a per-file HTTP failure. A batch accepts at most 128 paths, 2 MiB per successful file, and 16 MiB across successful files. Writes accept any `BodyInit`, including `Blob` and `ReadableStream`, and return the same complete file metadata as `stat()` and `list()`. `onUploadProgress` reports transferred bytes and includes the total size when it is known; successful completion is confirmed by the `write()` promise. Copy and move operations overwrite by default; pass `{ overwrite: false }` for create-only behavior.
+Paths are absolute machine paths under `/space` or `/rool-drive`. `list()` without a path enumerates those storage roots; pass `{ recursive: true }` to enumerate a complete subtree. File and directory metadata has a discriminating `kind` field. Reads return the native `Response` so callers can stream the body. `readMultiple()` hydrates ordered small files in one request and returns an `ok` result with binary-safe bytes and validators, or a per-file HTTP failure. A batch accepts at most 128 paths, 2 MiB per successful file, and 16 MiB across successful files. Writes accept any `BodyInit`, including `Blob` and `ReadableStream`, and return the same complete file metadata as `stat()` and `list()`. Pass a function that creates a fresh `ReadableStream` when an upload must be replayable after a machine route change; a directly passed stream remains one-shot. `onUploadProgress` reports transferred bytes and includes the total size when it is known; successful completion is confirmed by the `write()` promise. `options(path)` reports `maxUploadBytes` for that path's storage root. Calling `options()` without a path reports whole-DAV capabilities and returns `null` for `maxUploadBytes` because `/space` and `/rool-drive` have different limits. Copy and move operations overwrite by default; pass `{ overwrite: false }` for create-only behavior.
 
 `deleteMultiple()` sends independent DAV requests with at most eight in flight. It accepts plain paths and targets carrying their own HTTP preconditions, and returns one ordered success or failure result per target. The requests are not atomic. A directory target recursively deletes its contents, so callers should omit redundant descendants; duplicate and overlapping targets otherwise remain independent and can race.
 
@@ -313,30 +320,29 @@ const defaultAgent = await machine.agents.get("rool");
 if (!defaultAgent) throw new Error("Rool agent is unavailable");
 
 const conversation = defaultAgent.conversation("research-chat");
+const stopWatching = conversation.watch((view) => {
+  renderConversation({
+    turns: view.turns,
+    output: view.output,
+    isRunning: view.isRunning,
+    loading: view.loading,
+    error: view.error,
+  });
+});
+
 await conversation.prompt("Explain the result.", { effort: "reasoning" });
 
-renderSettled(await conversation.listTurns());
-clearUnsettled();
-await conversation.follow({
-  onEvent: (event) => {
-    if (event.type !== "output.delta") return;
-    if (event.content.type === "text") {
-      renderUnsettledText(event.content.text);
-    } else if (event.content.type === "tool_call") {
-      showRunningTool(event.content.id, event.content.name);
-    } else if (event.content.type === "tool_result") {
-      showToolResult(event.content.id, event.content.content);
-    }
-  },
-});
-renderSettled(await conversation.listTurns());
+// When this conversation leaves the UI:
+stopWatching();
 ```
 
 `prompt()` starts the conversation's current run and resolves once the server accepts it. The agent runs as a detached job. A conversation can only have one current run; call `cancel()` and wait for `follow()` to finish before prompting again. The `readOnly` option is accepted for compatibility with legacy prompting but currently has no effect.
 
-`follow()` performs one `GET` of the conversation's current run. It receives the complete unsettled part of the conversation and then continues with new events until that response ends. Tool calls and their results arrive as `output.delta` events with matching IDs. A tool result contains nested content parts and an optional `error` flag. `follow()` returns `false` when there is no current run. A client can always render the conversation from its durable turns plus the events from its latest `follow()` call.
+`watch()` is the normal UI API. It fetches only turns after the last turn it has seen, follows the current run, and refreshes the durable turns when that stream ends. `turns` contains saved history through the current user message while a run is active; `output` contains that run's replayed and live output. The first listener starts the work and removing the last listener stops it. Saved turns remain cached on the conversation handle for the next listener.
+
+`follow()` is the lower-level streaming API. It performs one `GET` of the conversation's current run. It receives the complete current-run output and then continues with new events until that response ends. Tool calls and their results arrive as `output.delta` events with matching IDs. A tool result contains nested content parts and an optional `error` flag. `follow()` returns `false` when there is no current run. Aborting `follow()` only stops that request; call `cancel()` to stop the detached job.
 
-A `conversation_changed` account event tells clients to fetch the durable turns and follow the current run again. Aborting `follow()` only stops watching. Call `cancel()` to stop the detached job.
+The SDK uses `conversation_changed` account events to wake active watchers. A watcher also refreshes after prompting, cancellation, stream completion, connection failure, and account event-token replacement.
 
 Prompt attachments are existing `/space` or `/rool-drive` paths. Pass a durable user turn's `id` as `replaceTurnId` to replace that message and everything after it. This supports edits and rerolls, including the first message. A replacement gets a new user turn ID; use that ID to edit it again.
 
@@ -354,12 +360,12 @@ await conversation.prompt("Return the number of records.", {
 await conversation.follow();
 
 const turns = await conversation.listTurns();
-const part = turns.at(-1)?.body.content[0];
+const part = turns.at(-1)?.content[0];
 if (part?.type !== "json") throw new Error("No structured result");
 console.log(part.value); // { count: ... }
 ```
 
-Custom agent definitions currently contain one plain system prompt. The server owns the executable agent implementation.
+A custom agent's `system` field contains instructions added after Rool's built-in machine context. Each conversation can add another instruction layer without changing the agent or its metadata.
 
 ```typescript
 const researcher = await machine.agents.create("researcher", {
@@ -369,10 +375,15 @@ const customConversation = await researcher.createConversation({
   name: "Climate report",
   visibility: "private",
 });
+await customConversation.replaceInstructions(
+  "For this conversation, compare at least two sources.",
+);
 await customConversation.prompt("Investigate this claim.");
 ```
 
-Agents expose `replace()` and `delete()`. Conversations expose metadata replacement, listing, durable turn reads, rename, and deletion. Listed and fetched conversation metadata includes server-managed ISO 8601 `createdAt` and `updatedAt` timestamps plus `isRunning`, which can drive a running indicator without opening every run stream. Visibility defaults to private. The built-in `rool` agent cannot be replaced or deleted.
+`getInstructions()` returns the conversation instructions. `replaceInstructions("")` clears them. Metadata changes do not affect them. New instructions apply to the next run; a run already in progress keeps the instructions it started with.
+
+Agents expose `replace()` and `delete()`. Conversations expose instruction and metadata replacement, listing, durable turn reads, rename, and deletion. Listed and fetched conversation metadata includes server-managed ISO 8601 `createdAt` and `updatedAt` timestamps plus `isRunning`, which can drive a running indicator without opening every run stream. Visibility defaults to private. The built-in `rool` agent cannot be replaced or deleted.
 
 ## Members and invites
 
@@ -427,6 +438,19 @@ const updated = await client.rotateGiftCode(giftId);
 
 Gift failures are `RoolProblem` errors. `gift_invalid` means the code or gift is unavailable to the caller. `gift_claimed` means it was already claimed.
 
+## Speechmatics
+
+Voice input transcribes the user's speech with Speechmatics' real-time API. Rool mints a short-lived key without exposing its long-lived provider key; hand the temporary key to the Speechmatics real-time SDK and stream the user's mic audio to it.
+
+```typescript
+const { token, expiresAt, ttl } = await client.getSpeechmaticsToken({
+  ttl: 300,
+});
+// speechmaticsRealtimeClient.start(token, { transcription_config: { language: "en" } })
+```
+
+The key expires after `ttl` seconds (60–3600, default 300). `expiresAt` is the epoch-milliseconds moment the key stops being accepted. A token request fails with `insufficient_credits` when the account's balance is too low and with `speechmatics_unavailable` when Speechmatics cannot issue a key.
+
 ## API problems
 
 Each problem `type` links to its entry below.
@@ -611,6 +635,18 @@ The gift has already been claimed. A claimed gift cannot be claimed again or giv
 
 The gift update is empty or contains an invalid note or archived value.
 
+<a id="problem-insufficient_credits"></a>
+
+### `insufficient_credits`
+
+The account's credit balance is too low to mint a speech transcription key. Top up the balance and try again.
+
+<a id="problem-speechmatics_unavailable"></a>
+
+### `speechmatics_unavailable`
+
+Speechmatics could not issue a transcription key right now. Try again shortly.
+
 ## Development
 
 ```bash

package/dist/agents.d.ts

@@ -1,3 +1,4 @@
+import type { RoolClientEvent } from "./events.js";
 import type { MachineFilePath } from "./files.js";
 export type MachinePromptEffort = "quick" | "standard" | "reasoning" | "research";
 export type MachineAssistantFinish = "stop" | "tool_calls" | "length" | "safety" | "error" | "credits" | "cancelled";
@@ -24,7 +25,10 @@ export type MachineConversationContentPart = {
     type: "json";
     value: unknown;
 };
-export interface MachineConversationTurnBody {
+export interface MachineConversationTurn {
+    id: string;
+    userId?: string;
+    createdAt: string;
     role: MachineConversationTurnRole;
     content: MachineConversationContentPart[];
     request?: Record<string, unknown>;
@@ -36,13 +40,8 @@ export interface MachineConversationTurnBody {
     };
     aside?: boolean;
 }
-export interface MachineConversationTurn {
-    id: string;
-    userId?: string;
-    createdAt: string;
-    body: MachineConversationTurnBody;
-}
 export interface MachineAgentDefinition {
+    /** Instructions added after Rool's built-in machine context. */
     system: string;
 }
 export type MachineAgentCreateInput = MachineAgentDefinition;
@@ -95,12 +94,25 @@ export interface MachineConversationFollowOptions extends AgentRequestOptions {
     onEvent?: (event: MachineRunEvent) => void;
 }
 export type MachineConversationCancelOptions = AgentRequestOptions;
+export interface MachineConversationView {
+    readonly turns: readonly MachineConversationTurn[];
+    readonly output: readonly MachineConversationContentPart[];
+    readonly isRunning: boolean;
+    readonly loading: boolean;
+    readonly error: unknown;
+}
+export type MachineConversationListener = (view: MachineConversationView) => void;
 export interface MachineConversation {
     readonly id: string;
     readonly agent: MachineAgent;
     get(options?: AgentRequestOptions): Promise<MachineConversationState | undefined>;
     listTurns(options?: AgentRequestOptions): Promise<MachineConversationTurn[]>;
+    watch(listener: MachineConversationListener): () => void;
     replace(metadata: MachineConversationMetadataInput, options?: AgentRequestOptions): Promise<MachineConversationMetadata>;
+    /** Return conversation-specific instructions; an empty string means none. */
+    getInstructions(options?: AgentRequestOptions): Promise<string>;
+    /** Replace conversation-specific instructions; pass an empty string to clear. */
+    replaceInstructions(instructions: string, options?: AgentRequestOptions): Promise<string>;
     prompt(text: string, options?: MachineConversationPromptOptions): Promise<void>;
     follow(options?: MachineConversationFollowOptions): Promise<boolean>;
     cancel(options?: MachineConversationCancelOptions): Promise<boolean>;
@@ -124,7 +136,8 @@ export interface MachineAgents {
 interface AgentTransport {
     request(path: string, init?: RequestInit, allowHttpErrors?: boolean): Promise<Response>;
     requestJson<T>(path: string, init?: RequestInit): Promise<T>;
+    subscribeEvents(listener: (event: RoolClientEvent) => void): () => void;
 }
-export declare function createMachineAgents(machinePath: string, transport: AgentTransport): MachineAgents;
+export declare function createMachineAgents(machineId: string, machinePath: string, transport: AgentTransport): MachineAgents;
 export {};
 //# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/dist/agents.js

@@ -1,11 +1,14 @@
 import { throwProblemResponse } from "./problem.js";
 const VALID_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const MAX_EVENT_BYTES = 1024 * 1024;
+const WATCH_RETRY_MAX_MS = 5_000;
 class MachineAgentState {
+    machineId;
     machinePath;
     transport;
     agents = new Map();
-    constructor(machinePath, transport) {
+    constructor(machineId, machinePath, transport) {
+        this.machineId = machineId;
         this.machinePath = machinePath;
         this.transport = transport;
     }
@@ -73,17 +76,32 @@ class MachineAgentState {
         if (!response.ok)
             await throwProblemResponse(response);
         const metadata = (await response.json());
-        const turns = await this.listTurns(agentId, conversationId, options);
-        return { ...metadata, turns };
+        const update = await this.readTurnUpdate(agentId, conversationId, undefined, options.signal);
+        return { ...metadata, isRunning: update.isRunning, turns: update.turns };
     }
     async listTurns(agentId, conversationId, options = {}) {
-        const { turns } = await this.transport.requestJson(`${this.conversationPath(agentId, conversationId)}/turns`, { signal: options.signal });
-        return turns.map(turnFromWire);
+        return (await this.readTurnUpdate(agentId, conversationId, undefined, options.signal)).turns;
+    }
+    async readTurnUpdate(agentId, conversationId, after, signal) {
+        const query = after ? `?${new URLSearchParams({ after }).toString()}` : "";
+        return this.transport.requestJson(`${this.conversationPath(agentId, conversationId)}/turns${query}`, { signal });
+    }
+    subscribeEvents(listener) {
+        return this.transport.subscribeEvents(listener);
     }
     replaceConversation(agentId, conversationId, metadata, options = {}) {
         validateMetadata(metadata);
         return this.transport.requestJson(this.conversationPath(agentId, conversationId), jsonRequest("PUT", metadata, options.signal));
     }
+    async getConversationInstructions(agentId, conversationId, options = {}) {
+        const result = await this.transport.requestJson(`${this.conversationPath(agentId, conversationId)}/instructions`, { signal: options.signal });
+        return result.instructions;
+    }
+    async replaceConversationInstructions(agentId, conversationId, instructions, options = {}) {
+        validateInstructions(instructions);
+        const result = await this.transport.requestJson(`${this.conversationPath(agentId, conversationId)}/instructions`, jsonRequest("PUT", { instructions }, options.signal));
+        return result.instructions;
+    }
     async deleteConversation(agent, conversationId, options = {}) {
         await this.transport.request(this.conversationPath(agent.id, conversationId), { method: "DELETE", signal: options.signal });
         agent.forgetConversation(conversationId);
@@ -230,6 +248,21 @@ class ConversationClient {
     agent;
     id;
     state;
+    listeners = new Set();
+    turns = [];
+    output = [];
+    isRunning = false;
+    loading = true;
+    error = null;
+    watchController = null;
+    unsubscribeEvents = null;
+    syncRequested = false;
+    syncLoop = null;
+    retryTimer = null;
+    retryMs = 250;
+    followController = null;
+    followTask = null;
+    followRetryMs = 250;
     constructor(agent, id, state) {
         this.agent = agent;
         this.id = id;
@@ -241,17 +274,44 @@ class ConversationClient {
     listTurns(options = {}) {
         return this.state.listTurns(this.agent.id, this.id, options);
     }
+    watch(listener) {
+        this.listeners.add(listener);
+        listener(this.view());
+        if (!this.watchController)
+            this.startWatching();
+        return () => {
+            this.listeners.delete(listener);
+            if (this.listeners.size === 0)
+                this.stopWatching();
+        };
+    }
     replace(metadata, options) {
         return this.state.replaceConversation(this.agent.id, this.id, metadata, options);
     }
-    prompt(text, options = {}) {
-        return this.state.prompt(this.agent.id, this.id, text, options);
+    getInstructions(options) {
+        return this.state.getConversationInstructions(this.agent.id, this.id, options);
+    }
+    replaceInstructions(instructions, options) {
+        return this.state.replaceConversationInstructions(this.agent.id, this.id, instructions, options);
+    }
+    async prompt(text, options = {}) {
+        try {
+            await this.state.prompt(this.agent.id, this.id, text, options);
+        }
+        finally {
+            this.requestSync();
+        }
     }
     follow(options) {
         return this.state.follow(this.agent.id, this.id, options);
     }
-    cancel(options) {
-        return this.state.cancel(this.agent.id, this.id, options);
+    async cancel(options) {
+        try {
+            return await this.state.cancel(this.agent.id, this.id, options);
+        }
+        finally {
+            this.requestSync();
+        }
     }
     async rename(name, options = {}) {
         const current = await this.get(options);
@@ -265,25 +325,178 @@ class ConversationClient {
     delete(options) {
         return this.state.deleteConversation(this.agent, this.id, options);
     }
+    startWatching() {
+        const controller = new AbortController();
+        this.watchController = controller;
+        this.unsubscribeEvents = this.state.subscribeEvents((event) => {
+            const matchesConversation = event.type === "conversation_changed" &&
+                event.machineId === this.state.machineId &&
+                event.agentId === this.agent.id &&
+                event.conversationId === this.id;
+            if (event.type === "session" || matchesConversation) {
+                if (!this.followTask || event.type === "session")
+                    this.requestSync();
+            }
+        });
+        this.requestSync();
+    }
+    stopWatching() {
+        this.watchController?.abort();
+        this.watchController = null;
+        this.followController?.abort();
+        this.followController = null;
+        this.unsubscribeEvents?.();
+        this.unsubscribeEvents = null;
+        this.syncRequested = false;
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        this.retryTimer = null;
+    }
+    requestSync() {
+        const controller = this.watchController;
+        if (!controller || controller.signal.aborted)
+            return;
+        this.syncRequested = true;
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        this.retryTimer = null;
+        if (this.syncLoop)
+            return;
+        const loop = this.runSyncLoop(controller);
+        this.syncLoop = loop;
+        const finished = () => {
+            if (this.syncLoop === loop)
+                this.syncLoop = null;
+            const current = this.watchController;
+            if (current && this.syncRequested && !current.signal.aborted) {
+                this.requestSync();
+            }
+        };
+        void loop.then(finished, finished);
+    }
+    async runSyncLoop(controller) {
+        while (this.watchController === controller &&
+            !controller.signal.aborted &&
+            this.syncRequested) {
+            this.syncRequested = false;
+            try {
+                const after = this.turns.at(-1)?.id;
+                const update = await this.state.readTurnUpdate(this.agent.id, this.id, after, controller.signal);
+                if (controller.signal.aborted)
+                    return;
+                this.turns = update.reset
+                    ? update.turns
+                    : [...this.turns, ...update.turns];
+                this.isRunning = update.isRunning;
+                this.loading = false;
+                this.error = null;
+                this.retryMs = 250;
+                if (!this.isRunning || (update.reset && this.followTask)) {
+                    this.followController?.abort();
+                    this.output = [];
+                }
+                this.emit();
+                if (this.isRunning)
+                    this.ensureFollow(controller);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAbortError(error))
+                    return;
+                this.loading = false;
+                this.error = error;
+                this.emit();
+                this.scheduleRetry(controller);
+                return;
+            }
+        }
+    }
+    scheduleRetry(controller) {
+        if (this.retryTimer || this.watchController !== controller)
+            return;
+        const delay = this.retryMs;
+        this.retryMs = Math.min(this.retryMs * 2, WATCH_RETRY_MAX_MS);
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = null;
+            this.requestSync();
+        }, delay);
+    }
+    ensureFollow(watchController) {
+        if (this.followTask || this.watchController !== watchController)
+            return;
+        const controller = new AbortController();
+        this.followController = controller;
+        this.output = [];
+        this.emit();
+        const task = this.runFollow(controller);
+        this.followTask = task;
+        const finished = () => {
+            if (this.followTask === task)
+                this.followTask = null;
+            if (this.followController === controller)
+                this.followController = null;
+            const current = this.watchController;
+            if (current && !current.signal.aborted)
+                this.requestSync();
+        };
+        void task.then(finished, finished);
+    }
+    async runFollow(controller) {
+        let streamFailed = null;
+        try {
+            await this.state.follow(this.agent.id, this.id, {
+                signal: controller.signal,
+                onEvent: (event) => {
+                    if (event.type === "output.delta") {
+                        this.output = [...this.output, event.content];
+                        this.error = null;
+                        this.emit();
+                    }
+                    else if (event.type === "error" &&
+                        event.code === "run_stream_failed") {
+                        streamFailed = new Error(event.detail);
+                    }
+                },
+            });
+            if (streamFailed)
+                throw streamFailed;
+            this.followRetryMs = 250;
+        }
+        catch (error) {
+            if (controller.signal.aborted || isAbortError(error))
+                return;
+            this.error = error;
+            this.emit();
+            const delay = this.followRetryMs;
+            this.followRetryMs = Math.min(this.followRetryMs * 2, WATCH_RETRY_MAX_MS);
+            await abortableDelay(delay, controller.signal);
+        }
+    }
+    view() {
+        let end = this.turns.length;
+        if (this.isRunning) {
+            for (let index = this.turns.length - 1; index >= 0; index--) {
+                if (this.turns[index].role !== "user")
+                    continue;
+                end = index + 1;
+                break;
+            }
+        }
+        return {
+            turns: this.turns.slice(0, end),
+            output: [...this.output],
+            isRunning: this.isRunning,
+            loading: this.loading,
+            error: this.error,
+        };
+    }
+    emit() {
+        const view = this.view();
+        for (const listener of this.listeners)
+            listener(view);
+    }
 }
-export function createMachineAgents(machinePath, transport) {
-    return new MachineAgentState(machinePath, transport);
-}
-function turnFromWire(turn) {
-    return {
-        id: turn.id,
-        ...(turn.userId ? { userId: turn.userId } : {}),
-        createdAt: turn.createdAt,
-        body: {
-            role: turn.role,
-            content: turn.content,
-            ...(turn.request ? { request: turn.request } : {}),
-            ...(turn.finish ? { finish: turn.finish } : {}),
-            ...(turn.error ? { error: turn.error } : {}),
-            ...(turn.usage ? { usage: turn.usage } : {}),
-            ...(turn.aside !== undefined ? { aside: turn.aside } : {}),
-        },
-    };
+export function createMachineAgents(machineId, machinePath, transport) {
+    return new MachineAgentState(machineId, machinePath, transport);
 }
 function parseRunEvent(line) {
     const value = JSON.parse(line);
@@ -312,7 +525,7 @@ function parseRunEvent(line) {
 }
 function validateDefinition(definition) {
     if (!definition || typeof definition.system !== "string") {
-        throw new Error("Agent system prompt must be a string");
+        throw new Error("Agent system instructions must be a string");
     }
 }
 function validateMetadata(metadata) {
@@ -323,6 +536,11 @@ function validateMetadata(metadata) {
         throw new Error("Conversation name must be a string");
     }
 }
+function validateInstructions(instructions) {
+    if (typeof instructions !== "string") {
+        throw new Error("Conversation instructions must be a string");
+    }
+}
 function validateAttachment(path) {
     const supported = path.startsWith("/space/") || path.startsWith("/rool-drive/");
     if (!supported) {
@@ -345,4 +563,21 @@ function jsonRequest(method, body, signal) {
 function randomId() {
     return globalThis.crypto.randomUUID();
 }
+function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" || error.message.includes("was aborted")));
+}
+async function abortableDelay(milliseconds, signal) {
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => {
+        const timeout = setTimeout(finish, milliseconds);
+        signal.addEventListener("abort", finish, { once: true });
+        function finish() {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        }
+    });
+}
 //# sourceMappingURL=agents.js.map