@inferencesh/sdk 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.2] - 2026-10-01
+
+### Added
+
+- Instance types: `InstanceRentalType` (`on_demand`, `spot`), `rental_type` on availability and engine-picker offers, `hourly_price` on spot entries.
+- `lifecycleHook(event).builtin(name)` for hooks the platform runs itself.
+- `learningHooks({ suggest, learn })`: `suggest` adds the team's matching skills, knowledge and apps to context before each turn (`belt:suggest`); `learn` saves reusable knowledge from the conversation to the team's registry every 10th user turn and before compaction (`belt:extract`). Both are off unless set.
+- `BuiltinHookBeltExtract`.
+
+## [0.14.1] - 2026-10-01
+
+### Added
+
+- `internalTools()` builder methods for every category: `knowledge()` (search, read, save and delete skills and knowledge entries), `agent()` (run a copy of the agent on a side task), `skills()`, `artifact()` and `remote()`.
+- `InternalToolsConfig.knowledge` and `InternalToolsConfig.agent`.
+
+### Changed
+
+- `InternalToolsConfig.spawn` is now `agent`. The API still reads a stored or sent `spawn` as `agent`.
+
+### Deprecated
+
+- `InternalToolsConfig.host_context`: the API ignores it and no longer offers `get_host_context` or `send_to_host`.
+
 ## [0.14.0] - 2026-09-27
 
 ### Fixed

package/README.md

@@ -378,7 +378,7 @@ Use the fluent builders to define `AgentTool` schemas. Client tools (`tool`) run
 | `httpTool(name, url)` / `callTool(name, url)` | Server | HTTP request with credential injection (preferred over `webhookTool`) |
 | `webhookTool(name, url)` | Server | Unsigned webhook (legacy; use `httpTool` for new tools) |
 | `mcpTool(name, credentialId, toolName)` | Server | Call a tool through a connected MCP credential |
