@inferencesh/sdk 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -7,6 +7,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+
+- `HttpClient.fetch(endpoint, init?)`: fetches an endpoint with the client's auth, headers and credentials mode and resolves with the raw `Response`, for bodies `request()` does not parse (streams, text). A refused response throws the error `request()` would (`InferenceError`, `RequirementsNotMetException`). Type `HttpFetchInit`.
+- `StreamRequest` and `StreamRequestInit`: a function that sends a stream's request. `StreamableManager` takes `{ request }` in place of `{ url, headers, credentials }`, and `streamable()` / `streamableRaw()` take one in place of the URL. With `(init) => http.fetch(endpoint, init)` the stream carries the token of the moment it connects and a refusal goes through `onError`. Type `StreamableSource`.
+- `onError` gets a third argument, `FailedRequest` (`{ token }`): the bearer token the failed request carried, so a handler that refreshes credentials can tell a request sent before the refresh from one sent after it.
+- `getToken` may be async (`() => string | null | undefined | Promise<string | null | undefined>`). `request()`, `fetch()` and the EventSource handshake wait for it.
+- `HttpClient.request()` takes `handleErrors` (default `true`). With `handleErrors: false` the caller handles the request's failure itself: `onError` is not called for it, nothing is retried, and the error is thrown as it is.
+
+- Types: `StoreCategoryDTO` and `StoreTagDTO` (`GET /store/categories`, `GET /store/tags`); the decision app contract (`DecisionInput`, `DecisionVisionInput`, `DecisionOutput` and its question and answer types); `ErrorCodeImpersonationReasonRequired`.
+
+### Changed
+
+- `AgentClient.http` requires `fetch` and no longer requires `getStreamableConfig`. A hand-built `AgentClient` must add `http.fetch`; `Inference` and `HttpClient` already have it.
+- The streams the SDK opens itself (`tasks.run()` and `tasks.watch()`, `Agent` chat streams, the agent chat in `@inferencesh/sdk/agent`) go through `HttpClient.fetch`. A stream the api refuses now reaches `onError` like a refused request, and fails with an `InferenceError` (`statusCode`, `responseBody`) where it failed with `Error('HTTP <status>: <body>')`.
+- A request that got no response (the network failed) goes to `onError` from `fetch()` and the EventSource handshake too, as it already did from `request()`. The failure is thrown unless the handler's retry resolves with a response. A request aborted through its signal is not handed to `onError`.
+- The EventSource handshake and `fetch()` take what `onError` resolves with only when it is a `Response`; anything else leaves the refused response in place.
+- `StreamableManagerOptions` is a type alias (`StreamableSource & { ... }`), no longer an interface: it cannot be extended with `interface X extends StreamableManagerOptions<T>`; use an intersection.
+
+### Removed
+
+- The `AppTag*` constants (`AppTagTextToImage` and the rest). App tags come from the store: `GET /store/tags`, typed `StoreTagDTO`.
+
+### Deprecated
+
+- `HttpClient.getStreamableConfig()`: a request made from the config bypasses `onError` and carries the token of the moment the config was read. Use `fetch()` or a `StreamRequest`. It throws when `getToken` is async.
+
+## [0.20.1] - 2026-10-08
+
+### Added
+
+- Types: app tags and the decision app category.
+
+## [0.20.0] - 2026-10-07
+
+### Added
+
+- `tasks.files(id)`, `tasks.deleteFiles(id)` and `tasks.delete(id, { files })`: list a task's files and delete them with or without the task.
+- Types: task files, MCP Apps (`_meta.ui`, `AppUIRef`, the MCP tool call UI fields), remote tags and policy rules, `AppDTO.resolved_function`, `DescriptionLimit`.
+
+### Changed
+
+- Types: forms lose the bounty and reward fields; a bounty's proof form drops `proof_min_length`.
+
+### Security
+
+- `next` ^16.3.6 (resolves 16.3.8) for GHSA-vcvr-r3jv-pc5j.
+
+## [0.19.0] - 2026-10-04
+
+### Changed
+
+- Types regenerated; the run parameters docs drop `params.variant`.
+
 ## [0.18.0] - 2026-10-04
 
 ### Added

package/dist/agent/actions.js

@@ -109,11 +109,8 @@ export function createActions(ctx) {
             return;
         }
         // Single unified stream with TypedEvents (both Chat and ChatMessage events)
-        const { url, headers, credentials } = api.getChatStreamConfig(client, id);
         const manager = new StreamableManager({
-            url,
-            headers,
-            credentials,
+            request: api.chatStreamRequest(client, id),
             onError: (error) => {
                 console.warn('[AgentSDK] Stream error:', error);
                 callbacks.onError?.(error);

package/dist/agent/api.d.ts

@@ -9,6 +9,7 @@
  */
 import type { AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, InterruptDTO, ToolExplanationDTO } from '../types';
 import type { AgentOptions, AgentClient, AgentInfo, FileRef } from './types';
+import type { StreamRequest } from '../http/streamable';
 export interface SendResult {
     chatId: string;
     userMessage: ChatMessageDTO;
@@ -45,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.
@@ -56,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>;
 /**
@@ -64,13 +86,22 @@ 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>;
-export declare function getChatStreamConfig(client: AgentClient, chatId: string): {
-    url: string;
-    headers: Record<string, string>;
-    credentials: RequestCredentials;
-};
+export declare function chatStreamRequest(client: AgentClient, chatId: string): StreamRequest;

package/dist/agent/api.js

@@ -146,9 +146,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 +180,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 +200,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 +213,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 }
@@ -203,6 +237,6 @@ export async function listRunInterrupts(client, runId) {
 export async function uploadFile(client, file) {
     return client.files.upload(file);
 }
-export function getChatStreamConfig(client, chatId) {
-    return client.http.getStreamableConfig(`/chats/${chatId}/stream`);
+export function chatStreamRequest(client, chatId) {
+    return (init) => client.http.fetch(`/chats/${chatId}/stream`, init);
 }

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

@@ -19,7 +19,7 @@ export interface AlwaysAllowChoice {
  */
 export interface AgentClient {
     /** HTTP client for API requests */
-    http: Pick<HttpClient, 'request' | 'getStreamableConfig' | 'getStreamDefault' | 'getPollIntervalMs'>;
+    http: Pick<HttpClient, 'request' | 'fetch' | 'getStreamDefault' | 'getPollIntervalMs'>;
     /** Files API for uploads */
     files: {
         upload: (data: string | Blob | globalThis.File) => Promise<FileRef>;
@@ -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>>;
     /**