@inferencesh/sdk 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.1] - 2026-10-10
+
+### Fixed
+
+- `sendMessage` sends its attachments: it posted only the text after uploading the files, so attachments never reached the agent. It now posts the file refs as `attachments` on POST /chats/{id}/messages. Needs api-v1227+; an older API ignores the field.
+
+## [0.22.0] - 2026-10-10
+
+Breaking: the server proxy forwards only app runs and agent chats and refuses every other API call with 403 (see Security); `update()` on projects, knowledge, skills, chats, engines and teams sends PATCH and needs an API that answers PATCH (see Changed); the Next.js proxy handler has no `PUT`.
+
+### Added
+
+- Server proxy options (`@inferencesh/sdk/proxy` and every adapter): `allowedEndpoints` (`namespace/name` globs, e.g. `"ana/helper"`, `"ana/*"`) limits which apps and agents visitors may run; `isAuthenticated(request)` decides per request whether the API key may be used (401 otherwise) and receives the framework's request; `allowUnauthorizedRequests` (default `true`) set to `false` refuses every request unless `isAuthenticated` is given. `@inferencesh/sdk/proxy/nextjs` gains `createHandler(options)` (App Router) and `createPageHandler(options)` (Page Router); `handlers` and `pageHandler` are those with the default options. `PROXY_ENDPOINTS` lists what the proxy forwards. `apiUrl` (default `https://api.inference.sh`) names the API the frontend's client calls; `maxUploadBytes` (default 100 MiB) caps a file uploaded through the proxy.
+- Server proxy: `endpoints` forwards a subset of `PROXY_ENDPOINTS`, built with `pickProxyEndpoint("POST /chats/{id}/messages", { onlyFields, validate })`, which can narrow an entry (fewer body fields, an extra body check) but never widen it; `matchProxyEndpoint(method, path)` finds the entry a request takes. `exactRefs: true` matches `allowedEndpoints` entries against the whole ref, version included ("ana/helper@v2" lets only that version through). `isLoopbackHost` / `isHttpsOrLoopback` export the proxy's https-or-loopback rule.
+- Server proxy: `PROXY_ENDPOINTS` is built from the API's proxy manifest (`src/proxy/endpoints.json`, generated by go/api from its route table for the run-only preset and copied by its `make types`), exported as `PROXY_MANIFEST`. Each entry gains `route` ("POST /chats/{id}/messages") and `scopes` (what the site's key must hold for it); `PROXY_ENDPOINT_RULES` holds the proxy's own body checks by route. `pickProxyEndpoint` takes the manifest route, any placeholder names.
+- `AppsAPI.patch(appId, AppPatchBody)`: PATCH /apps/{id}, changes the app's copy fields sent and keeps the others. `update()` stays POST, since it also edits the version in place.
+- `ChatsAPI.updateSettings()` (POST /chats/{id}/settings: name, visibility, tool approval, hooks, memory), `FlowsAPI.patch()` (PATCH /flows/{id}, only the fields sent) and `FlowsAPI.saveViewport()` (POST /flows/{id}/viewport). `HttpClient` takes `'patch'`.
+- Write body types (`AgentUpdateBody`, `AppUpdateBody`, `ChatUpdateBody`, `EngineUpdateBody`, `FlowUpdateBody`, `FlowPatchBody`, `FlowViewportBody`, `ProjectWriteBody`, `KnowledgeUpdateBody`, `TeamUpdateBody`, `MCPServerUpdateBody`) name the fields each route writes. The update methods take them in place of `Partial<DTO>`: a loaded DTO spread into the call still type-checks; an explicit field the route drops does not.
+- `ApiKeysAPI.create()` takes the generated `CreateApiKeyRequest`, so `scope` (personal or workspace key) and `expires_at` type-check. Existing `{ name, scopes }` calls are unchanged.
+- `ProxyAdapter` takes an optional `signal` that the proxy passes to the upstream fetch.
+- Types: `ScopeRefusedMeta` (`required_scope`, the meta of an `insufficient_scope` or `admin_scopes_not_approved` error), `ErrorCodeAdminScopesNotApproved` and the other admin session error codes, `AgentVersionDTO.visitor_reads` (the scope groups a publication of the agent answers), `ScopesResponse.account_scopes` and `login_preset`, `AppSandbox` on `AppVersionDTO`.
+
+### Changed
+
+- `update()` on `ProjectsAPI`, `KnowledgeAPI`, `SkillsAPI`, `ChatsAPI`, `EnginesAPI` and `TeamsAPI` sends PATCH instead of POST: a field left out of the body keeps its value. With POST the API wrote every field left out as empty. Needs an API that answers PATCH on these routes; an older API answers 405.
+- `@inferencesh/sdk/proxy/nextjs` `createHandler()` (and `handlers`) return `{ GET, POST }`: the `PUT` handler is gone, since the proxy forwards no PUT call and answered every one with 403. Drop `PUT` from `export const { GET, POST, PUT } = ...`; Next.js now answers PUT with 405.
+
+- Tool approvals (`approveTool`, `rejectTool`, `alwaysAllowTool`, `resolveInterrupt`) and widening a chat's approval settings document that they need the account holder's own sign-in: with an API key, an app's token or the server proxy the API answers 403 `requires_sign_in` (`ErrorCodeRequiresSignIn`).
+- Types regenerated from the API: admin elevation types (`AdminElevate*`, `AdminElevation*`), `MeResponse.platform_power` and `scopes`, scope metadata (`sign_in_only`, `not_for_apps`, `costs_credits`, `automation`, `public_rows`, `staff_only`), `ScopePreset.default` and `grants`, `ApiKeyDTO.grants`, the approvals, secrets:reveal and admin scopes (`admin:pricing` included), and error codes including `requires_sign_in`, `insufficient_scope`, `invalid_ttl`, `invalid_code`, `already_processed` and `expired`.
+
+### Fixed
+
+- `@inferencesh/sdk/proxy/express` cancels the upstream request when the client disconnects. Before, a disconnected chat or task stream kept its upstream connection open, which kept the host process alive after `server.close()`.
+- `tasks.watch().done`, `client.run({ wait: true })` and the agent's stream-until-idle no longer hang when a stream closes cleanly before a terminal status (load balancer idle timeout, deploy): the SDK reads the task or chat once and settles from it, rejecting when it is still not terminal.
+- Agent chat state always holds `content` as an array: a message the API serializes with `content: null`, or a partial update without content, no longer crashes views that read it. A partial update keeps the content the message had.
+- `SDK_VERSION` reads `package.json`, so it cannot drift from the published version.
+
+### Deprecated
+
+- `FlowRunsAPI.update()`: the API refuses it, because a flow run has no caller-writable fields. Use `FlowRunsAPI.updateVisibility()` to change who can see a run. The method stays for compile compatibility.
+
+### Security
+
+- The server proxy forwards only what a frontend needs to run things, listed in `PROXY_ENDPOINTS`: `POST /apps/run`, `POST /files` (uploads of run inputs), `POST /agents/run`, `POST /chats`, `POST /chats/{id}/messages`, `POST /chats/{id}/agent`, `GET /agents/{namespace}/{name}`, reading, polling, streaming, stopping and cancelling the resulting task or chat, and client tool results (`POST /tools/{id}`). Every other call (secrets, API keys, billing, account, file listings, app/agent/flow management, admin, task and chat listings and feeds) answers 403 before the API key is attached, whatever the options. Before, it forwarded any path on `*.inference.sh` with the site's key. A server that proxied other calls for its frontend must make them from its own backend.
+- Ids in proxied paths must have the shape the API mints (a lowercase 26-character ULID), so a literal route beside an id is never taken for one: `GET /tasks/stream` (the live feed of every task the key can read), `/tasks/featured`, `/tasks/queue-stats`, `/chats/list` and the like answer 403.
+- Tool approvals are not forwarded: approve, reject, always allow, explain, resolving an interrupt, listing a run's interrupts, and chat settings (`allow_all_tools`). The API takes an approval only from the account holder's own sign-in, never an API key, so these could not work through a proxy, and "allow all tools" would have let any visitor holding a chat id approve every call in it. Agents served through a proxy should not use approval-gated tools; use a published agent (embed) for that.
+- A target URL with credentials (`https://user:pass@...`) is refused with 400.
+- The proxy forwards only to the configured API origin: `apiBaseUrl` / `INFERENCE_API_BASE_URL` when set, else `apiUrl` (default `https://api.inference.sh`). Other `*.inference.sh` hosts are refused with 412. `allowedDomains` patterns must match the whole host.
+- `POST /apps/run` through the proxy takes only `app`, `app_id`, `version_id`, `function`, `input`, `stream` and `wait`: a visitor can no longer set `workers`, `infra`, `session`, `session_timeout`, `webhook`, `run_at`, `setup` or `metadata` (403).
+- `POST /files` through the proxy takes one file per request, with no `category`, and a declared `size` up to `maxUploadBytes` (413 above it). Uploads count against the API key owner's storage quota.
+- With `allowedEndpoints` set, a request that names an app or agent must name an allowed one by its `namespace/name` ref: `app_id`/`version_id` runs and ad-hoc `agent_config` runs are refused, and body keys are matched case-insensitively as the API reads them. Requests about an existing task or chat name it by id and are not checked against `allowedEndpoints`: whoever holds a task or chat id can read, stream, cancel or stop it and send messages in the chat. All visitors share the key, so the id is the only boundary between them.
+- The server proxy (`@inferencesh/sdk/proxy`) refuses a target that is not `https:` with 412 before attaching the API key, so a client can no longer make it send `INFERENCE_API_KEY` over plain http. Plain `http:` is allowed only to a loopback host (`localhost`, `*.localhost`, `127.0.0.0/8`, `[::1]`), for a local API in development. A malformed target with `apiBaseUrl` set answers 400 instead of throwing.
+
 ## [0.21.0] - 2026-10-08
 
 Breaking: `AgentClient.http` requires `fetch`, the `AppTag*` constants are removed, and `StreamableManagerOptions` is a type alias. See Changed and Removed.

