@shardflux/sdk 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -3,7 +3,31 @@
 Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
 marked **Breaking**.
 
-## 0.15.0 (not yet published)
+## 0.16.0 (not yet published)
+
+- Add `@shardflux/sdk/testing`: `createFakeShardflux` supplies an isolated in-memory transport beneath real SDK handles, refs and errors, with scripted commands, a virtual clock, fault controls and captured response shapes. A shared scenario manifest runs against the fake and live API.
+
+- Add opt-in persistent workspace idle deletion retention, workspace/project setters and projected deletion times.
+
+- Accelerate reverse tunnels with a bounded, acknowledged binary WebSocket stream, 64 KiB frames and batched credits. Select `auto`, `pty` or `exec` transport; reconnect preserves byte offsets. Opt-in binary PTY output accepts larger blocks for file transfers.
+
+- Add opt-in resize controls to grow named resources only and return the held server answer without polling a pending operation.
+- Expose typed stored workspace caps and preserve nullable grants. Fixed memory without an explicit size uses the template default.
+
+- `WorkspaceRef.turn(fn, { afterSeconds: 0 })` and `Workspace.turn()` hint without waiting and request idle suspension when the body settles, including errors.
+- Computer `act()` avoids an extra screenshot after `screenshot`/`zoom`. Viewer links are reused by kind with more than 60 seconds left; `fresh: true` remints, and `stopStream()` clears them.
+- `computerToolset(ws, { beforeAction })` and `workspaceTools(ws, { computer: { beforeAction } })` check each action immediately before execution; refusal answers that action with an error and skips the rest.
+- The default pooled transport honors environment HTTP(S) proxies and NO_PROXY. `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL`, which takes precedence.
+- Exec and execution results expose `exitCodePosix`. Missing cell file paths with `path_not_found` raise `FileNotFoundError`, distinct from workspace deletion and protocol errors.
+- Embed live desktop viewers and port previews in a web app with an explicit HTTPS origin allowlist and partitioned browser sessions.
+
+- Add `workspace.tunnels.reverse({ remotePort, target, bindAddress?, signal? })`: a private workspace TCP listener forwarded to this machine, with binary multiplexing, bounded backpressure, half-close, transport reconnection, suspend/resume, statistics and deterministic close.
+
+- Add `ws.upgrade({ at })`, `upgradeAvailable` and `upgradePending`. An opt-in cold start preserves the workspace disk; `next_resume` schedules it. Lifecycle cold boot reasons include `upgraded`.
+
+### Integration testing
+
+## 0.15.0 — 2026-10-04
 
 ### Workspaces by key
 
@@ -45,12 +69,10 @@ Additive. A desktop in the workspace that agents drive with screenshots, clicks
 - `cloud.templates.setComputerUse(slug, enabled, { organizationId })` switches it for every workspace of one of your
   templates. `ToolName` includes `computer`; template views carry `computer_use`.
 
-## 0.14.0 — 2026-10-04 (not yet published)
+## 0.14.0 — 2026-10-04
 
 - Opt-in `workspaceTools(workspace, { prewake: true })` input-start hooks prepare VM tools while their input streams. Default tools, offline reads and file-first workspaces install no hook.
 
-## 0.14.0 (not yet published)
-
 ### Sign up from an agent
 
 Additive (API contracts §44).
@@ -159,7 +181,7 @@ gives a static allocation of `memory_mib`. Reopening an existing workspace with
 keeps its stored mode; a fork without caps inherits its source's. The SDK's requests do not change;
 `workspace.memory` and `workspace.allocationMode` report the mode the workspace got.
 
-## 0.13.1 (not yet published)
+## 0.13.1 — 2026-10-03
 
 Patch, additive: the transport, a documented value, a fix for tool calls across a move and self-healing workspaces.
 `@shardflux/cli` 0.8.1, `@shardflux/mcp` 0.7.1 and the `shardflux` bundle 0.10.1 follow (`^0.13.1`).
