@shardflux/sdk 0.9.0 → 0.10.0

package/dist/generated/cell-api.d.ts

@@ -723,9 +723,22 @@ export interface paths {
          *     none is known; in the future while a keepalive or a running command is
          *     active). A running exec command counts as work until min(its start +
          *     `IDLE_COMMAND_MAX_SECONDS`, its start + `timeout_ms`), and its end is
-         *     activity (contracts §20.6). `suspend_at` = `idle_since` + `idle_minutes` when
+         *     activity (contracts §20.6): an end seen without a client call is
+         *     recorded in `last_attach_at`, which is work but not a tool call.
+         *     `suspend_at` = `idle_since` + `idle_minutes` when
          *     the policy is `suspend_after` and automatic suspend is enabled, else
          *     null; the idle loop acts within `2 x ACTIVITY_FLUSH_MS` after it.
+         *     `suspend_request` is the pending suspend request of the application
+         *     API's `POST /v1/workspaces/{id}/suspend-when-idle` while it is valid:
+         *     the workspace is running, `last_tool_at` is not later than
+         *     `requested_at` + 0.5 s and `running_since` not later than
+         *     `requested_at` (a tool call or a resume after the request cancels it
+         *     for good), else null. A valid request applies under every policy
+         *     (`never` included) unless automatic suspend was disabled after
+         *     repeated failures; `suspend_at` is then the earlier of the policy's
+         *     time and max(`idle_since`, `requested_at`) + `after_seconds`, so an
+         *     attached stream, a keepalive or a running command defers it until
+         *     `after_seconds` after it ends (contracts §20.6).
          *     Activity lags tool traffic by up to `ACTIVITY_FLUSH_MS`. Any
          *     tool granted by the token authorizes the call; the tool gate does not
          *     apply and the call is not tool activity.
