@inferencesh/sdk 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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' });

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, ChatDTO, ChatMessageDTO, ChatSettingsRequest, InterruptDTO, ToolExplanationDTO } from '../types';
 import type { AgentOptions, AgentClient, AgentInfo, FileRef } from './types';
 export interface SendResult {
     chatId: string;
@@ -46,7 +46,23 @@ 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>;
+/**
+ * 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>;
 export declare function updateChatSettings(client: AgentClient, chatId: string, settings: ChatSettingsRequest): Promise<ChatDTO>;
 export declare function resolveInterrupt(client: AgentClient, interruptId: string, decision: 'allow' | 'deny'): Promise<InterruptDTO>;
 export declare function listRunInterrupts(client: AgentClient, runId: string): Promise<InterruptDTO[]>;

package/dist/agent/api.js

@@ -151,10 +151,32 @@ 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;
 }
 export async function updateChatSettings(client, chatId, settings) {
     const resp = await client.http.request('post', `/chats/${chatId}/settings`, { data: settings });

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/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, ChatDTO, ChatMessageDTO, 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. */

package/dist/types.d.ts

@@ -1834,6 +1834,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.16.0",
   "description": "Official JavaScript/TypeScript SDK for inference.sh - Run AI models with a simple API",
   "type": "module",
   "main": "dist/index.js",