@shardflux/sdk 0.8.0 → 0.10.0

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/version-check.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Client version check (contracts §30.4; 0.9.0+). `GET /v1/client-versions` (unauthenticated) lists every published
+ * client with its `latest` and `minimum_supported` version.
+ *
+ *   const s = await checkClientVersion();            // @shardflux/sdk at SDK_VERSION
+ *   if (s.status !== 'current') console.error(s.message ?? s.status);
+ *
+ * Automatically, the first successful API response of a `Shardflux` or `ShardfluxAccount` client starts the same check
+ * in the background, once per process per package identity (one request, 3 s timeout, every error swallowed), and
+ * emits `process.emitWarning(message, { type: 'ShardfluxUpdateWarning', code: 'SHARDFLUX_UPDATE_AVAILABLE' })` when
+ * the package is outdated or unsupported. Opt out with the option `versionCheck: false`, or the environment
+ * `SHARDFLUX_NO_UPDATE_CHECK=1` (also `true`, `yes`, `on`) or `NO_UPDATE_NOTIFIER=1`. Tools built on the SDK pass their
+ * own identity (`versionCheck: { package, version }`) or `false`.
+ */
+import type { operations } from './generated/app-api.js';
+type JsonOf<R> = R extends {
+    content: {
+        'application/json': infer T;
+    };
+} ? T : never;
+type Ok<Op> = Op extends {
+    responses: infer R;
+} ? {
+    [K in keyof R]: K extends 200 | 201 | 202 ? JsonOf<R[K]> : never;
+}[keyof R] : never;
+/** The body of GET /v1/client-versions. */
+export type ClientVersions = Ok<operations['getV1ClientVersions']>;
+export type ClientVersionEntry = ClientVersions['clients'][number];
+export type ClientEcosystem = ClientVersionEntry['ecosystem'];
+export declare const DEFAULT_BASE_URL = "https://api.shardflux.dev";
+export declare const SDK_PACKAGE = "@shardflux/sdk";
+/** The check's request timeout (ms). */
+export declare const VERSION_CHECK_TIMEOUT_MS = 3000;
+/**
+ * `unsupported` (below `minimum_supported`), `outdated` (below `latest`), `current` (otherwise) or `unknown` (no entry
+ * for the package, `latest` null (not distributed yet), a version that does not parse, or the request failed).
+ */
+export type ClientVersionStatusKind = 'current' | 'outdated' | 'unsupported' | 'unknown';
+export interface ClientVersionStatus {
+    status: ClientVersionStatusKind;
+    package: string;
+    ecosystem: ClientEcosystem;
+    /** The version this process runs. */
+    current: string;
+    latest: string | null;
+    minimumSupported: string | null;
+    upgradeCommand: string | null;
+    releaseNotesUrl: string | null;
+    /** The one-line notice, for `outdated` and `unsupported` only. */
+    message?: string;
+}
+/** A tool's own identity for the check (a CLI or server built on the SDK). */
+export interface VersionCheckIdentity {
+    package: string;
+    version: string;
+    /** Default `npm`. */
+    ecosystem?: ClientEcosystem;
+}
+/** `true` (default): `@shardflux/sdk` at SDK_VERSION; `false`: no automatic check; or the tool's own identity. */
+export type VersionCheckOption = boolean | VersionCheckIdentity;
+export interface CheckClientVersionOptions {
+    /** Default https://api.shardflux.dev. */
+    baseUrl?: string;
+    /** Default: the SDK's default fetch. */
+    fetch?: typeof fetch;
+    /** Default `@shardflux/sdk`. */
+    package?: string;
+    /** Default SDK_VERSION (when `package` is `@shardflux/sdk`). */
+    version?: string;
+    /** Default `npm`. */
+    ecosystem?: ClientEcosystem;
+    /** Default 3000 ms. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    userAgent?: string;
+}
+/**
+ * -1, 0 or 1 as `a` is older than, the same as, or newer than `b`: `major.minor.patch` compare numerically, a
+ * pre-release (`0.8.0-rc.1`) sorts before its release, build metadata (`+local`) is ignored. `null` when either string
+ * is not such a version (the check then reports `unknown`).
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1 | null;
+/** The status of `package` at `version` from a GET /v1/client-versions body (no request). */
+export declare function clientVersionStatus(body: unknown, identity: VersionCheckIdentity): ClientVersionStatus;
+/**
+ * Asks the API whether this client is current (GET /v1/client-versions; one request, 3 s timeout by default). Never
+ * throws: a failed request, a non-2xx answer or a body that is not the documented JSON is `unknown`.
+ */
+export declare function checkClientVersion(opts?: CheckClientVersionOptions): Promise<ClientVersionStatus>;
+/** True when the environment turns the automatic check off (SHARDFLUX_NO_UPDATE_CHECK truthy, NO_UPDATE_NOTIFIER set). */
+export declare function versionCheckDisabledByEnv(env?: Record<string, string | undefined> | undefined): boolean;
+/**
+ * The HttpClient hook a client installs: after its first successful response, start the check for its identity
+ * unless it already ran in this process or is turned off. Returns undefined when the option turns the check off.
+ */
+export declare function versionCheckHook(option: VersionCheckOption | undefined, baseUrl: string, f: typeof fetch, userAgent: string): (() => void) | undefined;
+/** Tests: resolves when every started background check has finished. */
+export declare function settleVersionChecks(): Promise<void>;
+/** Tests: forget which identities were checked in this process. */
+export declare function resetVersionChecks(): void;
+export {};

package/dist/version-check.js

@@ -0,0 +1,191 @@
+import { SDK_VERSION, buildUrl, defaultFetch } from "./http.js";
+export const DEFAULT_BASE_URL = 'https://api.shardflux.dev';
+export const SDK_PACKAGE = '@shardflux/sdk';
+/** The check's request timeout (ms). */
+export const VERSION_CHECK_TIMEOUT_MS = 3_000;
+// major.minor.patch, then a SemVer pre-release (-rc.1) or a PEP 440 one (rc1, .dev0), then +build metadata (ignored).
+// The same grammar as the Python SDK's compare_versions.
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)|\.?([A-Za-z][0-9A-Za-z]*(?:\.[0-9A-Za-z]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function versionKey(version) {
+    if (typeof version !== 'string')
+        return null;
+    const m = VERSION.exec(version.trim());
+    if (!m)
+        return null;
+    const core = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (!core.every(Number.isSafeInteger))
+        return null;
+    const pre = m[4] ?? m[5];
+    if (pre === undefined)
+        return { core, pre: null };
+    // Numeric runs compare as numbers and sort before alphanumeric ones; "rc10" sorts after "rc2".
+    const tokens = [];
+    for (const ident of pre.split('.')) {
+        for (const part of ident.match(/\d+|\D+/g) ?? [])
+            tokens.push(/^\d+$/.test(part) ? [0, Number(part)] : [1, part]);
+    }
+    return { core, pre: tokens };
+}
+const sign = (n) => (n < 0 ? -1 : n > 0 ? 1 : 0);
+function compareKeys(a, b) {
+    for (let i = 0; i < 3; i += 1)
+        if (a.core[i] !== b.core[i])
+            return sign(a.core[i] - b.core[i]);
+    if (a.pre === null || b.pre === null)
+        return a.pre === b.pre ? 0 : a.pre === null ? 1 : -1;
+    const n = Math.min(a.pre.length, b.pre.length);
+    for (let i = 0; i < n; i += 1) {
+        const [ka, va] = a.pre[i];
+        const [kb, vb] = b.pre[i];
+        if (ka !== kb)
+            return ka < kb ? -1 : 1;
+        if (va !== vb)
+            return va < vb ? -1 : 1;
+    }
+    return sign(a.pre.length - b.pre.length);
+}
+/**
+ * -1, 0 or 1 as `a` is older than, the same as, or newer than `b`: `major.minor.patch` compare numerically, a
+ * pre-release (`0.8.0-rc.1`) sorts before its release, build metadata (`+local`) is ignored. `null` when either string
+ * is not such a version (the check then reports `unknown`).
+ */
+export function compareVersions(a, b) {
+    const ka = versionKey(a);
+    const kb = versionKey(b);
+    return ka && kb ? compareKeys(ka, kb) : null;
+}
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+/** The status of `package` at `version` from a GET /v1/client-versions body (no request). */
+export function clientVersionStatus(body, identity) {
+    const ecosystem = identity.ecosystem ?? 'npm';
+    const base = {
+        status: 'unknown',
+        package: identity.package,
+        ecosystem,
+        current: identity.version,
+        latest: null,
+        minimumSupported: null,
+        upgradeCommand: null,
+        releaseNotesUrl: null,
+    };
+    const clients = typeof body === 'object' && body !== null ? body.clients : undefined;
+    const entry = Array.isArray(clients)
+        ? clients.find((c) => typeof c === 'object' && c !== null && c.package === identity.package && c.ecosystem === ecosystem)
+        : undefined;
+    if (entry === undefined)
+        return base;
+    const latest = str(entry.latest);
+    const minimum = str(entry.minimum_supported);
+    const upgrade = str(entry.upgrade_command) ?? (ecosystem === 'npm' ? `npm install ${identity.package}@latest` : `pip install --upgrade ${identity.package}`);
+    const out = { ...base, latest, minimumSupported: minimum, upgradeCommand: upgrade, releaseNotesUrl: str(entry.release_notes_url) };
+    // latest null: not distributed yet, so stay silent (also about minimum_supported).
+    if (latest === null)
+        return out;
+    const vsLatest = compareVersions(identity.version, latest);
+    if (vsLatest === null)
+        return out;
+    const vsMinimum = minimum === null ? null : compareVersions(identity.version, minimum);
+    if (vsMinimum === -1) {
+        return { ...out, status: 'unsupported', message: `${identity.package} ${identity.version} is no longer supported by the Shardflux API (minimum ${minimum}). Update: ${upgrade}` };
+    }
+    if (vsLatest === -1)
+        return { ...out, status: 'outdated', message: `${identity.package} ${identity.version} is outdated: ${latest} is available. Update: ${upgrade}` };
+    return { ...out, status: 'current' };
+}
+/**
+ * Asks the API whether this client is current (GET /v1/client-versions; one request, 3 s timeout by default). Never
+ * throws: a failed request, a non-2xx answer or a body that is not the documented JSON is `unknown`.
+ */
+export async function checkClientVersion(opts = {}) {
+    const pkg = opts.package ?? SDK_PACKAGE;
+    const version = opts.version ?? (pkg === SDK_PACKAGE ? SDK_VERSION : undefined);
+    const identity = { package: pkg, version: version ?? '', ecosystem: opts.ecosystem ?? 'npm' };
+    // Another package without its version cannot be compared.
+    if (version === undefined)
+        return clientVersionStatus(null, identity);
+    try {
+        const f = opts.fetch ?? defaultFetch();
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? VERSION_CHECK_TIMEOUT_MS);
+        const signal = opts.signal ? AbortSignal.any([timeout, opts.signal]) : timeout;
+        const res = await f(buildUrl(opts.baseUrl ?? DEFAULT_BASE_URL, '/v1/client-versions'), {
+            method: 'GET',
+            headers: { accept: 'application/json', 'user-agent': opts.userAgent ?? `shardflux-sdk-ts/${SDK_VERSION}` },
+            signal,
+        });
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => undefined);
+            return clientVersionStatus(null, identity);
+        }
+        return clientVersionStatus(JSON.parse(await res.text()), identity);
+    }
+    catch {
+        return clientVersionStatus(null, identity);
+    }
+}
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+/** True when the environment turns the automatic check off (SHARDFLUX_NO_UPDATE_CHECK truthy, NO_UPDATE_NOTIFIER set). */
+export function versionCheckDisabledByEnv(env = globalThis.process?.env) {
+    if (!env)
+        return false;
+    const own = env.SHARDFLUX_NO_UPDATE_CHECK;
+    if (own !== undefined && TRUTHY.has(own.trim().toLowerCase()))
+        return true;
+    const npm = env.NO_UPDATE_NOTIFIER;
+    return npm !== undefined && npm !== '';
+}
+/** Package identities already checked (or being checked) in this process. */
+const started = new Set();
+const inFlight = new Set();
+function emitUpdateWarning(message) {
+    const p = globalThis.process;
+    if (p && typeof p.emitWarning === 'function')
+        p.emitWarning(message, { type: 'ShardfluxUpdateWarning', code: 'SHARDFLUX_UPDATE_AVAILABLE' });
+    else
+        console.warn(message);
+}
+/**
+ * The HttpClient hook a client installs: after its first successful response, start the check for its identity
+ * unless it already ran in this process or is turned off. Returns undefined when the option turns the check off.
+ */
+export function versionCheckHook(option, baseUrl, f, userAgent) {
+    if (option === false)
+        return undefined;
+    const identity = option === undefined || option === true ? { package: SDK_PACKAGE, version: SDK_VERSION } : option;
+    let fired = false;
+    return () => {
+        if (fired)
+            return;
+        fired = true;
+        startVersionCheck(identity, baseUrl, f, userAgent);
+    };
+}
+function startVersionCheck(identity, baseUrl, f, userAgent) {
+    try {
+        if (versionCheckDisabledByEnv())
+            return;
+        const key = `${identity.ecosystem ?? 'npm'}\u0000${identity.package}\u0000${identity.version}`;
+        if (started.has(key))
+            return;
+        started.add(key);
+        const run = checkClientVersion({ baseUrl, fetch: f, userAgent, package: identity.package, version: identity.version, ecosystem: identity.ecosystem ?? 'npm' })
+            .then((s) => {
+            if ((s.status === 'outdated' || s.status === 'unsupported') && s.message)
+                emitUpdateWarning(s.message);
+        })
+            .catch(() => undefined);
+        inFlight.add(run);
+        void run.finally(() => inFlight.delete(run));
+    }
+    catch {
+        // Never fails the caller.
+    }
+}
+/** Tests: resolves when every started background check has finished. */
+export async function settleVersionChecks() {
+    while (inFlight.size > 0)
+        await Promise.all([...inFlight]);
+}
+/** Tests: forget which identities were checked in this process. */
+export function resetVersionChecks() {
+    started.clear();
+}

