@inferencesh/sdk 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-02
+
+### Changed
+
+- `updateChatSettings` and `switchAgent` merge what the api now answers with into the chat they hold: `ChatSettingsDTO` (`chat_id`, `name`, `visibility`, `allow_all_tools`, `disable_hooks`, `memory`) from `POST /chats/{id}/settings` and `ChatAgentDTO` (`chat_id`, `agent_id`, `agent`, `agent_version_id`, `agent_version`) from `POST /chats/{id}/agent`. The reducer has `MERGE_CHAT_SETTINGS` and `MERGE_CHAT_AGENT` for them; a response for a chat other than the one on screen is ignored. The low-level `updateChatSettings` and `setAgent` in the agent api return those types. Needs an api that answers with them.
+- `ChatDTO.chat_messages` is optional: the api leaves it out when it did not load the messages, which it never does on the chat endpoints. Read messages from `GET /chats/{id}/messages`.
+
+### Fixed
+
+- Polling `sendMessage` handled a fetched chat with an unchanged status only when it carried `chat_messages`. It now skips only the poll's own "nothing changed" answer.
+
+## [0.16.0] - 2026-10-02
+
+### Added
+
+- `useAgentActions().getAlwaysAllowOptions(toolInvocationId)`: what "always allow" can save for a call awaiting approval, narrowest first, computed by the api (`GET /chats/{id}/tools/{toolId}/always-allow/options`). Each option has a `key`, a `scope` (`exact`, `prefix`, `folder`, `remote`, `tool`), a `label` such as "npm run commands on laptop", and the chat `rules` it saves; `default` is the narrowest that answers the call again, and `unavailable` says why there are none.
+- `useAgentActions().explainTool(toolInvocationId)`: a plain-words explanation of a call awaiting approval, `{ risk_level: 'low' | 'medium' | 'high', explanation, reasoning, risk }` (`POST /chats/{id}/tools/{toolId}/explain`). A model writes it the first time it is asked for and the api keeps it for the call; call it only when the person asks.
+- Types: `ToolExplanationDTO`, `ToolRiskLevel`, `AlwaysAllowOptionsDTO`, `AlwaysAllowOptionDTO`, `AlwaysAllowScope`, `AlwaysAllowRequest`, `AlwaysAllowResultDTO`, `PolicyRuleDTO` (with `label`), `AlwaysAllowChoice`.
+
+### Changed
+
+- `useAgentActions().alwaysAllowTool(toolInvocationId, { option })` saves the chosen option and resolves to the saved rules. The second argument used to be the tool name; a string is still accepted and means the api's default. A 409 (stale option) or 400 rejects without putting the chat in the error state.
+
+### Security
+
+- `proxy-addr` 2.0.8 in the lockfile (CVE-2026-90711).
+
 ## [0.15.0] - 2026-10-02
 
 ### Added

package/dist/agent/actions.js

@@ -368,16 +368,37 @@ export function createActions(ctx) {
                 throw error;
             }
         },