@@ -216,7 +238,7 @@ failing with `409 conflict` (`workspace_not_running`).
   runs; new token)`.
 - The CLI, the MCP server and the `shardflux` bundle get it through their `^0.13.0` dependency.
 
-## 0.13.0
+## 0.13.0 — 2026-10-02
 
 ### Elastic memory
 
@@ -326,14 +348,12 @@ template's newest published version, picked up at its next cold boot or resume.
 - The cancel that `exec.run` sends when its `signal` aborts passes `killGraceMs` capped at 60000, so a larger
   `killGraceMs` still cancels the command.
 
-## 0.12.0 (release candidate)
+## 0.12.0 — 2026-09-30
 
 Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
 
 Pooled HTTP/1.1 on Node 26 with pinned undici 8.10.2; custom fetch stays unchanged. Labels on open/list and setLabels, typed idle(), keepalive() and setIdlePolicy(). Protocol errors carry source; isWorkspaceGone recognizes only an explicit API workspace_deleted refusal. Exec sessions accept stdin_open and offset-addressed exec.input. Failed workspaces recover through resume/auto-wake with the same ID. Completed deletions free keys for new IDs.
 
-Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
-
 ### Instant suspend: durable storage in the result
 
 Additive. A suspend returns as soon as the workspace is sealed on its host; the copy lands in durable storage right
@@ -358,7 +378,7 @@ after. This release reads that from the result and can wait for it.
 Requires the instant-suspend cell release for `durable: false` results; against other servers every succeeded suspend
 is already durable and `durable: true` resolves at once.
 
-## 0.11.1
+## 0.11.1 — 2026-09-30
 
 Wording: messages and JSDoc say what to do, without internals (no behaviour change).
 
@@ -372,7 +392,7 @@ Wording: messages and JSDoc say what to do, without internals (no behaviour chan
   `SHARDFLUX_HTTP_KEEPALIVE=1`.
 - The `formatTiming()` example is a production resume (413 ms).
 
-## 0.11.0
+## 0.11.0 — 2026-09-29
 
 ### A resume that restarted processes says so (cold boot)
 
@@ -395,17 +415,17 @@ the resume's result through; this release reads it.
 - The new `ServerTiming` fields are optional in the type (always set by the SDK), so timings built by hand still
   type-check. No return type or behaviour changes: a wake that cold-booted still resolves `true`.
 
-## 0.10.2
+## 0.10.2 — 2026-09-29
 
 Fix: the SDK reports 0.10.2. 0.10.1 was published reporting 0.10.0, its previous version; the build now
 fails when `SDK_VERSION` differs from package.json.
 
-## 0.10.1
+## 0.10.1 — 2026-09-29
 
 Public support: package metadata and the README now link to the [shared bug tracker](https://github.com/shardfluxdev/community/issues),
 feature requests, and private support/security reporting.
 
-## 0.10.0
+## 0.10.0 — 2026-09-29
 
 ### A command that could not start rejects exec.run() (ExecStartError)
 
@@ -453,7 +473,7 @@ from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overa
 
 - `workspace.suspendWhenIdle({ afterSeconds, idempotencyKey? })` and `cloud.workspaces.suspendWhenIdle(id, {
   afterSeconds })` (POST /v1/workspaces/{id}/suspend-when-idle): the workspace is suspended once it has been idle for
-  `afterSeconds` (30..3600), counted from the later of its last work and the request. Meant for the end of an agent
+  `afterSeconds` (0..3600 since the 2026-09-30 API release, commit `2b2f5e658`; originally 30..3600), counted from the later of its last work and the request. Meant for the end of an agent
   turn. A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.
   Resolves with `{ suspendRequest, operation, workspace }`: `operation` is the suspend already in progress, if any
   (then nothing is recorded).
@@ -463,7 +483,7 @@ from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overa
   count as the next turn and cancel the request.
 - Types `SuspendRequest`, `SuspendWhenIdleOptions`, `SuspendWhenIdleResult`, `SuspendWhenIdleResponse`.
 
-## 0.9.0
+## 0.9.0 — 2026-09-29
 
 Elastic compute (decision 0007): file tools and wake hints for parked workspaces. Additive; older APIs and cell
 gateways keep working (the new calls answer 404 there).
@@ -659,7 +679,7 @@ behavior is the automatic version check (below), which makes one background requ
 - New exports: `FeedbackCategory`, `FeedbackContext`, `FeedbackReceipt`, `SendFeedbackParams`, `AccountFeedbackParams`,
   `FEEDBACK_CATEGORIES`, `FEEDBACK_MESSAGE_MAX_LENGTH`.
 
-## 0.8.0 (2026-09-28)
+## 0.8.0 — 2026-09-28
 
 Types only; nothing changes at run time and the API is unchanged.
 
@@ -679,7 +699,7 @@ Types only; nothing changes at run time and the API is unchanged.
 - Checked at compile time against `@anthropic-ai/sdk` 0.128.0 and `openai` 7.23.0 (devDependencies only; the SDK still
   has no runtime dependencies).
 
-## 0.7.0 (2026-09-28)
+## 0.7.0 — 2026-09-28
 
 Needs an API with the template editor; every new field is additive and older fields are unchanged.
 
@@ -767,7 +787,7 @@ docs/decisions/0006-tool-call-capture.md (shared with the Python SDK 0.3.0).
 - **Breaking (types only):** `LifecyclePhase` gains `capture_flush`; an exhaustive `switch` over phases without a
   `default` case needs the new member.
 
-## 0.6.2 (2026-09-28)
+## 0.6.2 — 2026-09-28
 
 ### Starts that wait for capacity end
 
@@ -782,7 +802,7 @@ boot (and bill) long after every wait had given up.
 - `onProgress`: a `capacity_pending` `phase` event carries `deadlineAt` when the API reports it.
 - Docs: waits no longer say a pending start continues indefinitely.
 
-## 0.6.1 (2026-09-28)
+## 0.6.1 — 2026-09-28
 
 - `formatTiming()` joined two phases that followed each other with `∥` (ran together) when their 0.1 ms times summed
   with a floating-point error (1000.2 + 300.1 > 1300.3); it now prints `→`.
@@ -792,7 +812,7 @@ boot (and bill) long after every wait had given up.
   belonged to no phase (a 1 s wait could show `queued 0 ms`).
 - README: the timing example is the formatter's real output (durations under a second print in ms).
 
-## 0.6.0 (2026-09-28)
+## 0.6.0 — 2026-09-28
 
 ### Lifecycle calls: requested or finished
 
@@ -843,7 +863,7 @@ boot (and bill) long after every wait had given up.
   create, capture state, test instances, publish, discard).
 - `ShardfluxApiError.reason` (`details.reason`), with `KnownErrorReason`.
 
-## 0.5.0 (2026-09-26)
+## 0.5.0 — 2026-09-26
 
 First public release: `Shardflux` client, `workspaces.open/get/list/listAll`, lifecycle calls returning operations,
 `waitForOperation()`, the cell client (`exec`, `files`, `pty`, `processes`, `git`, `browser`), `workspaceTools()` with

package/README.md

@@ -1,6 +1,6 @@
 # @shardflux/sdk
 
-TypeScript SDK for [Shardflux](https://shardflux.dev): cloud computers for AI agents.
+TypeScript SDK for [Shardflux](https://shardflux.dev): serverless VMs for AI agents.
 
 Open a persistent workspace by key, run commands and move files in it, suspend it when idle, resume
 it later with its disk and memory intact, and fork it. Hand your agent framework-neutral workspace
@@ -20,6 +20,34 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
 
+## Test your integration (0.16.0+)
+
+Use the same client calls in fast, isolated tests with `@shardflux/sdk/testing`:
+
+```ts
+import { createFakeShardflux } from '@shardflux/sdk/testing';
+
+const cloud = createFakeShardflux({
+  onExec: (request) => ({ stdout: `ran ${request.argv.join(' ')}\n`, exitCode: 0 }),
+});
+const ref = cloud.workspace('acme/test', { template: 'python-node-browser' });
+const result = await ref.exec(['python3', '-V'], { sessionId: 'version-check' });
+await ref.files.write('/home/user/result.txt', result.stdout);
+```
+
+The fake returns real SDK workspace handles, refs and errors. Workspace lifecycle calls, labels, paginated lists,
+files, command output, desktop actions and port lists use an isolated in-memory store. Command results come from
+`onExec`; returning `null` leaves a command running for `cloud.testing.completeCommand(id, sessionId, result)`.
+Unscripted commands and unimplemented routes raise `FakeUnsupportedError`.
+
+Control state with `cloud.testing.setFaults(id, { busy: true, failed: true, legacyLayout: true })`,
+`computerUnavailable`, `deleted`, `resizeRefusal` (`shrink_not_supported` or `resize_not_available`), and
+`memoryLimitMib` (a plan clamp). Set `cloud.testing.quota` to `retained_state` or `concurrent_workspaces`.
+`cloud.testing.advance(milliseconds)` drives idle deadlines; `latencyMs` and `sleep` inject request latency.
+`cloud.testing.inspect(id)` returns a copy of the raw workspace view. Each fake has its own state.
+Import the testing subpath when building tests; the main SDK entry keeps its existing runtime dependencies.
+
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -31,6 +59,29 @@ For usage, account, billing, or private support, email [shardflux@heliosone.fi](
 Report vulnerabilities through [private security reporting](https://github.com/shardfluxdev/community/security/advisories/new).
 See the [support guide](https://github.com/shardfluxdev/community/blob/main/SUPPORT.md) for all reporting options.
 
+## Reverse tunnels (0.16.0+)
+
+Forward a workspace TCP port to a service on the machine running your SDK:
+
+```ts
+const tunnel = await workspace.tunnels.reverse({ remotePort: 8081, target: 'localhost:8081' });
+try {
+  // Commands in the workspace can call http://127.0.0.1:8081.
+  console.log(tunnel.stats);
+} finally {
+  await tunnel.close();
+}
+```
+
+The guest listener binds to `127.0.0.1` by default; `bindAddress: '0.0.0.0'` selects all guest interfaces.
+The target is dialed from this machine. TCP binary data, concurrent connections and half-close are preserved;
+network reconnection resumes the tunnel while the handle is open. `closed` reports completion or failure,
+`sessionId` identifies the forwarder, and `stats` counts connections, bytes in each direction and reconnects.
+An open tunnel keeps the workspace awake; close it when callbacks are finished. For persistent workspaces, explicit suspend/resume preserves
+an open tunnel. The caller needs `exec` and `files` access.
+
+The tunnel selects a streaming transport automatically when `pty` permission is granted. Choose `transport: 'pty'` or `transport: 'exec'` in the SDK, or `--transport pty|exec` in the CLI, to select it explicitly. The handle reports `transport`.
+
 ## Install
 
 ```sh