package/dist/workspace.d.ts

@@ -2,15 +2,16 @@
  * 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';
-import type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
+import type { WorkspaceMode } from './errors.js';
+import type { FinishedOperation, LifecycleOptions, ResumeOptions, WaitedLifecycleOptions, WaitedResumeOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
 import { WorkspaceSecrets } from './secrets.js';
-import type { CellClientOptions, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
+import type { CellClientOptions, Residency, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse, WorkspaceStartup } from './templates.js';
 import { ToolTokenManager } from './tokens.js';
 import type { ToolName, ToolToken } from './tokens.js';
@@ -20,6 +21,38 @@ export interface WakeOptions {
     signal?: AbortSignal;
     /** Progress of the wake: the resume request, observed states, conflicts retried, and `done` with the timing. */
     onProgress?: ProgressListener;
+    /**
+     * The tool token the wake brings back (0.9.0): the held resume (contracts §22.6) returns one with the running
+     * workspace, for this agent label and tool set (defaults: those given to open()). It is kept for `cell()` clients of
+     * the same label and tools, whose next call then needs no token request. A `cell()` client's own wake passes its
+     * label and tools.
+     */
+    agentLabel?: string;
+    tools?: ToolName[];
+}
+export interface HintOptions {
+    /** The tool token to use: the agent label and tool set of `cell()` (defaults: those given to open()). */
+    agentLabel?: string;
+    tools?: ToolName[];
+    /**
+     * When the workspace is not running: how to wake it in the background. Default `workspace.wake()`; `null` does not
+     * wake it; a function replaces the wake (the same hook as `CellClientOptions.wake`).
+     */
+    wake?: CellClientOptions['wake'];
+    /** Bound on the background wake (default 120 000 ms). */
+    wakeTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** `workspace.hint()`: what the host found, or the background wake of a workspace that was not running. */
+export interface HintResult {
+    /** The VM's residency when the hint arrived (contracts §25.1); null when the workspace was not running. */
+    residency: Residency | null;
+    /**
+     * The wake started in the background because the workspace was not running (409 `workspace_not_running`), else null.
+     * It resolves like `wake()`; nothing needs to await it (a failure is then left to the next tool call, which wakes
+     * the workspace itself), and concurrent hints share one wake.
+     */
+    wake: Promise<boolean> | null;
 }
 export declare class Workspace {
     #private;
@@ -67,8 +100,35 @@ 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;
+    /**
+     * `processful` (one VM keeps processes, memory and files) or `file_first` (0.9.0; contracts §29: a versioned file
+     * tree, commands run as executions). Immutable. A view without the field (older API) is processful.
+     */
+    get mode(): WorkspaceMode;
+    /**
+     * File-first workspaces: the newest tree revision this handle has seen (0 when created; each mutating files call or
+     * execution that changed something publishes the next). It follows every response of this handle's cell clients
+     * (`X-Tree-Revision`), execution results and refresh(); another writer's changes appear once a response reports
+     * them. Pass it as `ifTreeRevision` to make a write conditional. Null for processful workspaces.
+     */
+    get treeRevision(): number | null;
+    /**
+     * Executions of this file-first workspace (contracts §29.8) through `cell()`'s default client: `run(argv, opts)` runs
+     * a command in a fresh VM on the latest tree and returns an ExecutionResult (output, exit code, `changed`,
+     * `treeRevision`); `get(id, { waitMs })` reads one. See CellClient.executions.
+     *
+     *   const r = await workspace.executions.run(['bash', '-lc', 'pytest -q'], { timeoutMs: 600_000 });
+     *   console.log(r.exitCode, r.stdoutText, r.changed, r.treeRevision);
+     */
+    get executions(): CellClient['executions'];
     /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
     get secrets(): WorkspaceSecrets;
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
@@ -91,12 +151,31 @@ 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.
+     * Tool calls wake a suspended workspace by themselves, so this is rarely needed. With `wait` (0.9.0) it is one held
+     * request (contracts §22.6): the handle takes the running view and a tool token for `agentLabel`/`tools` (defaults:
+     * those given to open()), so `cell()` calls with that label and tools start at once. A workspace that is already
+     * running is ShardfluxApiError 409 `conflict` (`already_running`).
      */
-    resume(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
-    resume(opts?: LifecycleOptions): Promise<Operation>;
+    resume(opts: WaitedResumeOptions): Promise<FinishedOperation>;
+    resume(opts?: ResumeOptions): Promise<Operation>;
     /** Takes a snapshot. Resolves when it is REQUESTED; with `{ wait: true }`, once it is taken. */
     snapshot(opts: WaitedLifecycleOptions & {
         label?: string;
@@ -151,6 +230,7 @@ export declare class Workspace {
     /**
      * The workspace's changes against its template (cell gateway GET /v1/workspaces/{id}/changes; needs the `files` tool).
      * 409 workspace_not_running, or conflict with details.reason legacy_disk_layout / guest_feature_unavailable.
+     * File-first workspaces: NotSupportedForModeError (each execution result lists what it changed).
      */
     changes(opts?: WorkspaceChangesParams & {
         agentLabel?: string;
@@ -180,8 +260,22 @@ export declare class Workspace {
      * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`. A resume no
      * host admits within 15 minutes fails with `capacity_unavailable` (OperationFailedError, `retryable`: the workspace
      * stays suspended with its state; try again later).
+     *
+     * Since 0.9.0 the resume is held by the server until the workspace runs (contracts §22.6): one request returns the
+     * running workspace and a tool token for `agentLabel`/`tools`, which this handle keeps, so a tool call that woke the
+     * workspace is retried at once (refused call, resume, call). Timing: one `request` phase with reason `held`. A server
+     * that does not hold the request answers at once; the wake then waits for the operation and reads the view.
      */
     wake(opts?: WakeOptions): Promise<boolean>;
+    /**
+     * Announces an imminent tool call (cell `POST /wake-hint`, contracts §26.6; 0.9.0+) so a parked workspace is restored
+     * ahead of it: call it when the model starts emitting a tool call, before its arguments are complete. The agent tools
+     * of `workspaceTools()` send it when a call starts. Cheap and best effort: it returns what the host found. A workspace
+     * that is not running (suspended, or a token cannot be issued for it) is woken in the background (`wake`, not awaited
+     * here) so the call finds it running sooner. Other errors (network, auth) are thrown; callers that fire and forget
+     * should catch them.
+     */
+    hint(opts?: HintOptions): Promise<HintResult>;
     /** Tools granted by the most recent token (null before one was issued). */
     get grantedTools(): ToolName[] | null;
 }