package/dist/agent/api.d.ts

@@ -46,7 +46,23 @@ export declare function submitToolResult(client: AgentClient, toolInvocationId:
     };
     form_data?: Record<string, unknown>;
 }): Promise<void>;
+/**
+ * Approve a call awaiting approval; the api then runs it.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
+ */
 export declare function approveTool(client: AgentClient, toolInvocationId: string): Promise<void>;
+/**
+ * Reject a call awaiting approval, with an optional reason the agent sees.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
+ */
 export declare function rejectTool(client: AgentClient, toolInvocationId: string, reason?: string): Promise<void>;
 /**
  * What "always allow" can save for a call awaiting approval, narrowest first.
@@ -57,6 +73,11 @@ export declare function getAlwaysAllowOptions(client: AgentClient, chatId: strin
  * Save an "always allow" option (a key from getAlwaysAllowOptions) as chat
  * rules and approve the call once. Without an option the api saves its old
  * default: the command exactly for remote_exec, the whole tool otherwise.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
  */
 export declare function alwaysAllowTool(client: AgentClient, chatId: string, toolInvocationId: string, option?: string): Promise<AlwaysAllowResultDTO>;
 /**
@@ -65,8 +86,21 @@ export declare function alwaysAllowTool(client: AgentClient, chatId: string, too
  * for the call, so asking again is free.
  */
 export declare function explainTool(client: AgentClient, chatId: string, toolInvocationId: string): Promise<ToolExplanationDTO>;