@@ -1330,3 +1381,50 @@ const tools = workspaceTools(workspace, { prewake: true });
 // In your model stream's tool-input-start handler:
 tools.find(tool => tool.name === toolName)?.onInputStart?.();
 ```
+
+Resize controls (0.16.0+): `workspace.resize({ memoryMib: 6144, diskGib: 2, atLeast: true, wait: false })` grows
+only resources that need more capacity and returns the held server answer with its operation. `workspace.caps` exposes
+typed stored caps for later starts. A pending operation carries per-resource results once the resize has decided
+them. Fixed memory without `memory_mib` uses the template default, bounded by the plan and template.
+
+## New in 0.16.0
+
+`ref.turn(async (ref) => { ... })` (also `workspace.turn`) sends a wake hint without waiting, returns the body's result, and requests `suspendWhenIdle({ afterSeconds: 0 })` when it settles, including on error. Pass `{ afterSeconds: 60 }` to keep the workspace warm for a billed minute. Use persistent workspaces for resumable turns.
+
+Computer batches ending in `screenshot` or `zoom` return that action's image without an extra screenshot. `computer.stream()` reuses a link of the same kind with more than 60 seconds left; `{ fresh: true }` mints one, and `stopStream()` clears the cache. Gate each action with `computerToolset(ws, { beforeAction })` or `workspaceTools(ws, { computer: { beforeAction } })`: return `false`, a refusal string, or throw to answer that action with an error and skip the remaining actions. Hooks may be async.
+
+Exec results expose `exitCodePosix`: timeout 124, canceled 130, nonnegative exit code, 128 + signal, otherwise 1. `FileNotFoundError` is a `ShardfluxApiError` for cell `path_not_found` replies. The default transport honors `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and `NODE_USE_ENV_PROXY`. `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL`; `SHARDFLUX_API_URL` wins.
+
+## Embed a live viewer (0.16.0+)
+
+Watch the desktop or a port preview inside your web app. Choose 1–10 distinct HTTPS origins, then use the returned URL as the iframe source.
+
+```ts
+const { url } = await ws.computer.stream({ embed: { origins: ['https://app.example.com'] } });
+const preview = await ws.ports.link(3000, { embed: { origins: ['https://app.example.com'] } });
+```
+
+```html
+<iframe src="RETURNED_LINK_URL" title="Watch the agent" style="width:100%;height:600px;border:0"></iframe>
+```
+
+The browser session is partitioned by the top-level site. Each origin is exactly a scheme and host with an optional port, such as `https://app.example.com:8443`. The viewer permits framing by those origins; interactive viewing uses the same allowlist.
+
+## Idle deletion retention (0.16.0+)
+
+Keep one persistent workspace per conversation and delete it automatically after 14 idle days:
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'chat/42', template: 'python-node-browser', retention: { delete_after_idle_days: 14 } });
+await ws.setRetention({ delete_after_idle_days: 30 });
+await cloud.projects.setRetention((await cloud.me()).api_key!.project_id, { delete_after_idle_days: 14, labels: { app: 'chat' } });
+await ws.setRetention(null); // follow the project default
+```
+
+`cloud.workspace(key, { template, retention })` accepts the same policy. `ws.retention` shows its effective days
+and projected `delete_at`. All project selector labels must match exactly; a workspace's own policy wins.
+Calls and ongoing work postpone deletion. Without a policy, your workspace stays until you delete it.
+
+## Workspace upgrade (0.16.0+)
+
+`await ws.upgrade({ at: "now", wait: true })` keeps files, installed package files and home while cold starting on the supported current layout and base. `at: "next_resume"` schedules it for the next resume. Memory and running processes end at the cold start. Read `ws.upgradeAvailable` and `ws.upgradePending` for the target.

package/dist/account.d.ts

@@ -277,6 +277,8 @@ export declare class AccountProjectsApi {
         name: string;
         slug?: string;
     }): Promise<Project>;
+    getRetention(projectId: string): Promise<import('./client.js').ProjectRetentionPolicy | null>;
+    setRetention(projectId: string, policy: import('./client.js').ProjectRetentionPolicy | null): Promise<import('./client.js').ProjectRetentionPolicy | null>;
     get(projectId: string): Promise<Project>;
 }
 /** Every tool permission an API key can carry (pass it as `toolPermissions` for a key with every tool). */

package/dist/account.js

@@ -280,6 +280,12 @@ export class AccountProjectsApi {
     create(organizationId, params) {
         return json(this.#core, 'POST', `/v1/organizations/${enc(organizationId)}/projects`, { json: { name: params.name, ...(params.slug === undefined ? {} : { slug: params.slug }) } });
     }
+    getRetention(projectId) {
+        return json(this.#core, 'GET', `/v1/projects/${enc(projectId)}/retention`);
+    }
+    setRetention(projectId, policy) {
+        return json(this.#core, 'PUT', `/v1/projects/${enc(projectId)}/retention`, { json: policy });
+    }
     get(projectId) {
         return json(this.#core, 'GET', `/v1/projects/${enc(projectId)}`);
     }

package/dist/cell.d.ts

@@ -248,6 +248,8 @@ export declare const CAPTURE_BARRIER: unique symbol;
 export interface RunResult {
     sessionId: string;
     exitCode: number | null;
+    /** POSIX status: timeout 124, canceled 130, exit code, 128 + signal, otherwise 1. */
+    exitCodePosix: number;
     termSignal: number | null;
     timedOut: boolean;
     canceled: boolean;

package/dist/cell.js

@@ -1,4 +1,5 @@
 import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody, isWorkingQuotaRefusal } from "./errors.js";
+import { exitCodePosix } from "./exit-code.js";
 import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 import { HttpClient, defaultSleep, randomId, treeRevisionOf } from "./http.js";
 import { describeFailure, emitTo } from "./progress.js";
@@ -590,6 +591,7 @@ export class CellClient {
         return {
             sessionId,
             exitCode: session.exit_code ?? null,
+            exitCodePosix: exitCodePosix({ exitCode: session.exit_code ?? null, termSignal: session.term_signal ?? null, timedOut: session.timed_out ?? false, canceled: session.canceled ?? false }),
             termSignal: session.term_signal ?? null,
             timedOut: session.timed_out ?? false,
             canceled: session.canceled ?? false,

package/dist/client.d.ts

@@ -159,7 +159,7 @@ export type AllocationMode = 'fixed' | 'elastic';
 export type WorkspaceMemory = WorkspaceView['memory'];
 export interface Caps {
     cpu_millis?: number;
-    /** Memory in MiB; for an elastic workspace the promise (what it may grow to). */
+    /** Memory in MiB; elastic promise, or fixed size (the template default when omitted). */
     memory_mib?: number;
     disk_gib?: number;
     /**
@@ -197,6 +197,10 @@ export interface ResizeParams {
     cpuMillis?: number;
     /** Disk in GiB; disks grow only. */
     diskGib?: number;
+    /** Only grow each named numeric resource; a smaller or equal value leaves it unchanged. */
+    atLeast?: boolean;
+    /** Wait for completion (default true); false returns the held server answer without operation polling. */
+    wait?: boolean;
     /** Replays the stored response for a repeated request (default: a fresh key per call, so transport retries replay). */
     idempotencyKey?: string;
     /** Give up waiting for the resize after this long (default 300 000 ms); it continues server side. */
@@ -260,7 +264,21 @@ export interface WaitOptions {
     onProgress?: ProgressListener;
 }
 export type IdlePolicy = 'adaptive' | 'never' | `fixed:${number}`;
+export interface RetentionPolicy {
+    delete_after_idle_days: number;
+}
+export interface ProjectRetentionPolicy extends RetentionPolicy {
+    labels?: Record<string, string>;
+}
+export declare class ProjectsRetentionApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    getRetention(projectId: string): Promise<ProjectRetentionPolicy | null>;
+    setRetention(projectId: string, policy: ProjectRetentionPolicy | null): Promise<ProjectRetentionPolicy | null>;
+}
 export interface OpenParams {
+    /** Opt-in idle deletion in days (1..3650), persistent workspaces only. Omitted leaves it unchanged. */
+    retention?: RetentionPolicy;
     /** Searchable metadata; supplied labels replace the existing map. */
     labels?: Record<string, string>;
     idlePolicy?: IdlePolicy;
@@ -415,6 +433,7 @@ export declare class WorkspacesApi {
     /** null clears the override, restoring the template or platform policy. */
     /** Computer use (0.15.0+): the workspace's own switch; null follows the template. Returns the switch. */
     setComputerUse(workspaceId: string, enabled: boolean | null): Promise<ComputerUse>;
+    setRetention(workspaceId: string, policy: RetentionPolicy | null): Promise<Workspace>;
     setIdlePolicy(workspaceId: string, idlePolicy: IdlePolicy | null): Promise<Workspace>;
     list(params?: ListParams): Promise<Page<Workspace>>;
     /** Iterates every page. */
@@ -528,6 +547,10 @@ export declare class WorkspacesApi {
      * boots blank on the next resume. Returns the `reset` operation; its result names the recovery checkpoint (restorable
      * for 7 days). Errors: 409 legacy_disk_layout, not_resettable, operation_in_progress.
      */
+    /** Opt-in cold start preserving the disk; next_resume schedules it without stopping the VM. */
+    upgrade(workspaceId: string, opts?: LifecycleOptions & {
+        at?: 'now' | 'next_resume';
+    }): Promise<Operation>;
     reset(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     reset(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
     /**
@@ -583,6 +606,7 @@ export declare function fetchBillingCatalog(opts?: {
 }): Promise<BillingCatalog>;
 export declare class Shardflux {
     #private;
+    readonly projects: ProjectsRetentionApi;
     readonly workspaces: WorkspacesApi;
     readonly billing: BillingApi;
     /** Usage, allowances, estimates, grants/leases and spend (Phase 9). */

package/dist/client.js

@@ -14,6 +14,18 @@ import { AFTER_WAIT, HELD_RESUME, TRACE, runLifecycle, waitOptionsOf } from "./l
 import { Trace, combineListeners, durabilityOf, isDurable, traced } from "./progress.js";
 import { CaptureRegistry } from "./capture.js";
 import { sendFeedback } from "./feedback.js";
+export class ProjectsRetentionApi {
+    #ctx;
+    constructor(ctx) { this.#ctx = ctx; }
+    getRetention(projectId) {
+        const c = this.#ctx();
+        return c.http.json('GET', `/v1/projects/${encodeURIComponent(projectId)}/retention`, {}, c.authorization);
+    }
+    setRetention(projectId, policy) {
+        const c = this.#ctx();
+        return c.http.json('PUT', `/v1/projects/${encodeURIComponent(projectId)}/retention`, { json: policy }, c.authorization);
+    }
+}
 /**
  * The workspace a key names: the live row (deleted_at null) when there is one, since at most one live
  * workspace holds a key; otherwise the newest tombstone (ended sessions leave tombstones with the same key, and a
@@ -63,6 +75,8 @@ function resizeBody(p) {
         body.disk_gib = p.diskGib;
     if (Object.keys(body).length === 0)
         throw new TypeError('resize() needs at least one of memoryMib, memoryMibHeld, allocationMode, cpuMillis, diskGib');
+    if (p.atLeast !== undefined)
+        body.at_least = p.atLeast;
     return body;
 }
 const RESIZE_KEYS = {
@@ -164,6 +178,8 @@ export class WorkspacesApi {
             body.inputs = params.inputs;
         if (params.labels !== undefined)
             body.labels = params.labels;
+        if (params.retention !== undefined)
+            body.retention = params.retention;
         if (params.idlePolicy !== undefined)
             body.idle_policy = params.idlePolicy;
         if (params.computerUse !== undefined)
@@ -399,6 +415,9 @@ export class WorkspacesApi {
     async setComputerUse(workspaceId, enabled) {
         return this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/computer-use`, { json: { enabled } }, this.#auth);
     }