-        alwaysAllowTool: async (toolInvocationId, toolName) => {
+        getAlwaysAllowOptions: async (toolInvocationId) => {
+            const chatId = getChatId();
+            if (!chatId)
+                return null;
+            return api.getAlwaysAllowOptions(client, chatId, toolInvocationId);
+        },
+        explainTool: async (toolInvocationId) => {
+            const chatId = getChatId();
+            if (!chatId)
+                throw new Error('Cannot explain a tool call without a chat');
+            return api.explainTool(client, chatId, toolInvocationId);
+        },
+        alwaysAllowTool: async (toolInvocationId, choice) => {
             const chatId = getChatId();
             if (!chatId) {
                 console.error('[AgentSDK] Cannot always-allow tool without a chatId');
-                return;
+                return undefined;
             }
+            // A string is the tool name older callers passed; the api reads the
+            // tool from the call, so it only means "the default option".
+            const option = typeof choice === 'string' ? undefined : choice?.option;
             try {
-                await api.alwaysAllowTool(client, chatId, toolInvocationId, toolName);
+                return await api.alwaysAllowTool(client, chatId, toolInvocationId, option);
             }
             catch (error) {
+                // 409: the option is stale (the rules changed since it was read);
+                // 400: nothing can be always-allowed here. The call is still
+                // waiting and the connection is fine: the caller reads the options
+                // again or shows why.
+                if (isInferenceError(error) && (error.statusCode === 409 || error.statusCode === 400))
+                    throw error;
                 console.error('[AgentSDK] Failed to always-allow tool:', error);
                 const err = error instanceof Error ? error : new Error('Failed to always-allow tool');
                 dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'error' });
@@ -393,9 +414,7 @@ export function createActions(ctx) {
                 return;
             }
             try {
-                // The response carries the chat without its messages: update the
-                // chat and keep the conversation on screen.
-                dispatch({ type: 'UPDATE_CHAT', payload: await api.updateChatSettings(client, chatId, settings) });
+                dispatch({ type: 'MERGE_CHAT_SETTINGS', payload: await api.updateChatSettings(client, chatId, settings) });
             }
             catch (error) {
                 console.error('[AgentSDK] Failed to change chat settings:', error);
@@ -412,7 +431,7 @@ export function createActions(ctx) {
                 return;
             }
             try {
-                dispatch({ type: 'UPDATE_CHAT', payload: await api.setAgent(client, chatId, agentRef) });
+                dispatch({ type: 'MERGE_CHAT_AGENT', payload: await api.setAgent(client, chatId, agentRef) });
             }
             catch (error) {
                 console.error('[AgentSDK] Failed to switch the agent:', error);

package/dist/agent/api.d.ts

@@ -7,7 +7,7 @@
  *
  * /agents/run stays for A2A/programmatic use.
  */
-import type { ChatDTO, ChatMessageDTO, ChatSettingsRequest, InterruptDTO } from '../types';
+import type { AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, InterruptDTO, ToolExplanationDTO } from '../types';
 import type { AgentOptions, AgentClient, AgentInfo, FileRef } from './types';
 export interface SendResult {
     chatId: string;
@@ -36,7 +36,8 @@ export declare function fetchMessagesPage(client: AgentClient, chatId: string, o
 export declare function fetchChat(client: AgentClient, chatId: string): Promise<ChatDTO | null>;
 export declare function stopChat(client: AgentClient, chatId: string): Promise<void>;
 export declare function cancelMessage(client: AgentClient, messageId: string): Promise<void>;
-export declare function setAgent(client: AgentClient, chatId: string, agentRef: string): Promise<ChatDTO>;
+/** Hand the chat to another agent. Answers with the agent the chat now runs on. */
+export declare function setAgent(client: AgentClient, chatId: string, agentRef: string): Promise<ChatAgentDTO>;
 export declare function submitToolResult(client: AgentClient, toolInvocationId: string, resultOrAction: string | {
     action: {
         type: string;
@@ -46,8 +47,25 @@ export declare function submitToolResult(client: AgentClient, toolInvocationId:
 }): Promise<void>;
 export declare function approveTool(client: AgentClient, toolInvocationId: string): Promise<void>;
 export declare function rejectTool(client: AgentClient, toolInvocationId: string, reason?: string): Promise<void>;
-export declare function alwaysAllowTool(client: AgentClient, chatId: string, toolInvocationId: string, toolName: string): Promise<void>;
-export declare function updateChatSettings(client: AgentClient, chatId: string, settings: ChatSettingsRequest): Promise<ChatDTO>;
+/**
+ * What "always allow" can save for a call awaiting approval, narrowest first.
+ * The api computes the options from the call; each one, saved, answers it again.
+ */
+export declare function getAlwaysAllowOptions(client: AgentClient, chatId: string, toolInvocationId: string): Promise<AlwaysAllowOptionsDTO>;
+/**
+ * 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.
+ */
+export declare function alwaysAllowTool(client: AgentClient, chatId: string, toolInvocationId: string, option?: string): Promise<AlwaysAllowResultDTO>;
+/**
+ * Explain a call awaiting approval in plain words: what it does, why the agent
+ * appears to make it, and its risk. Generated by a model the first time and kept
+ * 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. */
+export declare function updateChatSettings(client: AgentClient, chatId: string, settings: ChatSettingsRequest): Promise<ChatSettingsDTO>;
 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

@@ -132,6 +132,7 @@ export async function stopChat(client, chatId) {
 export async function cancelMessage(client, messageId) {
     await client.http.request('post', `/chats/messages/${messageId}/cancel`);
 }
+/** Hand the chat to another agent. Answers with the agent the chat now runs on. */
 export async function setAgent(client, chatId, agentRef) {
     const resp = await client.http.request('post', `/chats/${chatId}/agent`, {
         data: { agent: agentRef },
@@ -151,11 +152,34 @@ export async function approveTool(client, toolInvocationId) {
 export async function rejectTool(client, toolInvocationId, reason) {
     await client.http.request('post', `/tools/${toolInvocationId}/reject`, { data: { reason } });
 }
-export async function alwaysAllowTool(client, chatId, toolInvocationId, toolName) {
-    await client.http.request('post', `/chats/${chatId}/tools/${toolInvocationId}/always-allow`, {
-        data: { tool_name: toolName }
-    });
+/**
+ * What "always allow" can save for a call awaiting approval, narrowest first.
+ * The api computes the options from the call; each one, saved, answers it again.
+ */
+export async function getAlwaysAllowOptions(client, chatId, toolInvocationId) {
+    const resp = await client.http.request('get', `/chats/${chatId}/tools/${toolInvocationId}/always-allow/options`);
+    return resp.data;
+}
+/**
+ * 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.
+ */
+export async function alwaysAllowTool(client, chatId, toolInvocationId, option) {
+    const data = option ? { option } : {};
+    const resp = await client.http.request('post', `/chats/${chatId}/tools/${toolInvocationId}/always-allow`, { data });
+    return resp.data;
+}
+/**
+ * Explain a call awaiting approval in plain words: what it does, why the agent
+ * appears to make it, and its risk. Generated by a model the first time and kept
+ * for the call, so asking again is free.
+ */
+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. */
 export async function updateChatSettings(client, chatId, settings) {
     const resp = await client.http.request('post', `/chats/${chatId}/settings`, { data: settings });
     return resp.data;

package/dist/agent/index.d.ts

@@ -46,6 +46,6 @@
 export { AgentChatProvider } from './provider';
 export { useAgentChat, useAgentActions, useAgentClient, useAgentChatContext, useMessage, } from './hooks';
 export { AgentChatContext, type AgentChatContextValue } from './context';
-export type { AgentClient, FileRef, AdHocAgentConfig, TemplateAgentConfig, AgentOptions, AgentChatState, AgentChatActions, ChatStatus, AgentChatProviderProps, ClientTool, ClientToolHandlerFn, } from './types';
+export type { AgentClient, FileRef, AdHocAgentConfig, TemplateAgentConfig, AgentOptions, AgentChatState, AgentChatActions, AlwaysAllowChoice, ChatStatus, AgentChatProviderProps, ClientTool, ClientToolHandlerFn, } from './types';
 export { isAdHocConfig, isTemplateConfig, isClientTool, extractToolSchemas, extractClientToolHandlers, } from './types';
 export { MCPMethodElicitationCreate, parseMCPInputState, elicitParams, isURLElicitation, buildMCPInputResult, type MCPInputState, type ElicitRequestParams, type ElicitRequestedSchema, type ElicitPropertySchema, } from './mcp-input';

package/dist/agent/reducer.js

@@ -50,6 +50,43 @@ export function chatReducer(state, action) {
                 return state;
             return { ...state, chat };
         }
+        // The settings and set-agent endpoints answer with only what they wrote.
+        // Merge it into the chat it belongs to; a chat switched away from in the
+        // meantime is left alone.
+        case 'MERGE_CHAT_SETTINGS': {
+            const settings = action.payload;
+            if (!state.chat || state.chat.id !== settings.chat_id)
+                return state;
+            return {
+                ...state,
+                chat: {
+                    ...state.chat,
+                    name: settings.name,
+                    visibility: settings.visibility,
+                    agent_data: {
+                        ...state.chat.agent_data,
+                        allow_all_tools: settings.allow_all_tools,
+                        disable_hooks: settings.disable_hooks,
+                        memory: settings.memory,
+                    },
+                },
+            };
+        }
+        case 'MERGE_CHAT_AGENT': {
+            const agent = action.payload;
+            if (!state.chat || state.chat.id !== agent.chat_id)
+                return state;
+            return {
+                ...state,
+                chat: {
+                    ...state.chat,
+                    agent_id: agent.agent_id,
+                    agent: agent.agent,
+                    agent_version_id: agent.agent_version_id,
+                    agent_version: agent.agent_version,
+                },
+            };
+        }
         case 'UPDATE_ACTIVE_RUN': {
             if (!state.chat)
                 return state;

package/dist/agent/types.d.ts

@@ -4,11 +4,15 @@
  * Public types for the Agent chat module.
  */
 import type { Dispatch } from 'react';
-import type { AgentRunDTO, AgentVersionDTO, ChatDTO, ChatMessageDTO, ChatSettingsRequest, AgentTool, AgentConfigInput as GeneratedAgentConfig, CoreAppConfigInput as CoreAppConfig, FileRef, ElicitResult } from '../types';
+import type { AgentRunDTO, AgentVersionDTO, AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ToolExplanationDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, AgentTool, AgentConfigInput as GeneratedAgentConfig, CoreAppConfigInput as CoreAppConfig, FileRef, ElicitResult } from '../types';
 import type { HttpClient } from '../http/client';
 import type { StreamableManager } from '../http/streamable';
 import type { PollManager } from '../http/poll';
 export type { FileRef } from '../types';
+/** The "always allow" option to save: a key from getAlwaysAllowOptions. */
+export interface AlwaysAllowChoice {
+    option?: string;
+}
 /**
  * Minimal client interface required by the agent module.
  * This allows extended clients (like the app client) to be used.
@@ -132,8 +136,26 @@ export interface AgentChatActions {
     approveTool: (toolInvocationId: string) => Promise<void>;
     /** Reject a tool (for HIL approval - AwaitingApproval status) */
     rejectTool: (toolInvocationId: string, reason?: string) => Promise<void>;
-    /** Always allow a tool for this chat (approves + auto-approves future invocations) */
-    alwaysAllowTool: (toolInvocationId: string, toolName: string) => Promise<void>;
+    /**
+     * What "always allow" can save for a call awaiting approval, narrowest
+     * first, as computed by the api (null without a chat). Show the options'
+     * labels in order; `default` is the narrowest that answers the call again.
+     */
+    getAlwaysAllowOptions: (toolInvocationId: string) => Promise<AlwaysAllowOptionsDTO | null>;
+    /**
+     * Explain a call awaiting approval (risk level, what it does, why, what could
+     * go wrong). A model generates it the first time it is asked for; later calls
+     * return the kept answer. Call it only when the person asks.
+     */
+    explainTool: (toolInvocationId: string) => Promise<ToolExplanationDTO>;
+    /**
+     * Always allow a call: save the chosen option's chat rules (`{ option: key }`
+     * from getAlwaysAllowOptions) and approve the call once. Without an option the
+     * 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.
+     */
+    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) */
     updateChatSettings: (settings: ChatSettingsRequest) => Promise<void>;
     /** Hand this chat to another agent (namespace/name); the next message goes to it. Agents our loop runs only. */
@@ -211,6 +233,12 @@ export type ChatAction = {
 } | {
     type: 'UPDATE_CHAT';
     payload: ChatDTO | null;
+} | {
+    type: 'MERGE_CHAT_SETTINGS';
+    payload: ChatSettingsDTO;
+} | {
+    type: 'MERGE_CHAT_AGENT';
+    payload: ChatAgentDTO;
 } | {
     type: 'UPDATE_ACTIVE_RUN';
     payload: AgentRunDTO;

package/dist/api/agents.js

@@ -296,6 +296,10 @@ export class Agent {
         const intervalMs = options.pollIntervalMs ?? this.http.getPollIntervalMs();
         let prevStatus = null;
         let knownMessageIds = new Set();
+        // Returned by the poll when nothing changed. Compared by identity: a
+        // fetched chat never carries chat_messages, so their absence cannot tell
+        // the two apart.
+        const unchanged = {};
         return new Promise((resolve) => {
             this.poller?.stop();
             this.poller = new PollManager({
@@ -305,17 +309,15 @@ export class Agent {
                     const status = statusResp.data;
                     // Unchanged status is skipped — unless the turn is still ungated: a run
                     // that started and finished between two polls only shows in the messages.
-                    if (status.status === prevStatus && gate.settled) {
-                        // No change — return a stub to skip processing
-                        return { status: status.status };
-                    }
+                    if (status.status === prevStatus && gate.settled)
+                        return unchanged;
                     // Status changed — fetch full chat
                     const chatResp = await this.http.request('get', `/chats/${this.chatId}`);
                     return chatResp.data;
                 },
                 intervalMs,
                 onData: (chat) => {
-                    if (chat.status === prevStatus && !chat.chat_messages)
+                    if (chat === unchanged)
                         return;
                     prevStatus = chat.status;
                     options.onChat?.(chat);

package/dist/types.d.ts

@@ -1777,6 +1777,37 @@ export interface ChatSettingsRequest {
      */
     forget_memory?: string[];
 }
+/**
+ * ChatSettingsDTO is what POST /chats/{id}/settings answers with: the chat's
+ * settings after the change, every field the endpoint writes and nothing
+ * else. A client merges it into the chat it holds.
+ */
+export interface ChatSettingsDTO {
+    chat_id: string;
+    name: string;
+    visibility: Visibility;
+    /**
+     * AllowAllTools and DisableHooks are agent_data.allow_all_tools and
+     * agent_data.disable_hooks on the chat.
+     */
+    allow_all_tools: boolean;
+    disable_hooks: boolean;
+    /**
+     * Memory is agent_data.memory after forget_memory removed its keys.
+     */
+    memory: StringEncodedMap;
+}
+/**
+ * ChatAgentDTO is what POST /chats/{id}/agent answers with: the agent the
+ * chat now runs on. A client merges it into the chat it holds.
+ */
+export interface ChatAgentDTO {
+    chat_id: string;
+    agent_id: string;
+    agent?: AgentDTO;
+    agent_version_id: string;
+    agent_version?: AgentVersionDTO;
+}
 /**
  * ChatDTO for API responses
  */
@@ -1800,7 +1831,12 @@ export interface ChatDTO extends BaseModelDTO, PermissionModelDTO {
     agent_version?: AgentVersionDTO;
     name: string;
     description: string;
-    chat_messages: ChatMessageDTO[];
+    /**
+     * ChatMessages is left out when the messages were not loaded. The chat
+     * endpoints do not load them; read them from GET /chats/{id}/messages.
+     * An absent field says nothing about whether the chat has messages.
+     */
+    chat_messages?: ChatMessageDTO[];
     agent_data: ChatData;
     active_run?: AgentRunDTO;
     pending_interrupts?: InterruptDTO[];
@@ -1834,6 +1870,189 @@ export interface ChatMessageDTO extends BaseModelDTO, PermissionModelDTO {
     tool_call_id?: string;
     tool_invocations?: ToolInvocationDTO[];
 }
+/**
+ * PolicyEffect is a rule's outcome: allow, ask or deny.
+ */
+export type PolicyEffect = "allow" | "ask" | "deny";
+export declare const PolicyEffectAllow: PolicyEffect;
+export declare const PolicyEffectAsk: PolicyEffect;
+export declare const PolicyEffectDeny: PolicyEffect;
+/**
+ * PolicyRuleDTO is one rule, typed form Kind[selector](specifier).
+ */
+export interface PolicyRuleDTO {
+    id: string;
+    effect: PolicyEffect;
+    /**
+     * Kind: RemoteExec, Workspace, Harness, Tool (and, from phase 3, App,
+     * Agent, Knowledge, Mcp, Flow, WebFetch).
+     */
+    kind: string;
+    /**
+     * Selector narrows the rule to one remote (its id) or a tag (tag:<name>);
+     * empty applies everywhere.
+     */
+    selector: string;
+    /**
+     * Specifier is the kind's pattern: a command (`npm test`, `git push:*`),
+     * a folder (`~/proj/**`), a harness tool with its pattern
+     * (`Bash(git status:*)`, `Edit`), or a loop tool's name. Empty is the
+     * whole kind.
+     */
+    specifier: string;
+    /**
+     * Label is the rule in words, e.g. "git commit commands on Laptop", the
+     * same words an approval prompt's "always allow" options use.
+     */
+    label: string;
+    /**
+     * CreatedAt is null for a rule that is not a stored row yet: an entry of
+     * the chat's always-allow list from before rules existed, or the chat's
+     * "allow every tool" setting.
+     */
+    created_at?: string;
+    /**
+     * CreatedBy is the user who wrote the rule; empty for those above.
+     */
+    created_by: string;
+}
+/**
+ * AlwaysAllowScope is how far an "always allow" option reaches, narrowest
+ * first.
+ */
+export type AlwaysAllowScope = "exact" | "prefix" | "folder" | "remote" | "tool";
+/**
+ * AlwaysAllowScopeExact: this call exactly (each piece of the command,
+ * the file, the domain).
+ */
+export declare const AlwaysAllowScopeExact: AlwaysAllowScope;
+/**
+ * AlwaysAllowScopePrefix: commands that start the same way, per piece
+ * (git commit:*, npm run:*).
+ */
+export declare const AlwaysAllowScopePrefix: AlwaysAllowScope;
+/**
+ * AlwaysAllowScopeFolder: files in the same folder.
+ */
+export declare const AlwaysAllowScopeFolder: AlwaysAllowScope;
+/**
+ * AlwaysAllowScopeRemote: every command on the machine.
+ */
+export declare const AlwaysAllowScopeRemote: AlwaysAllowScope;
+/**
+ * AlwaysAllowScopeTool: every call of the tool.
+ */
+export declare const AlwaysAllowScopeTool: AlwaysAllowScope;
+/**
+ * AlwaysAllowOptionDTO is one "always allow" choice on an approval prompt:
+ * the chat rules it saves.
+ */
+export interface AlwaysAllowOptionDTO {
+    /**
+     * Key names the option in POST .../always-allow. It changes when the
+     * rules it stands for change.
+     */
+    key: string;
+    scope: AlwaysAllowScope;
+    /**
+     * Label is the option in words, e.g. "git clone commands on Laptop".
+     */
+    label: string;
+    /**
+     * Description adds why a broad option is the narrowest offered, e.g.
+     * the command uses shell syntax no narrower rule can match.
+     */
+    description?: string;
+    /**
+     * Rules are the chat rules the option saves (not stored yet: no id).
+     */
+    rules: PolicyRuleDTO[];
+}
+/**
+ * AlwaysAllowOptionsDTO is GET /chats/{id}/tools/{toolId}/always-allow/options:
+ * the options for a call awaiting approval, narrowest first. Each one,
+ * saved, answers this call again. Computed by the api from the call; the
+ * client never builds rules.
+ */
+export interface AlwaysAllowOptionsDTO {
+    options: AlwaysAllowOptionDTO[];
+    /**
+     * Default is the key of the narrowest option, "" when there is none.
+     */
+    default?: string;
+    /**
+     * Unavailable says why there are no options: a policy allows only its
+     * own rules, or no chat rule could allow this call.
+     */
+    unavailable?: string;
+}
+/**
+ * AlwaysAllowRequest is POST /chats/{id}/tools/{toolId}/always-allow. The
+ * api saves the option's rules to the chat and approves the call once.
+ */
+export interface AlwaysAllowRequest {
+    /**
+     * Option is an option key from the options endpoint. A key that no
+     * longer names a current option is refused (409). Without one, the
+     * call saves what "always allow" saved before options existed: the
+     * command's pieces exactly for remote_exec, the whole tool otherwise.
+     */
+    option?: string;
+    /**
+     * ToolName is accepted from older clients and ignored: the call names
+     * its own tool.
+     */
+    tool_name?: string;
+}
+/**
+ * AlwaysAllowResultDTO is what an always-allow saved.
+ */
+export interface AlwaysAllowResultDTO {
+    /**
+     * Option is the option chosen; null for a call without one.
+     */
+    option?: AlwaysAllowOptionDTO;
+    /**
+     * Rules are the chat rules now in place for it.
+     */
+    rules: PolicyRuleDTO[];
+}
+/**
+ * ToolRiskLevel is how risky an explained call is.
+ */
+export type ToolRiskLevel = "low" | "medium" | "high";
+/**
+ * ToolRiskLow: safe development workflows (reads, builds, tests).
+ */
+export declare const ToolRiskLow: ToolRiskLevel;
+/**
+ * ToolRiskMedium: changes that can be undone.
+ */
+export declare const ToolRiskMedium: ToolRiskLevel;
+/**
+ * ToolRiskHigh: dangerous or irreversible changes.
+ */
+export declare const ToolRiskHigh: ToolRiskLevel;
+/**
+ * ToolExplanationDTO is POST /chats/{id}/tools/{toolId}/explain: a model's
+ * plain-words reading of a call awaiting approval (Claude Code's permission
+ * explainer). Generated once, when the person asks, and kept for the call.
+ */
+export interface ToolExplanationDTO {
+    risk_level: ToolRiskLevel;
+    /**
+     * Explanation is what the call does, in one or two sentences.
+     */
+    explanation: string;
+    /**
+     * Reasoning is why the agent appears to be making it.
+     */
+    reasoning: string;
+    /**
+     * Risk is what could go wrong, in a few words.
+     */
+    risk: string;
+}
 /**
  * CredentialDTO is the API response for a credential (never exposes secrets).
  */

package/dist/types.js

@@ -302,6 +302,43 @@ export const ScopeGroupKnowledge = "knowledge";
 export const ScopeGroupArtifacts = "artifacts";
 export const ScopeGroupUser = "user";
 export const ScopeGroupSettings = "settings";
+export const PolicyEffectAllow = "allow";
+export const PolicyEffectAsk = "ask";
+export const PolicyEffectDeny = "deny";
+/**
+ * AlwaysAllowScopeExact: this call exactly (each piece of the command,
+ * the file, the domain).
+ */
+export const AlwaysAllowScopeExact = "exact";
+/**
+ * AlwaysAllowScopePrefix: commands that start the same way, per piece
+ * (git commit:*, npm run:*).
+ */
+export const AlwaysAllowScopePrefix = "prefix";
+/**
+ * AlwaysAllowScopeFolder: files in the same folder.
+ */
+export const AlwaysAllowScopeFolder = "folder";
+/**
+ * AlwaysAllowScopeRemote: every command on the machine.
+ */
+export const AlwaysAllowScopeRemote = "remote";
+/**
+ * AlwaysAllowScopeTool: every call of the tool.
+ */
+export const AlwaysAllowScopeTool = "tool";
+/**
+ * ToolRiskLow: safe development workflows (reads, builds, tests).
+ */
+export const ToolRiskLow = "low";
+/**
+ * ToolRiskMedium: changes that can be undone.
+ */
+export const ToolRiskMedium = "medium";
+/**
+ * ToolRiskHigh: dangerous or irreversible changes.
+ */
+export const ToolRiskHigh = "high";
 export const ErrorCodeInvalidRequest = "invalid_request";
 export const ErrorCodeValidationError = "validation_error";
 export const ErrorCodeUnauthorized = "unauthorized";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/sdk",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Official JavaScript/TypeScript SDK for inference.sh - Run AI models with a simple API",
   "type": "module",
   "main": "dist/index.js",