@@ -827,6 +840,7 @@ export interface components {
             env?: {
                 [key: string]: string;
             };
+            /** @description Absolute working directory; omitted or empty starts in the default (/home/user). A relative path is refused, not resolved: 422 validation_failed, details.reason invalid_cwd, details.field cwd, the message naming the absolute path it likely means. A cwd that is not a directory ends the session failed_to_start (processful) or the execution failed with details.reason exec_failed_to_start (file-first). */
             cwd?: string;
             user?: string;
             /** @description Written to stdin, which is then closed (max 1 MiB decoded). */
@@ -939,6 +953,7 @@ export interface components {
             started_at?: string | null;
             /** Format: date-time */
             ended_at?: string | null;
+            /** @description Why the session ended without an exit code. For failed_to_start the command never ran and this names the cause, e.g. `working directory "/home/user/app" is not a directory` or `executable "foo" not found in PATH`. */
             error?: string;
         };
         OutputEvent: {
@@ -982,6 +997,7 @@ export interface components {
             env?: {
                 [key: string]: string;
             };
+            /** @description Absolute working directory; omitted or empty starts in the default (/home/user). A relative path is refused: 422 validation_failed, details.reason invalid_cwd, details.field cwd. */
             cwd?: string;
             user?: string;
             /** @default 24 */
@@ -1348,6 +1364,25 @@ export interface components {
                 [key: string]: unknown;
             } | null;
         };
+        /**
+         * @description A pending suspend request (application API `POST /v1/workspaces/{id}/suspend-when-idle`):
+         *     once the workspace has been idle for `after_seconds` after `requested_at`, suspend it.
+         */
+        IdleSuspendRequest: {
+            /**
+             * Format: date-time
+             * @description When the request was made (database clock); a newer request replaces it.
+             */
+            requested_at: string;
+            after_seconds: number;
+            /**
+             * Format: date-time
+             * @description requested_at + after_seconds, the earliest suspend (the idle loop acts within
+             *     2 x ACTIVITY_FLUSH_MS after it). A work signal still active then defers it;
+             *     suspend_at is the projection.
+             */
+            not_before: string;
+        };
         IdleStatus: {
             policy: components["schemas"]["IdlePolicy"];
             /** @description Workspace observed_state (contracts §9). */
@@ -1365,6 +1400,8 @@ export interface components {
             /** Format: date-time */
             suspend_at: string | null;
             auto_suspend: components["schemas"]["IdleAutoSuspend"];
+            /** @description The pending suspend request while it is valid, else null. */
+            suspend_request: components["schemas"]["IdleSuspendRequest"] | null;
         };
     };
     responses: {

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.9.0";
+export declare const SDK_VERSION = "0.10.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

package/dist/http.js

@@ -8,7 +8,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.9.0';
+export const SDK_VERSION = '0.10.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends

package/dist/index.d.ts

@@ -15,14 +15,14 @@
 export type { components, operations, paths } from './generated/app-api.js';
 export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from './client.js';
-export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
 export type { FinishedOperation, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
 export { formatTiming } from './progress.js';
 export type { LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from './feedback.js';
 export type { AccountFeedbackParams, FeedbackCategory, FeedbackContext, FeedbackReceipt, SendFeedbackParams } from './feedback.js';
 export { UsageApi } from './usage.js';
-export type { Grants, Spend, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
+export type { Grants, Spend, SpendCap, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
 export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from './templates.js';
 export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from './template-file.js';
 export type { PackedFile, YamlParser } from './template-file.js';
@@ -50,10 +50,10 @@ export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, Ope
 export { CaptureError, ToolCallCapture, captureTool } from './capture.js';
 export type { CallLike, CallRef, CaptureCall, CaptureErrorKind, CaptureEvent, CaptureFlushResult, CapturePart, CaptureSelector, CaptureSource, CaptureStats, CaptureStatus, DropReason, ToolCallCaptureOptions, WrapOptions, } from './capture.js';
 export type { AiSdkAdapter, AiSdkToolEndEvent, AnthropicAdapter, ClaudeAdapter, ClaudeCaptureHooks, ClaudeHookCallback, ClaudeHookMatcher, LangChainAdapter, LangChainToolHandler, MastraAdapter, MastraAfterToolCallContext, McpAdapter, OpenAIAgentsAdapter, } from './capture-adapters.js';
-export { NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
+export { ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
 export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason, WorkspaceMode } from './errors.js';
 export { SDK_VERSION } from './http.js';
 export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from './account.js';
-export type { AccountClientOptions, AccountDeletion, AccountDeletionCanceled, AccountDeletionScheduled, ApiKey, ApiKeyPage, ApiKeyToolPermission, AuditExportParams, AuthSessionInfo, AuthSessionPage, AuthSessionState, AuthUser, BillingInvoicePage, BillingPortalSession, CheckoutStatus, CreateApiKeyParams, CreatedApiKey, DataExport, EmailChangeConfirmResult, EmailChangeResult, Invitation, InvitationPage, LoginResult, Member, MemberPage, MemberRole, MfaChallengeResult, Organization, OrganizationDeletion, OrganizationDeletionResult, OrganizationPage, OrganizationRole, OrganizationWorkspacePage, OrganizationWorkspacesParams, PageParams, PasswordChangeResult, PasswordResetConfirmResult, PasswordResetRequestResult, Project, ProjectPage, RecoveryCodes, RegisterResult, ResendVerificationResult, SessionTokenUpdate, ShardfluxAccountOptions, StepUpResult, TotpConfirmResult, TotpDisableResult, TotpEnrollment, VerifyEmailResult, WaitForCheckoutOptions, } from './account.js';
+export type { AccountClientOptions, AccountDeletion, AccountDeletionCanceled, AccountDeletionScheduled, ApiKey, ApiKeyPage, ApiKeyToolPermission, AuditExportParams, AuthSessionInfo, AuthSessionPage, AuthSessionState, AuthUser, BillingInvoicePage, BillingPortalSession, CheckoutStatus, CreateApiKeyParams, CreatedApiKey, DataExport, EmailChangeConfirmResult, EmailChangeResult, Invitation, InvitationPage, LoginResult, Member, MemberPage, MemberRole, MfaChallengeResult, Organization, OrganizationDeletion, OrganizationDeletionResult, OrganizationPage, OrganizationRole, OrganizationWorkspacePage, OrganizationWorkspacesParams, PageParams, PasswordChangeResult, PasswordResetConfirmResult, PasswordResetRequestResult, Project, ProjectPage, RecoveryCodes, RegisterResult, ResendVerificationResult, SessionTokenUpdate, ShardfluxAccountOptions, SpendPolicyUpdate, StepUpResult, TotpConfirmResult, TotpDisableResult, TotpEnrollment, VerifyEmailResult, WaitForCheckoutOptions, } from './account.js';
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from './version-check.js';
 export type { CheckClientVersionOptions, ClientEcosystem, ClientVersionEntry, ClientVersionStatus, ClientVersionStatusKind, ClientVersions, VersionCheckIdentity, VersionCheckOption, } from './version-check.js';

package/dist/index.js

@@ -15,7 +15,7 @@ export { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
 export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
-export { NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
+export { ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
 export { SDK_VERSION } from "./http.js";
 export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from "./account.js";
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from "./version-check.js";

package/dist/tools.js

@@ -11,6 +11,7 @@
  * providers' formats and executeToolCall dispatches a model's tool call.
  */
 import { CAPTURE_BARRIER } from "./cell.js";
+import { ExecStartError } from "./errors.js";
 import { newExecutionId } from "./executions.js";
 export class ToolArgumentError extends Error {
     tool;
@@ -160,13 +161,31 @@ export function workspaceTools(workspace, opts = {}) {
                 description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
                 parameters: execParameters,
                 run: async (a, o) => {
-                    const r = await cell().exec.run(['bash', '-lc', String(a.command)], {
-                        ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
-                        timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
-                        ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
-                        maxOutputBytes: max,
-                        ...(o.signal ? { signal: o.signal } : {}),
-                    });
+                    let r;
+                    try {
+                        r = await cell().exec.run(['bash', '-lc', String(a.command)], {
+                            ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                            timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
+                            ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                            maxOutputBytes: max,
+                            ...(o.signal ? { signal: o.signal } : {}),
+                        });
+                    }
+                    catch (e) {
+                        // Nothing ran (e.g. a cwd that is not a directory): the model gets the reason, as for an execution.
+                        if (!(e instanceof ExecStartError))
+                            throw e;
+                        return {
+                            exit_code: null,
+                            term_signal: null,
+                            timed_out: false,
+                            stdout: '',
+                            stderr: '',
+                            truncated: false,
+                            session_id: e.sessionId,
+                            error: { code: e.code, message: e.message, reason: e.reason },
+                        };
+                    }
                     return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
                 },
             },

package/dist/usage.d.ts

@@ -2,13 +2,21 @@
  * Usage, allowances, estimates, grants and spend (Phase 9 application API).
  *
  *   const s = await cloud.usage.summary(orgId);
- *   if (s.allowance_exhausted) ... // opens/resumes answer 402 allowance_exhausted
+ *   if (s.allowance_exhausted) ... // opens/resumes answer 402 allowance_exhausted, details.reason = s.exhausted_reason
+ *   s.spend_cap.state             // opt-in overage (0.10.0): 'accruing', 'warning', 'reached', ...
  *
  * Every response carries `measurement.measured_through` (usage is complete up to it) and both raw
  * (fractional) and billable (whole-unit) quantities. API keys read organization totals but only
  * their own project's workspaces.
+ *
+ * Opt-in overage (0.10.0): an owner or billing member can turn on overage with a spend cap in the console. While it is
+ * on, a CPU-hours or RAM GiB-hours allowance past `included` is in cap state `overage` (starts are admitted and the
+ * usage past it is charged on the next invoice) until the charges reach the cap. `summary()`, `spend()` and
+ * `estimate()` report it as `spend_cap` (`SpendCap`: state, cap, charges, lines per allowance, projected date);
+ * `spendPolicy()` returns the settings. An API key only reads them: owners and billing members change them in the
+ * console or with a user session (`ShardfluxAccount.billing.setSpendPolicy`).
  */
-import type { operations } from './generated/app-api.js';
+import type { components, operations } from './generated/app-api.js';
 import type { ClientContext } from './client.js';
 type JsonOf<R> = R extends {
     content: {
@@ -27,6 +35,13 @@ export type Grants = Ok<operations['getV1OrganizationsOrganizationIdGrants']>;
 export type Spend = Ok<operations['getV1OrganizationsOrganizationIdSpend']>;
 export type SpendPolicy = Ok<operations['getV1OrganizationsOrganizationIdSpendPolicy']>;
 export type UsageMeter = UsageSummary['meters'][number]['meter'];
+/**
+ * Opt-in overage this period (0.10.0), on `summary()`, `spend()` and `estimate()`: `state` (`unavailable`, `off`,
+ * `paused`, `within_allowance`, `accruing`, `warning`, `reached`), the configured and effective cap, `charges_minor`
+ * and `remaining_minor` (minor units of `currency`), `percent_of_cap`, `lines` (units past each allowance, billed units,
+ * rate and amount) and `projected_reached_at`.
+ */
+export type SpendCap = components['schemas']['SpendCap'];
 export interface UsageSeriesParams {
     /** RFC 3339; defaults to the current period's start. */
     from?: string;
@@ -39,22 +54,37 @@ export interface UsageSeriesParams {
 export declare class UsageApi {
     #private;
     constructor(ctx: () => ClientContext);
-    /** Current-period usage per meter, allowances with enforcement and cap state, measurement freshness. */
+    /**
+     * Current-period usage per meter, allowances with enforcement and cap state (`overage` while opt-in overage covers
+     * usage past a CPU-hours or RAM GiB-hours allowance), measurement freshness, `exhausted_reason` (the 402
+     * allowance_exhausted reason while starts are refused: `allowance_used`, `overage_paused`, `spend_cap_reached`) and
+     * `spend_cap` (0.10.0).
+     */
     summary(organizationId: string): Promise<UsageSummary>;
     /** Time series from the ledger (hour: <= 31 days, day: <= 400 days per request). */
     series(organizationId: string, params?: UsageSeriesParams): Promise<UsageSeries>;
     /** Usage of one workspace. */
     workspace(workspaceId: string, params?: Omit<UsageSeriesParams, 'workspaceId' | 'projectId'>): Promise<UsageSeries>;
-    /** Subscription fee, usage charges (0 while overage is disabled) and projected allowance use. */
+    /**
+     * Subscription fee, overage charges so far (`usage_charges_minor`, per meter in `usage_lines`), the estimated total,
+     * projected allowance use and `spend_cap` (0.10.0). Charges are 0 while overage is off or not on the plan.
+     */
     estimate(organizationId: string): Promise<UsageEstimate>;
     /** Quotas, per-workspace ceilings/reservations/grants and the compute budget leases granted to the cell. */
     grants(organizationId: string, params?: {
         limit?: number;
         cursor?: string;
     }): Promise<Grants>;
-    /** Spend policy, charges this period, cap state and enforcement (leases, overshoot bound). */
+    /**
+     * Spend policy, overage charges this period (`usage_charges_minor`), cap state (`overage` past an allowance under the
+     * cap), `exhausted_reason`, enforcement (leases, overshoot bound) and `spend_cap` (0.10.0).
+     */
     spend(organizationId: string): Promise<Spend>;
-    /** Usage alert thresholds (changing them is an owner/billing browser action). */
+    /**
+     * Usage alert thresholds and the overage settings (0.10.0): `overage_available`, `overage_enabled`, `overage_state`
+     * (`unavailable`, `off`, `on`, `paused`), `spend_cap_minor` with its bounds, `rates` and `currency`. Read-only for API
+     * keys: owners and billing members change them in the console or with `ShardfluxAccount.billing.setSpendPolicy`.
+     */
     spendPolicy(organizationId: string): Promise<SpendPolicy>;
 }
 export {};

package/dist/usage.js

@@ -7,7 +7,12 @@ export class UsageApi {
         const c = this.#ctx();
         return c.http.json('GET', path, query ? { query } : {}, c.authorization);
     }
-    /** Current-period usage per meter, allowances with enforcement and cap state, measurement freshness. */
+    /**
+     * Current-period usage per meter, allowances with enforcement and cap state (`overage` while opt-in overage covers
+     * usage past a CPU-hours or RAM GiB-hours allowance), measurement freshness, `exhausted_reason` (the 402
+     * allowance_exhausted reason while starts are refused: `allowance_used`, `overage_paused`, `spend_cap_reached`) and
+     * `spend_cap` (0.10.0).
+     */
     summary(organizationId) {
         return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/usage/summary`);
     }
@@ -26,7 +31,10 @@ export class UsageApi {
     workspace(workspaceId, params = {}) {
         return this.#get(`/v1/workspaces/${encodeURIComponent(workspaceId)}/usage`, { from: params.from, to: params.to, granularity: params.granularity, meter: params.meter });
     }
-    /** Subscription fee, usage charges (0 while overage is disabled) and projected allowance use. */
+    /**
+     * Subscription fee, overage charges so far (`usage_charges_minor`, per meter in `usage_lines`), the estimated total,
+     * projected allowance use and `spend_cap` (0.10.0). Charges are 0 while overage is off or not on the plan.
+     */
     estimate(organizationId) {
         return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/usage/estimate`);
     }
@@ -34,11 +42,18 @@ export class UsageApi {
     grants(organizationId, params = {}) {
         return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/grants`, { limit: params.limit, cursor: params.cursor });
     }
-    /** Spend policy, charges this period, cap state and enforcement (leases, overshoot bound). */
+    /**
+     * Spend policy, overage charges this period (`usage_charges_minor`), cap state (`overage` past an allowance under the
+     * cap), `exhausted_reason`, enforcement (leases, overshoot bound) and `spend_cap` (0.10.0).
+     */
     spend(organizationId) {
         return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/spend`);
     }
-    /** Usage alert thresholds (changing them is an owner/billing browser action). */
+    /**
+     * Usage alert thresholds and the overage settings (0.10.0): `overage_available`, `overage_enabled`, `overage_state`
+     * (`unavailable`, `off`, `on`, `paused`), `spend_cap_minor` with its bounds, `rates` and `currency`. Read-only for API
+     * keys: owners and billing members change them in the console or with `ShardfluxAccount.billing.setSpendPolicy`.
+     */
     spendPolicy(organizationId) {
         return this.#get(`/v1/organizations/${encodeURIComponent(organizationId)}/spend-policy`);
     }

package/dist/workspace.d.ts

@@ -2,7 +2,7 @@
  * A workspace handle: the latest view from the application API plus managed
  * tool tokens and cell clients (one per agent label / tool set).
  */
-import type { ClientContext, DiskLayout, ForkTarget, Operation, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { ClientContext, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
 import { CAPTURE_BARRIER, CellClient } from './cell.js';
 import { ToolCallCapture } from './capture.js';
 import type { ToolCallCaptureOptions } from './capture.js';
@@ -100,6 +100,12 @@ export declare class Workspace {
      * an older API. A failed startup leaves the workspace running for inspection; the next open runs the failed step again.
      */
     get startup(): WorkspaceStartup | null;
+    /**
+     * The pending suspend-when-idle request as of the last view (0.10.0; `idle.suspend_request`): `{requested_at,
+     * after_seconds, not_before}`, or null when there is none, when the workspace is not running, or once a tool call or
+     * a resume after the request cancelled it. `refresh()` reads it again.
+     */
+    get suspendRequest(): SuspendRequest | null;
     /** The raw view (GET /v1/workspaces/{id}). */
     get data(): WorkspaceView;
     /**
@@ -145,6 +151,22 @@ export declare class Workspace {
      */
     suspend(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     suspend(opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (30..3600; 0.9.0): call it when your agent's turn
+     * ends, so the workspace stops using RAM soon after instead of waiting out its idle policy. A command still running,
+     * an attached stream or a keepalive postpones the suspend until `afterSeconds` after it ends; the next tool call (the
+     * next turn) or a resume cancels it. Resolves with the recorded `suspendRequest` (also `workspace.suspendRequest`), or
+     * with the suspend already in progress as `operation`. See WorkspacesApi.suspendWhenIdle for the errors. A file-first
+     * workspace (never suspended) is refused locally with NotSupportedForModeError.
+     *
+     *   const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 });
+     */
+    suspendWhenIdle(opts: SuspendWhenIdleOptions): Promise<SuspendWhenIdleResult>;
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; idempotent, in any state) and refreshes this handle's view.
+     * A suspend the request already started is not undone (it shows as `activeOperation`).
+     */
+    cancelSuspendWhenIdle(): Promise<this>;
     /**
      * Resumes a suspended workspace. Resolves when the resume is REQUESTED; with `{ wait: true }`, once the workspace runs.
      * Tool calls wake a suspended workspace by themselves, so this is rarely needed. With `wait` (0.9.0) it is one held

package/dist/workspace.js

@@ -132,6 +132,14 @@ export class Workspace {
     get startup() {
         return this.#view.startup ?? null;
     }
+    /**
+     * The pending suspend-when-idle request as of the last view (0.10.0; `idle.suspend_request`): `{requested_at,
+     * after_seconds, not_before}`, or null when there is none, when the workspace is not running, or once a tool call or
+     * a resume after the request cancelled it. `refresh()` reads it again.
+     */
+    get suspendRequest() {
+        return this.#view.idle?.suspend_request ?? null;
+    }
     /** The raw view (GET /v1/workspaces/{id}). */
     get data() {
         return this.#view;
@@ -193,6 +201,32 @@ export class Workspace {
             return Promise.reject(refusal);
         return this.#ctx.workspaces.suspend(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (30..3600; 0.9.0): call it when your agent's turn
+     * ends, so the workspace stops using RAM soon after instead of waiting out its idle policy. A command still running,
+     * an attached stream or a keepalive postpones the suspend until `afterSeconds` after it ends; the next tool call (the
+     * next turn) or a resume cancels it. Resolves with the recorded `suspendRequest` (also `workspace.suspendRequest`), or
+     * with the suspend already in progress as `operation`. See WorkspacesApi.suspendWhenIdle for the errors. A file-first
+     * workspace (never suspended) is refused locally with NotSupportedForModeError.
+     *
+     *   const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 });
+     */
+    async suspendWhenIdle(opts) {
+        const refusal = this.#needsVm('suspend_when_idle');
+        if (refusal)
+            throw refusal;
+        const out = await this.#ctx.workspaces.suspendWhenIdle(this.id, opts);
+        this.#view = out.workspace.data;
+        return { ...out, workspace: this };
+    }
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; idempotent, in any state) and refreshes this handle's view.
+     * A suspend the request already started is not undone (it shows as `activeOperation`).
+     */
+    async cancelSuspendWhenIdle() {
+        this.#view = (await this.#ctx.workspaces.cancelSuspendWhenIdle(this.id)).data;
+        return this;
+    }
     resume(opts = {}) {
         const refusal = this.#needsVm('resume');
         if (refusal)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",