+    async setRetention(workspaceId, policy) {
+        return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/retention`, { json: policy }, this.#auth));
+    }
     async setIdlePolicy(workspaceId, idlePolicy) {
         return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/idle-policy`, { json: { idle_policy: idlePolicy } }, this.#auth));
     }
@@ -474,7 +493,7 @@ export class WorkspacesApi {
             if (kind === 'delete' || kind === 'reset')
                 this.#ctx().captures.discard(workspaceId, kind);
             return operation;
-        }, opts, { settle: kind === 'suspend' || kind === 'snapshot' });
+        }, opts, { settle: kind === 'suspend' || kind === 'snapshot' || kind === 'upgrade' });
     }
     delete(workspaceId, opts = {}) {
         return this.#op('delete', workspaceId, undefined, opts);
@@ -640,7 +659,7 @@ export class WorkspacesApi {
                     // Another lifecycle operation (a suspend, a resume, another resize) holds the workspace: the refused request
                     // changed nothing, so wait for that operation and send it again (bounded, within timeoutMs).
                     const active = e instanceof ShardfluxApiError && e.code === 'conflict' && e.reason === 'operation_in_progress' ? (e.operationId ?? e.details?.['active_operation_id']) : undefined;
-                    if (typeof active !== 'string' || attempt >= 3 || Date.now() - started >= timeoutMs)
+                    if (params.wait === false || typeof active !== 'string' || attempt >= 3 || Date.now() - started >= timeoutMs)
                         throw e;
                     trace.retry({ request: `PATCH ${path}`, attempt: attempt + 1, cause: `conflict operation_in_progress (waits for ${active})`, delayMs: 0 });
                     try {
@@ -658,6 +677,15 @@ export class WorkspacesApi {
             if (!operation || typeof operation !== 'object')
                 throw new ShardfluxProtocolError('resize: 202 response has no operation', res.status, 'api');
             trace.observe(operation);
+            if (params.wait === false) {
+                if (operation.state === 'failed' || operation.state === 'canceled')
+                    throw new OperationFailedError(operation);
+                const workspace = res.body.workspace;
+                const result = resizeResultBodyOf(operation);
+                return { workspaceId, operationId: operation.id, state: workspace?.observed_state ?? operation.state,
+                    memory: result.memory ?? null, cpu: result.cpu ?? null, disk: result.disk ?? null,
+                    caps: workspace?.caps ?? null, operation };
+            }
             let final = operation;
             if (operation.state !== 'succeeded') {
                 if (TERMINAL.has(operation.state))
@@ -685,6 +713,17 @@ export class WorkspacesApi {
         }, opts, { settle: true });
         return { operation, workspace: workspace };
     }
+    /**
+     * Resets a layered workspace to its template: every change in the workspace layer is wiped; key,
+     * id, template version, caps, secret bindings and volume attachments stay. Running: restarted on a blank layer
+     * (processes are gone; old tool tokens get 409 stale_epoch and the SDK refreshes them). Suspended: stays suspended and
+     * boots blank on the next resume. Returns the `reset` operation; its result names the recovery checkpoint (restorable
+     * for 7 days). Errors: 409 legacy_disk_layout, not_resettable, operation_in_progress.
+     */
+    /** Opt-in cold start preserving the disk; next_resume schedules it without stopping the VM. */
+    upgrade(workspaceId, opts = {}) {
+        return this.#op('upgrade', workspaceId, { at: opts.at ?? 'now' }, opts);
+    }
     reset(workspaceId, opts = {}) {
         const body = { confirm_destructive: true };
         return this.#op('reset', workspaceId, body, opts);
@@ -787,6 +826,7 @@ export async function fetchBillingCatalog(opts = {}) {
     return http.json('GET', '/v1/billing/catalog');
 }
 export class Shardflux {
+    projects;
     workspaces;
     billing;
     /** Usage, allowances, estimates, grants/leases and spend (Phase 9). */
@@ -813,6 +853,7 @@ export class Shardflux {
         const f = opts.fetch ?? defaultFetch();
         const userAgent = opts.userAgent ?? `shardflux-sdk-ts/${SDK_VERSION}`;
         const sleep = opts.sleep ?? defaultSleep;
+        this.projects = new ProjectsRetentionApi(() => this.#ctx);
         this.workspaces = new WorkspacesApi(() => this.#ctx);
         this.billing = new BillingApi(() => this.#ctx);
         this.usage = new UsageApi(() => this.#ctx);
@@ -821,7 +862,7 @@ export class Shardflux {
         this.egress = new EgressPolicyApi(() => this.#ctx);
         this.audit = new AuditApi(() => this.#ctx);
         this.volumes = new VolumesApi(() => this.#ctx);
-        const baseUrl = opts.baseUrl ?? envVar('SHARDFLUX_API_URL') ?? 'https://api.shardflux.dev';
+        const baseUrl = opts.baseUrl ?? envVar('SHARDFLUX_API_URL') ?? envVar('SHARDFLUX_BASE_URL') ?? 'https://api.shardflux.dev';
         this.#ctx = {
             http: new HttpClient({ baseUrl, fetch: f, userAgent, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 2, source: 'api', sleep, onSuccess: versionCheckHook(opts.versionCheck, baseUrl, f, userAgent) }),
             authorization: `Bearer ${apiKey}`,

package/dist/computer.d.ts

@@ -29,6 +29,10 @@ export interface ComputerActOptions {
     signal?: AbortSignal;
 }
 export interface ComputerStreamOptions {
+    /** Mint a new link even when a cached link has more than 60 seconds left. */
+    fresh?: boolean;
+    /** Frame the viewer in these HTTPS origins with a partitioned browser session (§48). */
+    embed?: import('./ports.js').PortEmbedOptions;
     /** Let the viewer use the mouse and keyboard (default false: view only, enforced in the workspace). */
     interactive?: boolean;
     /** How long the link works (60..604800 s; default 86400). */
@@ -111,6 +115,8 @@ export interface ComputerToolResult {
     is_error?: true;
 }
 export interface ComputerToolsetOptions {
+    /** Called just before each action. Return false/a refusal string, or throw, to stop the turn. */
+    beforeAction?: BeforeComputerAction;
     /** Screenshot format (default png). */
     format?: 'png' | 'jpeg';
     quality?: number;
@@ -134,10 +140,14 @@ export interface ComputerToolsetOptions {
  */
 export declare function computerToolset(workspace: {
     computer: WorkspaceComputer;
-}): {
+}, defaults?: ComputerToolsetOptions): {
     definition: {
         readonly type: "computer_toolset_20260801";
     };
     run(content: readonly unknown[], opts?: ComputerToolsetOptions): Promise<ComputerToolResult[]>;
 };
+export type BeforeComputerAction = (action: Readonly<ComputerAction>) => void | boolean | string | Promise<void | boolean | string>;
+type ComputerBatchResult = Partial<ComputerActionsResult> & Pick<ComputerActionsResult, 'results'>;
+/** No hook: one batch as before. With a hook, check immediately before each individual action runs. */
+export declare function runComputerActions(act: (actions: ComputerAction[], opts: ComputerActOptions) => Promise<ComputerActionsResult>, actions: ComputerAction[], opts: ComputerActOptions, beforeAction?: BeforeComputerAction): Promise<ComputerBatchResult>;
 export {};