@inferencesh/sdk 0.22.0 → 0.23.0

package/dist/types.d.ts

@@ -72,13 +72,21 @@ export interface SkillConfig {
     preload?: boolean;
 }
 /**
- * ContextField declares a context parameter expected by the agent.
+ * ContextField declares a context parameter expected by the agent. The
+ * agent's prompt names it with its description, and the agent writes
+ * {{context.NAME}} in a tool call's arguments for the server to fill in;
+ * it does not see the value unless InPrompt.
  */
 export interface ContextField {
     name: string;
     description?: string;
     required?: boolean;
     default?: string;
+    /**
+     * InPrompt shows the value to the model too, in the system prompt,
+     * labeled as the caller's data and quoted.
+     */
+    in_prompt?: boolean;
 }
 /**
  * AgentToolDTO for API responses
@@ -443,39 +451,51 @@ export interface ApiAppRunRequest {
     metadata?: TaskMetadata;
 }
 /**
- * ApiAgentRunRequest is the request body for /agents/run endpoint.
+ * MessageInput is a message a caller sends to an agent: its text and the
+ * files sent with it. The model, its settings, the system prompt, the tools
+ * and the history come from the agent and the chat. Every endpoint that
+ * takes a message decodes this type.
  */
-export interface ApiAgentRunRequest {
-    chat_id?: string;
-    agent?: string;
-    agent_config?: AgentConfigInput;
-    agent_name?: string;
-    input: LLMInput;
-    context?: {
-        [key: string]: string;
-    };
-    stream?: boolean;
+export interface MessageInput {
+    text?: string;
     /**
-     * ChannelContext is recorded on the chat the first time it is seen.
+     * Attachments are files uploaded with POST /files. Images reach the
+     * model as image input.
      */
-    channel_context?: ChannelContext;
+    attachments?: FileRef[];
+    /**
+     * Deprecated: send Attachments. Image URIs, read only when Attachments
+     * is empty.
+     */
+    images?: string[];
+    /**
+     * Deprecated: send Attachments. File URIs, read only when Attachments
+     * is empty.
+     */
+    files?: string[];
 }
 /**
- * CreateAgentMessageRequest is the request for creating agent messages.
+ * ApiAgentRunRequest is the request body of POST /agents/run and its aliases
+ * /agents/message and /agents/messages. It names the agent once: by ref
+ * (agent), by id (agent_id, with an optional agent_version_id), or by an
+ * ad-hoc agent_config; or names none and posts into chat_id's chat.
  */
-export interface CreateAgentMessageRequest {
+export interface ApiAgentRunRequest {
     chat_id?: string;
+    agent?: string;
+    /**
+     * AgentID names a stored agent by id; AgentVersionID pins one of its
+     * versions (full or short id), else the agent's current version runs.
+     */
     agent_id?: string;
     agent_version_id?: string;
-    agent?: string;
-    tool_call_id?: string;
-    input: LLMInput;
-    channel_context?: ChannelContext;
     agent_config?: AgentConfigInput;
     agent_name?: string;
+    input: MessageInput;
     context?: {
         [key: string]: string;
     };
+    stream?: boolean;
 }
 export interface CreateAgentMessageResponse {
     user_message?: ChatMessageDTO;
@@ -863,7 +883,7 @@ export interface EstimateCostResponse {
 /**
  * Scope represents an API key permission scope string.
  */
-export type Scope = "*" | "agents" | "apps" | "conversations" | "files" | "datastores" | "templates" | "flows" | "projects" | "teams" | "billing" | "artifacts" | "agents:read" | "agents:write" | "agents:execute" | "apps:read" | "apps:write" | "apps:execute" | "conversations:read" | "conversations:write" | "files:read" | "files:write" | "datastores:read" | "datastores:write" | "flows:read" | "flows:write" | "flows:execute" | "projects:read" | "projects:write" | "teams:read" | "teams:write" | "billing:read" | "billing:write" | "secrets:read" | "secrets:write" | "secrets:reveal" | "credentials:read" | "credentials:write" | "engines:read" | "engines:write" | "remotes:read" | "remotes:write" | "apikeys:read" | "apikeys:write" | "knowledge:read" | "knowledge:write" | "artifacts:read" | "artifacts:write" | "user:read" | "user:write" | "settings:read" | "settings:write" | "approvals:write" | "admin:read" | "admin:write" | "admin:pricing";
+export type Scope = "*" | "agents" | "apps" | "conversations" | "files" | "datastores" | "templates" | "flows" | "projects" | "teams" | "billing" | "artifacts" | "agents:read" | "agents:write" | "agents:execute" | "apps:read" | "apps:write" | "apps:execute" | "conversations:read" | "conversations:write" | "files:read" | "files:write" | "datastores:read" | "datastores:write" | "flows:read" | "flows:write" | "flows:execute" | "projects:read" | "projects:write" | "teams:read" | "teams:write" | "billing:read" | "billing:write" | "secrets:read" | "secrets:write" | "secrets:reveal" | "credentials:read" | "credentials:write" | "engines:read" | "engines:write" | "remotes:read" | "remotes:write" | "apikeys:read" | "apikeys:write" | "knowledge:read" | "knowledge:write" | "artifacts:read" | "artifacts:write" | "user:read" | "user:write" | "settings:read" | "settings:write" | "approvals:write" | "admin:read" | "admin:write" | "store:pricing" | "store:submit";
 /**
  * API Key Scopes - hierarchical permission system.
  * Resource-level scopes (e.g., "agents") imply all action-level scopes (e.g., "agents:read").
@@ -1158,17 +1178,22 @@ export declare const ScopeAdminRead: Scope;
  */
 export declare const ScopeAdminWrite: Scope;
 /**
- * ScopeAdminPricing reads and changes store pricing: a version's
- * terms, its draft pricing (edit, evaluate, discard, publish, apply to
- * the listing) and the sample tasks drafts are evaluated against. Held
- * by an admin's own sign-in with platform power, and by a key of the
- * platform's automation account (ScopeDefinition.Automation).
+ * ScopeStorePricing reads and changes store pricing: a version's terms,
+ * its draft pricing (edit, evaluate, discard, publish, apply to the
+ * listing) and the sample tasks drafts are evaluated against. Held only
+ * in the platform's workspace (the system team), by its members, their
+ * keys and runs, and its own keys.
  */
-export declare const ScopeAdminPricing: Scope;
+export declare const ScopeStorePricing: Scope;
+/**
+ * ScopeStoreSubmit submits a resource version to the store on its
+ * publisher's behalf. Held like ScopeStorePricing.
+ */
+export declare const ScopeStoreSubmit: Scope;
 /**
  * ScopeGroup identifies a category of scopes for UI grouping
  */
-export type ScopeGroup = "agents" | "apps" | "conversations" | "files" | "datastores" | "flows" | "projects" | "teams" | "billing" | "secrets" | "credentials" | "engines" | "remotes" | "apikeys" | "knowledge" | "artifacts" | "user" | "settings" | "approvals" | "admin";
+export type ScopeGroup = "agents" | "apps" | "conversations" | "files" | "datastores" | "flows" | "projects" | "teams" | "billing" | "secrets" | "credentials" | "engines" | "remotes" | "apikeys" | "knowledge" | "artifacts" | "user" | "settings" | "approvals" | "admin" | "store";
 export declare const ScopeGroupAgents: ScopeGroup;
 export declare const ScopeGroupApps: ScopeGroup;
 export declare const ScopeGroupConversations: ScopeGroup;
@@ -1189,6 +1214,7 @@ export declare const ScopeGroupUser: ScopeGroup;
 export declare const ScopeGroupSettings: ScopeGroup;
 export declare const ScopeGroupApprovals: ScopeGroup;
 export declare const ScopeGroupAdmin: ScopeGroup;
+export declare const ScopeGroupStore: ScopeGroup;
 /**
  * ScopeDefinition describes a single scope for UI rendering
  */
@@ -1214,13 +1240,6 @@ export interface ScopeDefinition {
      * apps, agents, flows).
      */
     costs_credits?: boolean;
-    /**
-     * Automation: a narrow platform-administration scope that a workspace
-     * key of the platform's automation account (the system team's service
-     * account) may hold, minted by an admin with platform power and always
-     * expiring. Every other key, token and app holds no admin scope.
-     */
-    automation?: boolean;
 }
 /**
  * ScopeGroupDefinition describes a group of scopes for UI rendering
@@ -1255,6 +1274,11 @@ export interface ScopesResponse {
      * key or app is ever granted one.
      */
     account_scopes: ScopeDefinition[];
+    /**
+     * AccountGroups are the groups AccountScopes fall in, so the page labels
+     * them the way it labels Groups.
+     */
+    account_groups: ScopeGroupDefinition[];
     /**
      * LoginPreset is what the device approval page preselects for
      * `belt login`: the standard preset plus approvals:write (answering
@@ -1366,6 +1390,18 @@ export interface AppFunction {
      * a stream function declares a socket parameter. Empty means run.
      */
     kind?: FunctionKind;
+    /**
+     * Credentials the function needs at run time, declared on the function
+     * in app code. Each must be covered by the app-wide list in inf.yml.
+     * Empty means the function gets the app-wide list.
+     */
+    credentials?: CredentialRequirement[];
+    /**
+     * Annotations are MCP tool hints (read-only, destructive, idempotent,
+     * open-world) declared on the function. Hints only: nothing trusts
+     * them for an unverified namespace.
+     */
+    annotations?: ToolAnnotations;
 }
 /**
  * AppImages holds developer-provided images for the app.
@@ -1531,6 +1567,28 @@ export interface AppVersionDTO extends BaseModelDTO {
      */
     sandbox?: AppSandbox;
     checksum?: string;
+    /**
+     * Warnings are what the deploy that created this version accepted but
+     * the author should fix. Only the deploy's own response carries them.
+     */
+    warnings?: DeployWarning[];
+}
+/**
+ * DeployWarning is something a deploy accepted but the author should fix:
+ * the app works, but asks for more than it needs or says less than clients
+ * use.
+ */
+export interface DeployWarning {
+    /**
+     * Code identifies the check: readonly_broad_credential,
+     * unused_credential, missing_annotations.
+     */
+    code: string;
+    /**
+     * Function is the function the warning is about, when it is about one.
+     */
+    function?: string;
+    message: string;
 }
 /**
  * LicenseRecordDTO is the API response for a license record.
@@ -2843,8 +2901,9 @@ export declare const ErrorCodeFeatureNotAvailable: ErrorCode;
 export declare const ErrorCodeEntitlementUnavailable: ErrorCode;
 export declare const ErrorCodePaymentRequired: ErrorCode;
 /**
- * ErrorCodePaymentMethodRequired (402): a bounty program requires a saved
- * payment method and the caller's team has none. Meta is
+ * ErrorCodePaymentMethodRequired (402): the action needs a saved payment
+ * method and the caller's team has none: a bounty program that requires
+ * one, or a free app run without a balance. Meta is
  * PaymentMethodRequiredMeta; clients send the user to BillingPage.
  */
 export declare const ErrorCodePaymentMethodRequired: ErrorCode;
@@ -2921,9 +2980,10 @@ export interface ScopeRefusedMeta {
 }
 /**
  * PaymentMethodRequiredMeta is the meta of a payment_method_required error.
+ * BountyID is set when a bounty claim was refused.
  */
 export interface PaymentMethodRequiredMeta {
-    bounty_id: string;
+    bounty_id?: string;
     billing_page: string;
 }
 /**
@@ -3778,6 +3838,21 @@ export interface ResourceContent {
         [key: string]: any;
     };
 }
+/**
+ * ToolAnnotations describes tool behavior so clients can make trust and UX
+ * decisions (e.g., auto-approve read-only tools). All fields are optional hints.
+ */
+export interface ToolAnnotations {
+    /**
+     * Title is the human-readable name clients and the Claude directory show.
+     * It repeats MCPTool.Title because some clients read only this one.
+     */
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 /**
  * ToolCallRequest represents a request to call a tool.
  * InputResponses and RequestState are present on MRTR retries: the client is
@@ -6762,7 +6837,7 @@ export interface UtilityConfig {
  * These are the backbone protocol events — every consumer (A2A, SDK, frontend)
  * projects from this set.
  */
-export type AgentEventType = "run.started" | "run.state_changed" | "turn.started" | "turn.completed" | "content.delta" | "tool.started" | "tool.completed" | "approval.required" | "approval.resolved" | "hook.executed" | "usage.updated" | "context.compacted" | "error";
+export type AgentEventType = "run.started" | "run.state_changed" | "turn.started" | "turn.completed" | "content.delta" | "tool.started" | "tool.completed" | "approval.required" | "approval.resolved" | "hook.executed" | "usage.updated" | "context.updated" | "limits.updated" | "account.updated" | "context.compacted" | "error" | "subagent.started" | "subagent.updated" | "subagent.completed";
 /**
  * Run lifecycle
  */
@@ -6793,9 +6868,14 @@ export declare const AgentEventApprovalResolved: AgentEventType;
  */
 export declare const AgentEventHookExecuted: AgentEventType;
 /**
- * Usage
+ * Usage: a turn's tokens (usage.updated), the context window's fill
+ * (context.updated), the plan's rate limits (limits.updated) and the
+ * account the agent runs as (account.updated).
  */
 export declare const AgentEventUsageUpdated: AgentEventType;
+export declare const AgentEventContextUpdated: AgentEventType;
+export declare const AgentEventLimitsUpdated: AgentEventType;
+export declare const AgentEventAccountUpdated: AgentEventType;
 /**
  * Context management
  */
@@ -6840,6 +6920,10 @@ export interface TurnCompletedPayload {
 export interface ContentDeltaPayload {
     kind: ContentDeltaKind;
     delta: string;
+    /**
+     * SubagentID is set on a subagent's own output (subagent_types.go).
+     */
+    subagent_id?: string;
 }
 export type ContentDeltaKind = "text" | "reasoning";
 export declare const ContentDeltaText: ContentDeltaKind;
@@ -6850,6 +6934,10 @@ export interface ToolStartedPayload {
     tool_type?: ToolType;
     display_name?: string;
     arguments?: StringEncodedMap;
+    /**
+     * SubagentID is set on a subagent's own tool calls.
+     */
+    subagent_id?: string;
 }
 export interface ToolCompletedPayload {
     tool_invocation_id: string;
@@ -6857,12 +6945,21 @@ export interface ToolCompletedPayload {
     status: ToolInvocationStatus;
     result?: string;
     duration_ms?: number;
+    /**
+     * SubagentID is set on a subagent's own tool calls.
+     */
+    subagent_id?: string;
 }
 export interface ApprovalRequiredPayload {
     tool_invocation_id: string;
     tool_name: string;
     arguments?: StringEncodedMap;
     reason: InterruptReason;
+    /**
+     * SubagentID is set when a subagent asks: its tool call, not the
+     * agent's.
+     */
+    subagent_id?: string;
 }
 export interface ApprovalResolvedPayload {
     tool_invocation_id: string;
@@ -6876,12 +6973,23 @@ export interface HookExecutedPayload {
     reason?: string;
     duration_ms?: number;
 }
+/**
+ * UsageUpdatedPayload is what one turn used, emitted once when the turn
+ * ends. PromptTokens counts every input token, cached or not:
+ * CachedInputTokens (read from a prompt cache) and CacheCreationTokens
+ * (written to one) are parts of it. ReasoningTokens is part of
+ * CompletionTokens. CostUSD is the agent's own figure, 0 when it reports
+ * none.
+ */
 export interface UsageUpdatedPayload {
     prompt_tokens: number;
     completion_tokens: number;
     total_tokens: number;
+    cached_input_tokens?: number;
+    cache_creation_tokens?: number;
     reasoning_tokens?: number;
     cost_usd?: number;
+    status?: TurnUsageStatus;
 }
 export interface ContextCompactedPayload {
     before_tokens: number;
@@ -7095,6 +7203,9 @@ export interface ToolResultEventData {
 export interface ErrorEventData {
     error: string;
 }
+export declare const AgentEventSubagentStarted: AgentEventType;
+export declare const AgentEventSubagentUpdated: AgentEventType;
+export declare const AgentEventSubagentCompleted: AgentEventType;
 /**
  * ToolInvocationStatus represents the execution status of a tool invocation
  */
@@ -7247,3 +7358,16 @@ export interface ToolParameterProperty {
     items?: ToolParameterProperty;
     required?: string[];
 }
+/**
+ * TurnUsageStatus says how much of a turn's usage the agent reported.
+ */
+export type TurnUsageStatus = "complete" | "partial";
+/**
+ * TurnUsageComplete is the whole turn, as the agent counted it.
+ */
+export declare const TurnUsageComplete: TurnUsageStatus;
+/**
+ * TurnUsagePartial is what was reported before the turn ended early
+ * (interrupted, failed).
+ */
+export declare const TurnUsagePartial: TurnUsageStatus;

package/dist/types.js

@@ -309,13 +309,18 @@ export const ScopeAdminRead = "admin:read";
  */
 export const ScopeAdminWrite = "admin:write";
 /**
- * ScopeAdminPricing reads and changes store pricing: a version's
- * terms, its draft pricing (edit, evaluate, discard, publish, apply to
- * the listing) and the sample tasks drafts are evaluated against. Held
- * by an admin's own sign-in with platform power, and by a key of the
- * platform's automation account (ScopeDefinition.Automation).
+ * ScopeStorePricing reads and changes store pricing: a version's terms,
+ * its draft pricing (edit, evaluate, discard, publish, apply to the
+ * listing) and the sample tasks drafts are evaluated against. Held only
+ * in the platform's workspace (the system team), by its members, their
+ * keys and runs, and its own keys.
  */
-export const ScopeAdminPricing = "admin:pricing";
+export const ScopeStorePricing = "store:pricing";
+/**
+ * ScopeStoreSubmit submits a resource version to the store on its
+ * publisher's behalf. Held like ScopeStorePricing.
+ */
+export const ScopeStoreSubmit = "store:submit";
 export const ScopeGroupAgents = "agents";
 export const ScopeGroupApps = "apps";
 export const ScopeGroupConversations = "conversations";
@@ -336,6 +341,7 @@ export const ScopeGroupUser = "user";
 export const ScopeGroupSettings = "settings";
 export const ScopeGroupApprovals = "approvals";
 export const ScopeGroupAdmin = "admin";
+export const ScopeGroupStore = "store";
 /**
  * AlwaysAllowScopeExact: this call exactly (each piece of the command,
  * the file, the domain).
@@ -476,8 +482,9 @@ export const ErrorCodeFeatureNotAvailable = "feature_not_available";
 export const ErrorCodeEntitlementUnavailable = "entitlement_unavailable";
 export const ErrorCodePaymentRequired = "payment_required";
 /**
- * ErrorCodePaymentMethodRequired (402): a bounty program requires a saved
- * payment method and the caller's team has none. Meta is
+ * ErrorCodePaymentMethodRequired (402): the action needs a saved payment
+ * method and the caller's team has none: a bounty program that requires
+ * one, or a free app run without a balance. Meta is
  * PaymentMethodRequiredMeta; clients send the user to BillingPage.
  */
 export const ErrorCodePaymentMethodRequired = "payment_method_required";
@@ -1474,9 +1481,14 @@ export const AgentEventApprovalResolved = "approval.resolved";
  */
 export const AgentEventHookExecuted = "hook.executed";
 /**
- * Usage
+ * Usage: a turn's tokens (usage.updated), the context window's fill
+ * (context.updated), the plan's rate limits (limits.updated) and the
+ * account the agent runs as (account.updated).
  */
 export const AgentEventUsageUpdated = "usage.updated";
+export const AgentEventContextUpdated = "context.updated";
+export const AgentEventLimitsUpdated = "limits.updated";
+export const AgentEventAccountUpdated = "account.updated";
 /**
  * Context management
  */
@@ -1541,6 +1553,9 @@ export const BuiltinHookBeltSuggest = "belt:suggest";
  * compaction drops the turns it would have learned from.
  */
 export const BuiltinHookBeltExtract = "belt:extract";
+export const AgentEventSubagentStarted = "subagent.started";
+export const AgentEventSubagentUpdated = "subagent.updated";
+export const AgentEventSubagentCompleted = "subagent.completed";
 export const ToolInvocationStatusPending = "pending";
 export const ToolInvocationStatusInProgress = "in_progress";
 export const ToolInvocationStatusAwaitingInput = "awaiting_input";
@@ -1589,3 +1604,12 @@ export const ToolParamTypeArray = "array";
  * Tool parameter types
  */
 export const ToolParamTypeNull = "null";
+/**
+ * TurnUsageComplete is the whole turn, as the agent counted it.
+ */
+export const TurnUsageComplete = "complete";
+/**
+ * TurnUsagePartial is what was reported before the turn ended early
+ * (interrupted, failed).
+ */
+export const TurnUsagePartial = "partial";

package/dist/utils.d.ts

@@ -2,8 +2,8 @@
  * Status utilities for handling both int and string-based status values.
  * Provides future compatibility when API migrates from int to string status.
  */
-import { TaskStatus } from './types';
-import type { AgentRunState, ChatDTO, ChatMessageStatus } from './types';
+import { TaskStatus } from './types.js';
+import type { AgentRunState, ChatDTO, ChatMessageStatus } from './types.js';
 /**
  * Parse task status from int or string to TaskStatus number.
  * Handles both current int-based API and future string-based API.

package/dist/utils.js

@@ -2,8 +2,8 @@
  * Status utilities for handling both int and string-based status values.
  * Provides future compatibility when API migrates from int to string status.
  */
-import { InterruptReasonToolApproval, InterruptStatusPending } from './types';
-import { TaskStatusUnknown, TaskStatusReceived, TaskStatusQueued, TaskStatusDispatched, TaskStatusPreparing, TaskStatusServing, TaskStatusSettingUp, TaskStatusRunning, TaskStatusCancelling, TaskStatusUploading, TaskStatusCompleted, TaskStatusFailed, TaskStatusCancelled, AgentRunStateWorking, AgentRunStateSubmitted, AgentRunStateInputRequired, AgentRunStateAuthRequired, AgentRunStateCompleted, AgentRunStateFailed, AgentRunStateCanceled, AgentRunStateRejected, ChatMessageStatusReady, ChatMessageStatusFailed, ChatMessageStatusCancelled, ChatStatusBusy, ChatStatusAwaitingInput, } from './types';
+import { InterruptReasonToolApproval, InterruptStatusPending } from './types.js';
+import { TaskStatusUnknown, TaskStatusReceived, TaskStatusQueued, TaskStatusDispatched, TaskStatusPreparing, TaskStatusServing, TaskStatusSettingUp, TaskStatusRunning, TaskStatusCancelling, TaskStatusUploading, TaskStatusCompleted, TaskStatusFailed, TaskStatusCancelled, AgentRunStateWorking, AgentRunStateSubmitted, AgentRunStateInputRequired, AgentRunStateAuthRequired, AgentRunStateCompleted, AgentRunStateFailed, AgentRunStateCanceled, AgentRunStateRejected, ChatMessageStatusReady, ChatMessageStatusFailed, ChatMessageStatusCancelled, ChatStatusBusy, ChatStatusAwaitingInput, } from './types.js';
 /** Map string status names to TaskStatus values (for future string-based API) */
 const STATUS_STRING_MAP = {
     unknown: TaskStatusUnknown,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/sdk",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Official JavaScript/TypeScript SDK for inference.sh - Run AI models with a simple API",
   "type": "module",
   "main": "dist/index.js",
@@ -144,6 +144,7 @@
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
     "clean": "rimraf dist coverage",
+    "check:exports": "node scripts/check-exports.mjs",
     "example": "node examples/basic.js"
   }
 }