-| `internalTools()` | Server | Built-in plan, memory, and widget tools |
+| `internalTools()` | Server | Built-in tools: plan, memory, widget, finish, skills, meta, remote, knowledge, artifact, agent |
 
 ```typescript
 import {

package/dist/hook-builder.d.ts

@@ -1,7 +1,7 @@
 /**
  * Hook Builder - Fluent API for defining lifecycle hooks
  */
-import { LifecycleHookConfig, HookEvent } from './types';
+import { LifecycleHookConfig, HookEvent, BuiltinHook } from './types';
 export declare class LifecycleHookBuilder {
     private event;
     private handlerType;
@@ -13,6 +13,8 @@ export declare class LifecycleHookBuilder {
     webhook(url: string): this;
     /** Set handler to a task (agent ref) */
     task(agentRef: string): this;
+    /** Set handler to a builtin the platform runs itself (e.g. belt:suggest) */
+    builtin(name: BuiltinHook): this;
     /** Set async execution */
     async(enabled: boolean): this;
     /** Set handler timeout in seconds */
@@ -21,3 +23,14 @@ export declare class LifecycleHookBuilder {
 }
 /** Create a lifecycle hook for an agent event */
 export declare const lifecycleHook: (event: HookEvent) => LifecycleHookBuilder;
+/**
+ * The built-in learning hooks, attached to the events each one runs on.
+ * - `suggest`: before each turn, add the team's matching skills, knowledge and apps to context.
+ * - `learn`: every 10th user turn and before compaction, save reusable knowledge from the
+ *   conversation to the team's registry, deduplicated. Runs on the agent's own model, and only
+ *   for chats by the agent's owning team.
+ */
+export declare function learningHooks(opts: {
+    suggest?: boolean;
+    learn?: boolean;
+}): LifecycleHookConfig[];

package/dist/hook-builder.js

@@ -1,7 +1,7 @@
 /**
  * Hook Builder - Fluent API for defining lifecycle hooks
  */
-import { HookHandlerWebhook, HookHandlerTask } from './types';
+import { HookHandlerWebhook, HookHandlerTask, HookHandlerBuiltin, BuiltinHookBeltSuggest, BuiltinHookBeltExtract, HookEventTurnStart, HookEventAgentComplete, HookEventPreCompact, } from './types';
 // =============================================================================
 // Hook Builder
 // =============================================================================
@@ -23,6 +23,12 @@ export class LifecycleHookBuilder {
         this.handlerRef = agentRef;
         return this;
     }
+    /** Set handler to a builtin the platform runs itself (e.g. belt:suggest) */
+    builtin(name) {
+        this.handlerType = HookHandlerBuiltin;
+        this.handlerRef = name;
+        return this;
+    }
     /** Set async execution */
     async(enabled) {
         this.isAsync = enabled;
@@ -48,3 +54,22 @@ export class LifecycleHookBuilder {
 // =============================================================================
 /** Create a lifecycle hook for an agent event */
 export const lifecycleHook = (event) => new LifecycleHookBuilder(event);
+/**
+ * The built-in learning hooks, attached to the events each one runs on.
+ * - `suggest`: before each turn, add the team's matching skills, knowledge and apps to context.
+ * - `learn`: every 10th user turn and before compaction, save reusable knowledge from the
+ *   conversation to the team's registry, deduplicated. Runs on the agent's own model, and only
+ *   for chats by the agent's owning team.
+ */
+export function learningHooks(opts) {
+    const hooks = [];
+    if (opts.suggest) {
+        hooks.push(lifecycleHook(HookEventTurnStart).builtin(BuiltinHookBeltSuggest).build());
+    }
+    if (opts.learn) {
+        for (const event of [HookEventAgentComplete, HookEventPreCompact]) {
+            hooks.push(lifecycleHook(event).builtin(BuiltinHookBeltExtract).build());
+        }
+    }
+    return hooks;
+}

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveFiel
 export type { JsonSchema, MediaType, PCMFormat, LiveField } from './live/schema';
 export { tool, appTool, agentTool, webhookTool, httpTool, callTool, mcpTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional, } from './tool-builder';
 export type { ClientTool, ClientToolHandler } from './tool-builder';
-export { lifecycleHook } from './hook-builder';
+export { lifecycleHook, learningHooks } from './hook-builder';
 export type { LifecycleHookBuilder } from './hook-builder';
 export { DeltaAccumulator, createLLMDeltaAccumulator, type DeltaEvent, type FieldTags, type FieldTagsRegistry } from './delta';
 export { parseStatus, isTerminalStatus, isChatBusy, isAwaitingHuman, isRunTerminal, isRunInterrupted, isRunSettled, isRunWorking, isMessageTerminal, pendingApprovals, } from './utils';

package/dist/index.js

@@ -33,7 +33,7 @@ export { isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveFiel
 // Tool Builder (fluent API)
 export { tool, appTool, agentTool, webhookTool, httpTool, callTool, mcpTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional, } from './tool-builder';
 // Hook Builder (fluent API)
-export { lifecycleHook } from './hook-builder';
+export { lifecycleHook, learningHooks } from './hook-builder';
 // Delta accumulator for streaming responses
 export { DeltaAccumulator, createLLMDeltaAccumulator } from './delta';
 // Status utilities (handle both int and string status values)

package/dist/tool-builder.d.ts

@@ -136,6 +136,14 @@ declare class InternalToolsBuilder {
     meta(enabled?: boolean): this;
     /** Enable remote tools (run commands on the user's connected remotes) */
     remote(enabled?: boolean): this;
+    /** Enable knowledge tools (search, read and save the user's skills and knowledge entries) */
+    knowledge(enabled?: boolean): this;
+    /** Enable skill_get for the skills configured on the agent (on by default) */
+    skills(enabled?: boolean): this;
+    /** Enable artifact tools (publish shareable HTML/Markdown pages) */
+    artifact(enabled?: boolean): this;
+    /** Enable the agent tool (run a copy of this agent on a side task) */
+    agent(enabled?: boolean): this;
     /** Enable all internal tools */
     all(): this;
     /** Disable all internal tools */

package/dist/tool-builder.js

@@ -293,6 +293,26 @@ class InternalToolsBuilder {
         this.config.remote = enabled;
         return this;
     }
+    /** Enable knowledge tools (search, read and save the user's skills and knowledge entries) */
+    knowledge(enabled = true) {
+        this.config.knowledge = enabled;
+        return this;
+    }
+    /** Enable skill_get for the skills configured on the agent (on by default) */
+    skills(enabled = true) {
+        this.config.skills = enabled;
+        return this;
+    }
+    /** Enable artifact tools (publish shareable HTML/Markdown pages) */
+    artifact(enabled = true) {
+        this.config.artifact = enabled;
+        return this;
+    }
+    /** Enable the agent tool (run a copy of this agent on a side task) */
+    agent(enabled = true) {
+        this.config.agent = enabled;
+        return this;
+    }
     /** Enable all internal tools */
     all() {
         this.config.plan = true;

package/dist/types.d.ts

@@ -7,11 +7,16 @@ export interface InternalToolsConfig {
     widget?: boolean;
     finish?: boolean;
     skills?: boolean;
+    /**
+     * Deprecated: ignored. Host context is disabled until embed context has a
+     * replacement; agents are never offered get_host_context or send_to_host.
+     */
     host_context?: boolean;
     meta?: boolean;
     artifact?: boolean;
-    spawn?: boolean;
+    agent?: boolean;
     remote?: boolean;
+    knowledge?: boolean;
 }
 /**
  * AgentTool represents a unified tool that can be used by an agent
@@ -84,6 +89,13 @@ export interface AppToolConfig {
     session_enabled?: boolean;
     setup?: any;
     input?: any;
+    /**
+     * FixedInput pins arguments: they are merged over whatever the model sent,
+     * and removed from the tool schema the model is shown, so it neither sees
+     * nor controls them. Input only supplies defaults the model may override;
+     * this is for values an operator decides, not the model.
+     */
+    fixed_input?: any;
 }
 export interface AgentToolConfig {
     ref: string;
@@ -153,6 +165,7 @@ export interface AppToolConfigDTO {
     session_enabled?: boolean;
     setup?: any;
     input?: any;
+    fixed_input?: any;
 }
 export interface AgentToolConfigDTO {
     ref: string;
@@ -2489,6 +2502,7 @@ export interface InstanceDTO extends BaseModelDTO, PermissionModelDTO {
     status: InstanceStatus;
     cost_estimate: string;
     hourly_price: number;
+    rental_type?: InstanceRentalType;
     template_id?: string;
     volume_ids?: string[];
     tags?: string[];
@@ -2510,6 +2524,11 @@ export interface InstanceTypeDTO extends BaseModelDTO, PermissionModelDTO {
     cloud_instance_type: string;
     deployment_type: InstanceTypeDeploymentType;
     hourly_price: number;
+    /**
+     * RentalType is set on engine-picker offers: Region and HourlyPrice are
+     * for this rental type. Empty on the raw catalog.
+     */
+    rental_type?: InstanceRentalType;
     configuration?: InstanceTypeConfiguration;
     availability: InstanceTypeAvailability[];
     boot_time?: InstanceTypeBootTime;
@@ -2529,6 +2548,11 @@ export interface InstanceTypeConfiguration {
 export interface InstanceTypeAvailability {
     available: boolean;
     region: string;
+    rental_type?: InstanceRentalType;
+    /**
+     * HourlyPrice is the spot price in cents, set on spot entries only.
+     */
+    hourly_price?: number;
 }
 export interface InstanceTypeBootTime {
     average_seconds: number;
@@ -2960,10 +2984,6 @@ export interface OrgDTO extends BaseModelDTO {
     name: string;
     avatar_url?: string;
     default_team_id?: string;
-    /**
-     * UsagePolicyID of the org's usage policy ('' = ungoverned, INF-808).
-     */
-    usage_policy_id?: string;
     /**
      * IsAdmin: whether the CALLER is on this org's admin grant list. Set on
      * caller-scoped responses.
@@ -4268,7 +4288,7 @@ export declare const PlanStepStatusPending: PlanStepStatus;
 export declare const PlanStepStatusInProgress: PlanStepStatus;
 export declare const PlanStepStatusCompleted: PlanStepStatus;
 export declare const PlanStepStatusCancelled: PlanStepStatus;
-export type ChatMessageRole = "system" | "user" | "assistant" | "tool" | "injection" | "compaction";
+export type ChatMessageRole = "system" | "user" | "assistant" | "tool" | "injection" | "compaction" | "event";
 /**
  * LLM wire-protocol roles
  */
@@ -4279,22 +4299,25 @@ export declare const ChatMessageRoleTool: ChatMessageRole;
 /**
  * Internal bookkeeping roles — never sent to the LLM provider.
  * BuildContext folds injections into the user turn and replaces
- * compaction markers with their summary.
+ * compaction markers with their summary. Event messages are display-only
+ * system info (a hook ran, ...) and BuildContext skips them.
  */
 export declare const ChatMessageRoleInjection: ChatMessageRole;
 export declare const ChatMessageRoleCompaction: ChatMessageRole;
+export declare const ChatMessageRoleEvent: ChatMessageRole;
 export type ChatMessageStatus = "pending" | "queued" | "ready" | "failed" | "cancelled";
 export declare const ChatMessageStatusPending: ChatMessageStatus;
 export declare const ChatMessageStatusQueued: ChatMessageStatus;
 export declare const ChatMessageStatusReady: ChatMessageStatus;
 export declare const ChatMessageStatusFailed: ChatMessageStatus;
 export declare const ChatMessageStatusCancelled: ChatMessageStatus;
-export type ChatMessageContentType = "text" | "reasoning" | "image" | "file" | "tool";
+export type ChatMessageContentType = "text" | "reasoning" | "image" | "file" | "tool" | "event";
 export declare const ChatMessageContentTypeText: ChatMessageContentType;
 export declare const ChatMessageContentTypeReasoning: ChatMessageContentType;
 export declare const ChatMessageContentTypeImage: ChatMessageContentType;
 export declare const ChatMessageContentTypeFile: ChatMessageContentType;
 export declare const ChatMessageContentTypeTool: ChatMessageContentType;
+export declare const ChatMessageContentTypeEvent: ChatMessageContentType;
 export type ChannelType = "slack" | "discord" | "teams" | "telegram";
 export declare const ChannelTypeSlack: ChannelType;
 export declare const ChannelTypeDiscord: ChannelType;
@@ -4328,6 +4351,34 @@ export interface ChatMessageContent {
     image?: string;
     file?: string;
     tool_calls?: ToolCall[];
+    event?: ChatEvent;
+}
+export type ChatEventType = "hook";
+export declare const ChatEventTypeHook: ChatEventType;
+/**
+ * ChatEvent is the payload of an event-role message: system info shown in the
+ * chat but never sent to the model.
+ */
+export interface ChatEvent {
+    type: ChatEventType;
+    hook?: ChatHookEvent;
+}
+/**
+ * ChatHookEvent records one lifecycle hook handler run.
+ */
+export interface ChatHookEvent {
+    event: HookEvent;
+    handler_type: HookHandlerType;
+    /**
+     * Handler names what ran: the builtin or agent ref, or a webhook's host
+     * (never its full URL, which can carry credentials).
+     */
+    handler: string;
+    decision?: HookDecision;
+    reason?: string;
+    injected?: boolean;
+    error?: string;
+    duration_ms: number;
 }
 /**
  * ChannelContext records which channel a chat or message came through
@@ -4749,6 +4800,13 @@ export type InstanceTypeDeploymentType = "vm" | "container" | "baremetal";
 export declare const InstanceTypeDeploymentTypeVM: InstanceTypeDeploymentType;
 export declare const InstanceTypeDeploymentTypeContainer: InstanceTypeDeploymentType;
 export declare const InstanceTypeDeploymentTypeBaremetal: InstanceTypeDeploymentType;
+/**
+ * InstanceRentalType is how a Shadeform instance is rented. Spot is discounted
+ * but can be reclaimed at any time.
+ */
+export type InstanceRentalType = "on_demand" | "spot";
+export declare const InstanceRentalTypeOnDemand: InstanceRentalType;
+export declare const InstanceRentalTypeSpot: InstanceRentalType;
 export type AppSessionStatus = "active" | "ended" | "expired";
 export declare const AppSessionStatusActive: AppSessionStatus;
 export declare const AppSessionStatusEnded: AppSessionStatus;
@@ -5543,8 +5601,21 @@ export declare const HookHandlerBuiltin: HookHandlerType;
  * agent config is validated against it, and clients enumerate it to show what
  * an agent can switch on without hosting anything.
  */
-export type BuiltinHook = "belt:suggest";
+export type BuiltinHook = "belt:suggest" | "belt:extract";
+/**
+ * BuiltinHookBeltSuggest searches the team's skills, knowledge and apps
+ * for what the turn is about and injects the matches, so an agent picks up
+ * procedural knowledge it was never prompted with.
+ */
 export declare const BuiltinHookBeltSuggest: BuiltinHook;
+/**
+ * BuiltinHookBeltExtract reviews the conversation for reusable knowledge
+ * and saves it to the team's registry, deduplicated against what is
+ * there, so belt:suggest can hand it back later. It runs in the
+ * background: on agent.complete every tenth user turn, and before
+ * compaction drops the turns it would have learned from.
+ */
+export declare const BuiltinHookBeltExtract: BuiltinHook;
 /**
  * BuiltinHookDefinition describes a builtin hook and where it may be used.
  */

package/dist/types.js

@@ -575,10 +575,12 @@ export const ChatMessageRoleTool = "tool";
 /**
  * Internal bookkeeping roles — never sent to the LLM provider.
  * BuildContext folds injections into the user turn and replaces
- * compaction markers with their summary.
+ * compaction markers with their summary. Event messages are display-only
+ * system info (a hook ran, ...) and BuildContext skips them.
  */
 export const ChatMessageRoleInjection = "injection";
 export const ChatMessageRoleCompaction = "compaction";
+export const ChatMessageRoleEvent = "event";
 export const ChatMessageStatusPending = "pending";
 export const ChatMessageStatusQueued = "queued";
 export const ChatMessageStatusReady = "ready";
@@ -589,10 +591,12 @@ export const ChatMessageContentTypeReasoning = "reasoning";
 export const ChatMessageContentTypeImage = "image";
 export const ChatMessageContentTypeFile = "file";
 export const ChatMessageContentTypeTool = "tool";
+export const ChatMessageContentTypeEvent = "event";
 export const ChannelTypeSlack = "slack";
 export const ChannelTypeDiscord = "discord";
 export const ChannelTypeTeams = "teams";
 export const ChannelTypeTelegram = "telegram";
+export const ChatEventTypeHook = "hook";
 export const EngineStatusRunning = "running";
 export const EngineStatusPending = "pending";
 export const EngineStatusDraining = "draining";
@@ -730,6 +734,8 @@ export const InstanceStatusDeleted = "deleted";
 export const InstanceTypeDeploymentTypeVM = "vm";
 export const InstanceTypeDeploymentTypeContainer = "container";
 export const InstanceTypeDeploymentTypeBaremetal = "baremetal";
+export const InstanceRentalTypeOnDemand = "on_demand";
+export const InstanceRentalTypeSpot = "spot";
 export const AppSessionStatusActive = "active";
 export const AppSessionStatusEnded = "ended";
 export const AppSessionStatusExpired = "expired";
@@ -1197,7 +1203,20 @@ export const HookHandlerWebhook = "webhook";
 export const HookHandlerTask = "task";
 export const HookHandlerGate = "gate";
 export const HookHandlerBuiltin = "builtin";
+/**
+ * BuiltinHookBeltSuggest searches the team's skills, knowledge and apps
+ * for what the turn is about and injects the matches, so an agent picks up
+ * procedural knowledge it was never prompted with.
+ */
 export const BuiltinHookBeltSuggest = "belt:suggest";
+/**
+ * BuiltinHookBeltExtract reviews the conversation for reusable knowledge
+ * and saves it to the team's registry, deduplicated against what is
+ * there, so belt:suggest can hand it back later. It runs in the
+ * background: on agent.complete every tenth user turn, and before
+ * compaction drops the turns it would have learned from.
+ */
+export const BuiltinHookBeltExtract = "belt:extract";
 export const ToolInvocationStatusPending = "pending";
 export const ToolInvocationStatusInProgress = "in_progress";
 export const ToolInvocationStatusAwaitingInput = "awaiting_input";

package/package.json

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