-/** Change the chat's settings. Answers with the settings as they now are. */
+/**
+ * Change the chat's settings. Answers with the settings as they now are.
+ * Widening what runs without approval (allow_all_tools) needs approvals:write,
+ * held only by the account holder's own sign-in: other credentials are
+ * refused with 403 `requires_sign_in` (ErrorCodeRequiresSignIn).
+ */
 export declare function updateChatSettings(client: AgentClient, chatId: string, settings: ChatSettingsRequest): Promise<ChatSettingsDTO>;
+/**
+ * Allow or deny an interrupt gate on an agent run.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
+ */
 export declare function resolveInterrupt(client: AgentClient, interruptId: string, decision: 'allow' | 'deny'): Promise<InterruptDTO>;
 export declare function listRunInterrupts(client: AgentClient, runId: string): Promise<InterruptDTO[]>;
 export declare function uploadFile(client: AgentClient, file: globalThis.File): Promise<FileRef>;

package/dist/agent/api.js

@@ -21,7 +21,9 @@ async function processFiles(client, files) {
         if (isFileRef(file))
             return file;
         try {
-            return await client.files.upload(file);
+            // The upload answers with the whole file record; the message takes a ref.
+            const { id, uri, filename, content_type, size } = await client.files.upload(file);
+            return { id, uri, filename, content_type, size };
         }
         catch (error) {
             console.error('[AgentSDK] Failed to upload file:', error);
@@ -45,9 +47,9 @@ async function createChat(client, config) {
 /**
  * Send a message in a chat — POST /chats/{id}/messages
  */
-async function sendChatMessage(client, chatId, text) {
+async function sendChatMessage(client, chatId, text, attachments) {
     const resp = await client.http.request('post', `/chats/${chatId}/messages`, {
-        data: { message: text },
+        data: attachments ? { message: text, attachments } : { message: text },
     });
     return {
         chatId,
@@ -58,14 +60,14 @@ async function sendChatMessage(client, chatId, text) {
  * Send a message — creates chat if needed, then sends message
  */
 export async function sendMessage(client, config, chatId, text, files) {
-    await processFiles(client, files);
+    const attachments = await processFiles(client, files);
     // Existing chat — just send the message
     if (chatId) {
-        return sendChatMessage(client, chatId, text);
+        return sendChatMessage(client, chatId, text, attachments);
     }
     // New chat — create it, then send the first message
     const chat = await createChat(client, config);
-    return sendChatMessage(client, chat.id, text);
+    return sendChatMessage(client, chat.id, text, attachments);
 }
 // =========================================================================
 // Agent info
@@ -146,9 +148,25 @@ export async function submitToolResult(client, toolInvocationId, resultOrAction)
     const data = typeof resultOrAction === 'string' ? { result: resultOrAction } : resultOrAction;
     await client.http.request('post', `/tools/${toolInvocationId}`, { data });
 }
+/**
+ * Approve a call awaiting approval; the api then runs it.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
+ */
 export async function approveTool(client, toolInvocationId) {
     await client.http.request('post', `/tools/${toolInvocationId}/invoke`);
 }
+/**
+ * Reject a call awaiting approval, with an optional reason the agent sees.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
+ */
 export async function rejectTool(client, toolInvocationId, reason) {
     await client.http.request('post', `/tools/${toolInvocationId}/reject`, { data: { reason } });
 }
@@ -164,6 +182,11 @@ export async function getAlwaysAllowOptions(client, chatId, toolInvocationId) {
  * Save an "always allow" option (a key from getAlwaysAllowOptions) as chat
  * rules and approve the call once. Without an option the api saves its old
  * default: the command exactly for remote_exec, the whole tool otherwise.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
  */
 export async function alwaysAllowTool(client, chatId, toolInvocationId, option) {
     const data = option ? { option } : {};
@@ -179,7 +202,12 @@ export async function explainTool(client, chatId, toolInvocationId) {
     const resp = await client.http.request('post', `/chats/${chatId}/tools/${toolInvocationId}/explain`);
     return resp.data;
 }
-/** Change the chat's settings. Answers with the settings as they now are. */
+/**
+ * Change the chat's settings. Answers with the settings as they now are.
+ * Widening what runs without approval (allow_all_tools) needs approvals:write,
+ * held only by the account holder's own sign-in: other credentials are
+ * refused with 403 `requires_sign_in` (ErrorCodeRequiresSignIn).
+ */
 export async function updateChatSettings(client, chatId, settings) {
     const resp = await client.http.request('post', `/chats/${chatId}/settings`, { data: settings });
     return resp.data;
@@ -187,6 +215,14 @@ export async function updateChatSettings(client, chatId, settings) {
 // =========================================================================
 // Interrupt operations
 // =========================================================================
+/**
+ * Allow or deny an interrupt gate on an agent run.
+ *
+ * Needs approvals:write, which only the account holder's own sign-in holds
+ * (the web app, or a `belt login` session). An API key, an app's OAuth token
+ * or the server proxy is refused with 403 `requires_sign_in`
+ * (ErrorCodeRequiresSignIn); the error's message says what to do.
+ */
 export async function resolveInterrupt(client, interruptId, decision) {
     const resp = await client.http.request('post', `/interrupts/${interruptId}/resolve`, {
         data: { decision }

package/dist/agent/reducer.js

@@ -14,6 +14,20 @@ function deriveChatStatus(run) {
         return ChatStatusAwaitingInput;
     return ChatStatusIdle;
 }
+/**
+ * Every message enters state through here. The API serializes a message with
+ * no content as `content: null` (a nil Go slice), and a partial stream update
+ * carries the whole DTO with `content: null` when content is not among its
+ * fields. State always holds an array, so ChatMessageDTO.content is what its
+ * type says for every consumer; a partial update with null content keeps the
+ * content the message already had.
+ */
+function normalizeMessage(message, existing) {
+    if (message.content != null)
+        return message;
+    return { ...message, content: existing?.content ?? [] };
+}
+const normalizeMessages = (messages) => messages.map((m) => normalizeMessage(m));
 // =============================================================================
 // Initial State
 // =============================================================================
@@ -38,7 +52,7 @@ export function chatReducer(state, action) {
             if (!chat) {
                 return { ...state, chat: null, messages: [], connectionStatus: 'idle', messageCursor: undefined, hasOlderMessages: undefined };
             }
-            const messages = [...(chat.chat_messages || [])].sort((a, b) => a.order - b.order);
+            const messages = normalizeMessages(chat.chat_messages || []).sort((a, b) => a.order - b.order);
             const cursor = chat?._messageCursor;
             const hasOlder = chat?._hasOlderMessages;
             return { ...state, chat, messages, messageCursor: cursor, hasOlderMessages: hasOlder };
@@ -93,11 +107,11 @@ export function chatReducer(state, action) {
             return { ...state, chat: { ...state.chat, active_run: action.payload, status: deriveChatStatus(action.payload) } };
         }
         case 'SET_MESSAGES':
-            return { ...state, messages: action.payload };
+            return { ...state, messages: normalizeMessages(action.payload) };
         case 'PREPEND_MESSAGES': {
             const { messages: older, cursor, hasMore } = action.payload;
             const existingIds = new Set(state.messages.map(m => m.id));
-            const deduped = older.filter(m => !existingIds.has(m.id));
+            const deduped = normalizeMessages(older.filter(m => !existingIds.has(m.id)));
             const merged = [...deduped, ...state.messages].sort((a, b) => a.order - b.order);
             return { ...state, messages: merged, messageCursor: cursor, hasOlderMessages: hasMore };
         }
@@ -106,7 +120,9 @@ export function chatReducer(state, action) {
             const existingIndex = state.messages.findIndex((m) => m.id === message.id);
             if (existingIndex !== -1) {
                 const existing = state.messages[existingIndex];
-                const updated = action.partial ? { ...existing, ...message } : message;
+                const updated = action.partial
+                    ? normalizeMessage({ ...existing, ...message }, existing)
+                    : normalizeMessage(message);
                 if (existing === updated)
                     return state;
                 const newMessages = [...state.messages];
@@ -115,12 +131,12 @@ export function chatReducer(state, action) {
             }
             if (action.partial)
                 return state;
-            return { ...state, messages: [...state.messages, message].sort((a, b) => a.order - b.order) };
+            return { ...state, messages: [...state.messages, normalizeMessage(message)].sort((a, b) => a.order - b.order) };
         }
         case 'ADD_MESSAGE':
             return {
                 ...state,
-                messages: [...state.messages, action.payload].sort((a, b) => a.order - b.order),
+                messages: [...state.messages, normalizeMessage(action.payload)].sort((a, b) => a.order - b.order),
             };
         case 'DELTA_TOKEN': {
             const { messageId, output } = action.payload;
@@ -131,7 +147,7 @@ export function chatReducer(state, action) {
             const target = msgs.find(m => m.id === messageId);
             if (!target)
                 return state;
-            const textBlock = target.content?.find(c => c.type === 'text');
+            const textBlock = target.content.find(c => c.type === 'text');
             const newContent = textBlock
                 ? target.content.map(c => c.type === 'text' ? { ...c, text: output.response } : c)
                 : [{ type: 'text', text: output.response }, ...target.content];

package/dist/agent/types.d.ts

@@ -132,9 +132,21 @@ export interface AgentChatActions {
     submitToolResult: (toolInvocationId: string, result: string) => Promise<void>;
     /** Answer an MCP tool call's input requests (AwaitingInput status with MCPInputState data) */
     submitMCPInput: (toolInvocationId: string, responses: Record<string, ElicitResult>) => Promise<void>;
-    /** Approve a tool (for HIL approval - AwaitingApproval status) */
+    /**
+     * Approve a tool (for HIL approval - AwaitingApproval status)
+     *
+     * Needs the account holder's own sign-in (approvals:write): with an API
+     * key, an app's token or the server proxy it rejects with 403
+     * `requires_sign_in` (ErrorCodeRequiresSignIn).
+     */
     approveTool: (toolInvocationId: string) => Promise<void>;
-    /** Reject a tool (for HIL approval - AwaitingApproval status) */
+    /**
+     * Reject a tool (for HIL approval - AwaitingApproval status)
+     *
+     * Needs the account holder's own sign-in (approvals:write): with an API
+     * key, an app's token or the server proxy it rejects with 403
+     * `requires_sign_in` (ErrorCodeRequiresSignIn).
+     */
     rejectTool: (toolInvocationId: string, reason?: string) => Promise<void>;
     /**
      * What "always allow" can save for a call awaiting approval, narrowest
@@ -154,15 +166,28 @@ export interface AgentChatActions {
      * api saves its default. A string is accepted from older callers (it was the
      * tool name) and means the default. Rejects with a 409 when the option is
      * stale: read the options again.
+     *
+     * Needs the account holder's own sign-in (approvals:write): with an API
+     * key, an app's token or the server proxy it rejects with 403
+     * `requires_sign_in` (ErrorCodeRequiresSignIn).
      */
     alwaysAllowTool: (toolInvocationId: string, choice?: AlwaysAllowChoice | string) => Promise<AlwaysAllowResultDTO | undefined>;
-    /** Change this chat's settings, e.g. allow_all_tools (switching it on approves the calls waiting) */
+    /**
+     * Change this chat's settings, e.g. allow_all_tools (switching it on approves the calls waiting).
+     * Widening approvals needs the account holder's own sign-in: other credentials get 403 `requires_sign_in`.
+     */
     updateChatSettings: (settings: ChatSettingsRequest) => Promise<void>;
     /** Hand this chat to another agent (namespace/name); the next message goes to it. Agents our loop runs only. */
     switchAgent: (agentRef: string) => Promise<void>;
     /** Cancel a queued message before the agent processes it */
     cancelMessage: (messageId: string) => Promise<void>;
-    /** Resolve an interrupt gate (allow or deny) */
+    /**
+     * Resolve an interrupt gate (allow or deny)
+     *
+     * Needs the account holder's own sign-in (approvals:write): with an API
+     * key, an app's token or the server proxy it rejects with 403
+     * `requires_sign_in` (ErrorCodeRequiresSignIn).
+     */
     resolveInterrupt: (interruptId: string, decision: 'allow' | 'deny') => Promise<void>;
     /** Load older messages (scroll-up pagination). Returns true if more exist. */
     loadOlderMessages: () => Promise<boolean>;

package/dist/api/agents.d.ts

@@ -1,5 +1,6 @@
 import { HttpClient } from '../http/client';
 import type { Response } from '../http/response';
+import type { AgentUpdateBody } from './write-bodies';
 import { FilesAPI } from './files';
 import { ChatDTO, ChatMessageDTO, ChannelContext, LLMDelta, LLMOutput, AgentConfigInput as AgentConfig, AgentDTO, AgentVersionDTO, CreateAgentRequest, FileDTO as File, InterruptDTO, CursorListRequest, CursorListResponse } from '../types';
 /** Internal tool definition returned by getInternalTools */
@@ -159,9 +160,10 @@ export declare class AgentsAPI {
      */
     createAgent(data: CreateAgentRequest): Promise<Response<AgentDTO>>;
     /**
-     * Update an agent template
+     * Update an agent template: its visibility and images, and a new version
+     * when `version` is set (see AgentUpdateBody).
      */
-    update(agentId: string, data: Partial<AgentDTO>): Promise<Response<AgentDTO>>;
+    update(agentId: string, data: AgentUpdateBody): Promise<Response<AgentDTO>>;
     /**
      * Delete an agent template
      */
@@ -215,7 +217,11 @@ export declare class AgentsAPI {
         form_data?: Record<string, unknown>;
     }): Promise<void>;
     /**
-     * Resolve an interrupt gate on an agent run
+     * Resolve an interrupt gate on an agent run.
+     *
+     * Needs approvals:write, which only the account holder's own sign-in holds:
+     * with an API key, an app's OAuth token or the server proxy it rejects with
+     * 403 `requires_sign_in` (ErrorCodeRequiresSignIn).
      */
     resolveInterrupt(interruptId: string, decision: 'allow' | 'deny'): Promise<Response<InterruptDTO>>;
     /**

package/dist/api/agents.js

@@ -1,4 +1,4 @@
-import { StreamableManager } from '../http/streamable';
+import { streamUntilTerminal } from '../http/stream-until-terminal';
 import { PollManager } from '../http/poll';
 import { createLLMDeltaAccumulator } from '../delta';
 import { ToolTypeClient, ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, } from '../types';
@@ -108,6 +108,10 @@ export class Agent {
         let waitPromise = null;
         if (this.chatId && shouldWait) {
             waitPromise = waitFn(options);
+            // The stream can fail while the POST is in flight, before anything
+            // awaits waitPromise; mark the rejection handled so Node does not treat
+            // it as unhandled. The await below still sees it.
+            waitPromise.catch(() => { });
         }
         // Make the POST request
         let response;
@@ -145,8 +149,11 @@ export class Agent {
                 this.disconnect();
                 reject(signal.reason);
             };
-            if (signal.aborted)
-                return onAbort();
+            if (signal.aborted) {
+                onAbort();
+                wait.catch(() => { });
+                return;
+            }
             signal.addEventListener('abort', onAbort, { once: true });
             wait.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
         });
@@ -203,89 +210,101 @@ export class Agent {
     startStreaming(options = {}) {
         if (!this.chatId)
             return;
-        this.streamUntilIdle(options, new TurnGate(false));
+        // Fire-and-forget: a stream failure must not become an unhandled rejection.
+        this.streamUntilIdle(options, new TurnGate(false)).catch((error) => {
+            console.warn('[Agent] Stream error:', error);
+        });
     }
     /** Stream events until chat becomes idle */
     streamUntilIdle(options, gate) {
         if (!this.chatId)
             return Promise.resolve();
-        const endpoint = `/chats/${this.chatId}/stream`;
-        return new Promise((resolve) => {
-            this.stream?.stop();
-            this.stream = new StreamableManager({
-                request: (init) => this.http.fetch(endpoint, init),
-            });
+        const chatId = this.chatId;
+        this.stream?.stop();
+        const handle = streamUntilTerminal((settle) => {
             // Last chat/run observation was idle but the gate wasn't settled yet;
             // a terminal message for this turn can settle it.
             let idlePending = false;
             const onIdle = () => {
                 if (gate.settled)
-                    resolve();
+                    settle.resolve();
                 else
                     idlePending = true;
             };
-            this.stream.addEventListener('chats', (chat) => {
+            const observeChat = (chat) => {
                 options.onChat?.(chat);
                 gate.observeChat(chat);
                 if (!isChatBusy(chat))
                     onIdle();
                 else
                     idlePending = false;
-            });
-            this.stream.addEventListener('agent_runs', (run) => {
-                const asChat = { active_run: run };
-                options.onChat?.(asChat);
-                gate.observeChat(asChat);
-                if (!isChatBusy(asChat))
-                    onIdle();
-                else
-                    idlePending = false;
-            });
+            };
             // One accumulator per message being streamed, keyed by the message id
             // the delta names, so a tool-call-only turn never shows the previous
             // message's text. Same attribution rule as the React hooks.
             const deltaAccums = new Map();
-            this.stream.addEventListener('delta', (evt) => {
-                if (!options.onDelta || !evt?.delta || !evt.resource_id)
-                    return;
-                let accum = deltaAccums.get(evt.resource_id);
-                if (!accum) {
-                    accum = createLLMDeltaAccumulator();
-                    deltaAccums.set(evt.resource_id, accum);
-                }
-                accum.apply(evt.delta);
-                options.onDelta({
-                    messageId: evt.resource_id,
-                    delta: evt.delta,
-                    output: accum.toOutput(),
-                    seq: evt.seq,
-                });
-            });
-            this.stream.addEventListener('chat_messages', (message) => {
-                // A terminal message receives no further deltas.
-                if (isMessageTerminal(message.status))
-                    deltaAccums.delete(message.id);
-                gate.observeMessage(message);
-                options.onMessage?.(message);
-                if (idlePending && gate.settled)
-                    resolve();
-                if (message.tool_invocations && options.onToolCall) {
-                    for (const inv of message.tool_invocations) {
-                        if (this.dispatchedToolCalls.has(inv.id))
-                            continue;
-                        if (inv.type === ToolTypeClient && (inv.status === ToolInvocationStatusInProgress || inv.status === ToolInvocationStatusAwaitingInput)) {
-                            this.dispatchedToolCalls.add(inv.id);
-                            options.onToolCall({
-                                id: inv.id,
-                                name: inv.function?.name || '',
-                                args: inv.function?.arguments || {},
-                            });
+            return {
+                request: (init) => this.http.fetch(`/chats/${chatId}/stream`, init),
+                events: {
+                    chats: (chat) => observeChat(chat),
+                    agent_runs: (run) => observeChat({ active_run: run }),
+                    delta: (evt) => {
+                        if (!options.onDelta || !evt?.delta || !evt.resource_id)
+                            return;
+                        let accum = deltaAccums.get(evt.resource_id);
+                        if (!accum) {
+                            accum = createLLMDeltaAccumulator();
+                            deltaAccums.set(evt.resource_id, accum);
                         }
-                    }
-                }
-            });
-            this.stream.start();
+                        accum.apply(evt.delta);
+                        options.onDelta({
+                            messageId: evt.resource_id,
+                            delta: evt.delta,
+                            output: accum.toOutput(),
+                            seq: evt.seq,
+                        });
+                    },
+                    chat_messages: (message) => {
+                        // A terminal message receives no further deltas.
+                        if (isMessageTerminal(message.status))
+                            deltaAccums.delete(message.id);
+                        gate.observeMessage(message);
+                        options.onMessage?.(message);
+                        if (idlePending && gate.settled)
+                            settle.resolve();
+                        if (message.tool_invocations && options.onToolCall) {
+                            for (const inv of message.tool_invocations) {
+                                if (this.dispatchedToolCalls.has(inv.id))
+                                    continue;
+                                if (inv.type === ToolTypeClient && (inv.status === ToolInvocationStatusInProgress || inv.status === ToolInvocationStatusAwaitingInput)) {
+                                    this.dispatchedToolCalls.add(inv.id);
+                                    options.onToolCall({
+                                        id: inv.id,
+                                        name: inv.function?.name || '',
+                                        args: inv.function?.arguments || {},
+                                    });
+                                }
+                            }
+                        }
+                    },
+                },
+                // The stream closed before the chat was seen idle: the chat itself
+                // says whether the turn is over.
+                reconcile: async () => {
+                    const { data: chat } = await this.http.request('get', `/chats/${chatId}`);
+                    observeChat(chat);
+                },
+                closedMessage: 'Chat stream closed before the chat became idle',
+                // Stopped by disconnect()/abort or replaced by a newer stream: the
+                // caller stopped waiting on purpose.
+                onStopped: () => settle.resolve(),
+                // Once the turn is over the stream stays attached, so onChat/onMessage
+                // keep reporting until the next turn or disconnect() replaces it.
+                keepOpen: true,
+            };
         });
+        this.stream = handle;
+        return handle.done;
     }
     /** Poll until chat becomes idle, dispatching callbacks on changes */
     pollUntilIdle(options, gate) {
@@ -394,7 +413,8 @@ export class AgentsAPI {
         return this.http.request('post', '/agents', { data });
     }
     /**
-     * Update an agent template
+     * Update an agent template: its visibility and images, and a new version
+     * when `version` is set (see AgentUpdateBody).
      */
     async update(agentId, data) {
         return this.http.request('post', `/agents/${agentId}`, { data });
@@ -472,7 +492,11 @@ export class AgentsAPI {
         await this.http.request('post', `/tools/${toolInvocationId}`, { data: { result } });
     }
     /**
-     * Resolve an interrupt gate on an agent run
+     * Resolve an interrupt gate on an agent run.
+     *
+     * Needs approvals:write, which only the account holder's own sign-in holds:
+     * with an API key, an app's OAuth token or the server proxy it rejects with
+     * 403 `requires_sign_in` (ErrorCodeRequiresSignIn).
      */
     async resolveInterrupt(interruptId, decision) {
         return this.http.request('post', `/interrupts/${interruptId}/resolve`, {

package/dist/api/api-keys.d.ts

@@ -1,6 +1,6 @@
 import { HttpClient } from '../http/client';
 import type { Response } from '../http/response';
-import { ApiKeyDTO, CursorListRequest, CursorListResponse } from '../types';
+import { ApiKeyDTO, CreateApiKeyRequest, CursorListRequest, CursorListResponse } from '../types';
 /**
  * API Keys API
  */
@@ -14,10 +14,7 @@ export declare class ApiKeysAPI {
     /**
      * Create an API key
      */
-    create(data: {
-        name: string;
-        scopes?: string[];
-    }): Promise<Response<ApiKeyDTO>>;
+    create(data: CreateApiKeyRequest): Promise<Response<ApiKeyDTO>>;
     /**
      * Delete an API key
      */