@inferencesh/sdk 0.4.27 → 0.5.2

package/README.md

@@ -1,11 +1,13 @@
-# @inferencesh/sdk
+# @inferencesh/sdk — ai inference api for javascript & typescript
 
 [![npm version](https://img.shields.io/npm/v/@inferencesh/sdk.svg)](https://www.npmjs.com/package/@inferencesh/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@inferencesh/sdk.svg)](https://www.npmjs.com/package/@inferencesh/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-Official JavaScript/TypeScript SDK for [inference.sh](https://inference.sh) — Run AI models with a simple API.
+official javascript/typescript sdk for [inference.sh](https://inference.sh) — the ai agent runtime for serverless ai inference.
+
+run ai models, build ai agents, and deploy generative ai applications with a simple api. access 150+ models including flux, stable diffusion, llms (claude, gpt, gemini), video generation (veo, seedance), and more.
 
 ## Installation
 
@@ -149,6 +151,53 @@ const task = await client.tasks.run(
 await client.tasks.cancel(task.id);
 ```
 
+### Sessions (Stateful Execution)
+
+Sessions allow you to maintain state across multiple task invocations. The worker stays warm between calls, preserving loaded models and in-memory state.
+
+```typescript
+// Start a new session
+const result = await client.tasks.run({
+  app: 'my-stateful-app',
+  input: { prompt: 'hello' },
+  session: 'new'
+});
+
+const sessionId = result.session_id;
+console.log('Session ID:', sessionId);
+
+// Continue the session with another call
+const result2 = await client.tasks.run({
+  app: 'my-stateful-app',
+  input: { prompt: 'remember what I said?' },
+  session: sessionId
+});
+```
+
+#### Custom Session Timeout
+
+By default, sessions expire after 60 seconds of inactivity. You can customize this with `session_timeout` (1-3600 seconds):
+
+```typescript
+// Create a session with 5-minute idle timeout
+const result = await client.tasks.run({
+  app: 'my-stateful-app',
+  input: { prompt: 'hello' },
+  session: 'new',
+  session_timeout: 300  // 5 minutes
+});
+
+// Session stays alive for 5 minutes after each call
+```
+
+**Notes:**
+- `session_timeout` is only valid when `session: 'new'`
+- Minimum timeout: 1 second
+- Maximum timeout: 3600 seconds (1 hour)
+- Each successful call resets the idle timer
+
+For complete session documentation including error handling, best practices, and advanced patterns, see the [Sessions Developer Guide](https://inference.sh/docs/extend/sessions).
+
 ## Agent Chat
 
 Chat with AI agents using `client.agents.create()`.
@@ -252,6 +301,8 @@ Runs a task on inference.sh.
 | `params.setup` | `object` | No | Setup parameters (affects worker warmth/scheduling) |
 | `params.infra` | `string` | No | Infrastructure: `'cloud'` or `'private'` |
 | `params.variant` | `string` | No | App variant to use |
+| `params.session` | `string` | No | Session ID or `'new'` to start a new session |
+| `params.session_timeout` | `number` | No | Session timeout in seconds (1-3600, only with `session: 'new'`) |
 
 **Options:**
 
@@ -331,6 +382,14 @@ import type { Task, ApiTaskRequest, RunOptions } from '@inferencesh/sdk';
 - Node.js 18.0.0 or higher
 - Modern browsers with `fetch` support
 
-## License
+## resources
+
+- [documentation](https://inference.sh/docs) — getting started guides and api reference
+- [blog](https://inference.sh/blog) — tutorials on ai agents, image generation, and more
+- [app store](https://app.inference.sh) — browse 150+ ai models
+- [discord](https://discord.gg/RM77SWSbyT) — community support
+- [github](https://github.com/inference-sh) — open source projects
+
+## license
 
 MIT © [inference.sh](https://inference.sh)

package/dist/agent/api.js

@@ -24,6 +24,7 @@ export async function sendAdHocMessage(client, config, chatId, text, imageUris,
             system_prompt: config.system_prompt ?? '',
             tools: toolSchemas
         },
+        agent_name: config.name,
         input: {
             text,
             images: imageUris,

package/dist/api/agents.js

@@ -56,7 +56,7 @@ export class Agent {
             : {
                 chat_id: this.chatId,
                 agent_config: this.config,
-                agent_name: this.agentName,
+                agent_name: this.agentName ?? this.config.name,
                 input: { text, images: imageUris, files: fileUris, role: 'user', context: [], system_prompt: '', context_size: 0 },
             };
         // For existing chats with callbacks: Start streaming BEFORE POST so we don't miss updates

package/dist/api/apps.d.ts

@@ -1,14 +1,5 @@
 import { HttpClient } from '../http/client';
-import { AppDTO as App, AppVersionDTO, CursorListRequest, CursorListResponse } from '../types';
-interface LicenseRecord {
-    id: string;
-    created_at: string;
-    updated_at: string;
-    deleted_at?: string;
-    user_id: string;
-    app_id: string;
-    license: string;
-}
+import { AppDTO as App, AppVersionDTO, CursorListRequest, CursorListResponse, LicenseRecord } from '../types';
 /**
  * Apps API
  */
@@ -69,4 +60,3 @@ export declare class AppsAPI {
     saveLicense(appId: string, license: string): Promise<LicenseRecord>;
 }
 export declare function createAppsAPI(http: HttpClient): AppsAPI;
-export {};

package/dist/sessions.integration.test.js

@@ -39,7 +39,6 @@ describeIfApiKey('Sessions Integration Tests', () => {
             expect(result.status).toBe(TaskStatusCompleted);
             expect(result.session_id).toBeDefined();
             expect(result.session_id).not.toBe('new');
-            expect(result.session_id).toMatch(/^sess_/);
         }, 60000);
         it('should return correct output data', async () => {
             const result = await client.run({
@@ -69,7 +68,6 @@ describeIfApiKey('Sessions Integration Tests', () => {
             });
             expect(result1.status).toBe(TaskStatusCompleted);
             const sessionId = result1.session_id;
-            expect(sessionId).toMatch(/^sess_/);
             // Retrieve value from same session
             const result2 = await client.run({
                 app: SESSION_TEST_APP,

package/dist/types.d.ts

@@ -170,7 +170,7 @@ export interface ClientToolConfigDTO {
  */
 export interface CoreAppConfig {
     id?: string;
-    version?: string;
+    version_id?: string;
     /**
      * CoreAppRef is the user-facing ref (namespace/name@shortid) - used in ad-hoc configs, resolved at creation
      */
@@ -192,9 +192,7 @@ export interface AgentImages {
     thumbnail: string;
     banner: string;
 }
-export interface Agent {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Agent extends BaseModel, PermissionModel {
     ProjectModel: ProjectModel;
     /**
      * Basic info
@@ -237,6 +235,11 @@ export interface SkillConfig {
  * Using Go embedding flattens these fields in JSON serialization.
  */
 export interface AgentConfig {
+    /**
+     * Optional name for the agent (used for adhoc agent deduplication — reuses existing agent by name).
+     * Not persisted as a DB column; only used in API requests.
+     */
+    name?: string;
     description?: string;
     system_prompt?: string;
     example_prompts?: string[];
@@ -261,14 +264,8 @@ export interface AgentConfig {
      */
     output_schema?: any;
 }
-export interface AgentVersion {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface AgentVersion extends BaseModel, PermissionModel {
     agent_id: string;
-    /**
-     * Short ID for human-readable version references (e.g., "abc123")
-     */
-    short_id: string;
     /**
      * ConfigHash for deduplication - SHA256 of config content
      */
@@ -276,7 +273,7 @@ export interface AgentVersion {
 }
 export interface CoreAppConfigDTO {
     id?: string;
-    version?: string;
+    version_id?: string;
     ref?: string;
     app?: AppDTO;
     /**
@@ -338,7 +335,7 @@ export interface ApiAppRunRequest {
      */
     app?: string;
     /**
-     * Alternative: specify app by ID (for internal use)
+     * Deprecated: use App ref instead. Direct ID bypasses ref routing.
      */
     app_id?: string;
     version_id?: string;
@@ -360,6 +357,10 @@ export interface ApiAppRunRequest {
      * When using sessions, the worker is leased and state persists across calls
      */
     session?: string;
+    /**
+     * Session timeout in seconds (1-3600). Only valid when session="new"
+     */
+    session_timeout?: number;
 }
 /**
  * ApiAgentRunRequest is the request body for /agents/run endpoint.
@@ -710,9 +711,7 @@ export interface AppImages {
     thumbnail: string;
     banner: string;
 }
-export interface App {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface App extends BaseModel, PermissionModel {
     /**
      * Namespace is copied from team.username at creation time and is IMMUTABLE.
      * This ensures stable references like "namespace/name" even if team username changes.
@@ -767,13 +766,7 @@ export interface AppFunction {
     input_schema: any;
     output_schema: any;
 }
-export interface AppVersion {
-    BaseModel: BaseModel;
-    /**
-     * ShortID is a human-friendly version identifier (e.g., "abc123")
-     * Unique within the app, used in references like "namespace/app@abc123"
-     */
-    short_id: string;
+export interface AppVersion extends BaseModel {
     app_id: string;
     metadata: {
         [key: string]: any;
@@ -811,6 +804,11 @@ export interface AppVersion {
      */
     checksum?: string;
 }
+export interface LicenseRecord extends BaseModel {
+    user_id: string;
+    app_id: string;
+    license: string;
+}
 export interface AppDTO extends BaseModel, PermissionModelDTO {
     namespace: string;
     name: string;
@@ -822,7 +820,6 @@ export interface AppDTO extends BaseModel, PermissionModelDTO {
     version?: AppVersionDTO;
 }
 export interface AppVersionDTO extends BaseModel {
-    short_id: string;
     metadata: {
         [key: string]: any;
     };
@@ -858,9 +855,7 @@ export type AppSessionStatus = string;
 export declare const AppSessionStatusActive: AppSessionStatus;
 export declare const AppSessionStatusEnded: AppSessionStatus;
 export declare const AppSessionStatusExpired: AppSessionStatus;
-export interface AppSession {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface AppSession extends BaseModel, PermissionModel {
     /**
      * Affinity binding
      */
@@ -882,6 +877,10 @@ export interface AppSession {
      */
     call_count: number;
     last_call_at?: string;
+    /**
+     * Custom idle timeout in seconds (nil = use default)
+     */
+    idle_timeout?: number;
     /**
      * Relations
      */
@@ -890,6 +889,7 @@ export interface AppSession {
 }
 export interface BaseModel {
     id: string;
+    short_id: string;
     created_at: string;
     updated_at: string;
     deleted_at?: string;
@@ -1150,9 +1150,7 @@ export declare const EngineStatusRunning: EngineStatus;
 export declare const EngineStatusPending: EngineStatus;
 export declare const EngineStatusStopping: EngineStatus;
 export declare const EngineStatusStopped: EngineStatus;
-export interface EngineState {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface EngineState extends BaseModel, PermissionModel {
     instance?: Instance;
     transaction_id: string;
     config: EngineConfig;
@@ -1182,9 +1180,7 @@ export interface EngineStateSummary extends BaseModel, PermissionModelDTO {
  * Worker-related types
  */
 export type WorkerStatus = string;
-export interface WorkerState {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface WorkerState extends BaseModel, PermissionModel {
     index: number;
     status: WorkerStatus;
     status_updated_at?: string;
@@ -1262,9 +1258,20 @@ export interface WorkerStateSummary {
     cpus: WorkerCPU[];
     rams: WorkerRAM[];
 }
-export interface File {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+/**
+ * FileMetadata holds probed media metadata cached on File records.
+ */
+export interface FileMetadata {
+    type?: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+    fps?: number;
+    sample_rate?: number;
+    channels?: number;
+    codec?: string;
+}
+export interface File extends BaseModel, PermissionModel {
     path: string;
     remote_path: string;
     upload_url: string;
@@ -1273,6 +1280,7 @@ export interface File {
     size: number;
     filename: string;
     rating: ContentRating;
+    metadata?: FileMetadata;
 }
 export interface FileDTO extends BaseModel, PermissionModelDTO {
     path: string;
@@ -1283,9 +1291,9 @@ export interface FileDTO extends BaseModel, PermissionModelDTO {
     size: number;
     filename: string;
     rating: ContentRating;
+    metadata?: FileMetadata;
 }
-export interface FlowVersion {
-    BaseModel: BaseModel;
+export interface FlowVersion extends BaseModel {
     /**
      * Permission fields - nullable for migration from existing data
      * After migration these will be populated from parent Flow
@@ -1295,10 +1303,6 @@ export interface FlowVersion {
     team_id: string;
     team?: Team;
     flow_id: string;
-    /**
-     * Short ID for human-readable version references (e.g., "abc123")
-     */
-    short_id: string;
     /**
      * ConfigHash for deduplication - SHA256 of config content
      */
@@ -1395,7 +1399,6 @@ export interface FlowDTO extends BaseModel, PermissionModelDTO {
     viewport?: FlowViewport;
 }
 export interface FlowVersionDTO extends BaseModel {
-    short_id: string;
     input_schema: any;
     input: FlowRunInputs;
     output_schema: any;
@@ -1564,9 +1567,7 @@ export interface ProjectModelDTO {
 /**
  * Project represents a container for organizing related resources
  */
-export interface Project {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Project extends BaseModel, PermissionModel {
     name: string;
     description: string;
     type: ProjectType;
@@ -1673,9 +1674,7 @@ export type InstanceStatus = string;
 export declare const InstanceStatusPending: InstanceStatus;
 export declare const InstanceStatusActive: InstanceStatus;
 export declare const InstanceStatusDeleted: InstanceStatus;
-export interface Instance {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Instance extends BaseModel, PermissionModel {
     cloud: InstanceCloudProvider;
     name: string;
     region: string;
@@ -1891,9 +1890,7 @@ export type Infra = string;
 export declare const InfraPrivate: Infra;
 export declare const InfraCloud: Infra;
 export declare const InfraPrivateFirst: Infra;
-export interface Task {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface Task extends BaseModel, PermissionModel {
     is_featured: boolean;
     status: TaskStatus;
     /**
@@ -1953,6 +1950,10 @@ export interface Task {
      */
     session_id?: string;
     session?: AppSession;
+    /**
+     * Session timeout in seconds (only used when session="new")
+     */
+    session_timeout?: number;
 }
 export interface TaskEvent {
     id: string;
@@ -2012,6 +2013,7 @@ export interface TaskDTO extends BaseModel, PermissionModelDTO {
     transaction_id?: string;
     transaction?: Transaction;
     session_id?: string;
+    session_timeout?: number;
 }
 export interface TimescaleTask {
     id: string;
@@ -2029,8 +2031,7 @@ export type TeamType = string;
 export declare const TeamTypePersonal: TeamType;
 export declare const TeamTypeTeam: TeamType;
 export declare const TeamTypeSystem: TeamType;
-export interface Team {
-    BaseModel: BaseModel;
+export interface Team extends BaseModel {
     type: TeamType;
     username: string;
     email: string;
@@ -2137,8 +2138,7 @@ export declare const TransactionTypeDebit: TransactionType;
 /**
  * Transaction represents a single credit transaction
  */
-export interface Transaction {
-    BaseModel: BaseModel;
+export interface Transaction extends BaseModel {
     PermissionModel: PermissionModel;
     type: TransactionType;
     amount: number;
@@ -2150,6 +2150,12 @@ export interface Transaction {
     metadata: {
         [key: string]: any;
     };
+    /**
+     * SideEffectsProcessed tracks whether side effects (notifications, auto-recharge,
+     * billing status changes) have been processed for this transaction.
+     * Set to true via WithSkipTxSideEffects context to skip side effects (e.g. migrations).
+     */
+    side_effects_processed: boolean;
 }
 /**
  * PaymentRecordStatus represents the status of a payment
@@ -2168,12 +2174,11 @@ export declare const PaymentRecordTypeAutoRecharge: PaymentRecordType;
 /**
  * PaymentRecord stores Stripe payment details for both checkout sessions and direct charges
  */
-export interface PaymentRecord {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface PaymentRecord extends BaseModel, PermissionModel {
     type: PaymentRecordType;
     status: PaymentRecordStatus;
     amount: number;
+    service_fee: number;
     stripe_customer_id: string;
     payment_intent_id: string;
     receipt_url: string;
@@ -2248,9 +2253,7 @@ export interface OutputMeta {
     inputs: MetaItem[];
     outputs: MetaItem[];
 }
-export interface UsageEvent {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface UsageEvent extends BaseModel, PermissionModel {
     usage_billing_record_id: string;
     reference_id: string;
     resource_id: string;
@@ -2263,9 +2266,14 @@ export interface UsageEvent {
     quantity: number;
     unit: string;
 }
-export interface UsageBillingRecord {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+/**
+ * DiscountItem represents a single discount applied to a billing record
+ */
+export interface DiscountItem {
+    reason: string;
+    amount: number;
+}
+export interface UsageBillingRecord extends BaseModel, PermissionModel {
     /**
      * Fee breakdown (all in microcents)
      */
@@ -2297,9 +2305,7 @@ export interface UsageBillingRecord {
     partner_credit_transaction_id: string;
     partner_credit_transaction?: Transaction;
 }
-export interface UsageBillingRefund {
-    BaseModel: BaseModel;
-    PermissionModel: PermissionModel;
+export interface UsageBillingRefund extends BaseModel, PermissionModel {
     usage_billing_record_id: string;
     usage_billing_record?: UsageBillingRecord;
     /**

package/package.json

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