@shardflux/sdk 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,10 +1,32 @@
 # Changelog
 
+## 0.14.0 — 2026-10-04 (not yet published)
+
+- 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.
+
 Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
 marked **Breaking**.
 
 ## 0.14.0 (not yet published)
 
+### Sign up from an agent
+
+Additive (API contracts §44).
+
+- `ShardfluxAccount.signup({ email?, displayName?, codexIdToken? })` (POST /v1/auth/signup): a working account and
+  its session in one call, with no browser and no email round-trip. Returns `{ account, result }`; `result.access`
+  is `verified`, `provisional` (works at once on the Free plan; the trial starts when the email is verified) or
+  `verification_required`, and `result.created` is false when a Codex proof signed in to an existing account.
+- `codexIdentityProof(opts?)` (Node): the OpenAI ID token of the Codex CLI signed in on this machine, refreshed by
+  Codex itself (`codex app-server`, `account/read {refreshToken: true}`) and read from `$CODEX_HOME/auth.json`. Only
+  the ID token is returned. Never throws: `{ ok: false, reason: 'codex_not_found' | 'not_signed_in' |
+  'api_key_login' | 'stale', message }`.
+- `account.auth.requestEmailCode()` and `account.auth.verifyEmailCode(code)` (POST /v1/auth/verify-email/code):
+  verify with a 6-digit emailed code; nothing is signed out.
+- `account.auth.stepUp({ codexIdToken })`: a step-up with the linked Codex login instead of the password.
+- New types `SignupResult`, `SignupAccess`, `EmailCodeResult`, `CodexIdentityProof`, `CodexProofOptions`,
+  `CodexProofUnavailable`.
+
 ### Workspaces working at once
 
 Additive. The plan's workspace number caps workspaces working at the same moment; stored workspaces are bounded by
@@ -25,6 +47,76 @@ Retained state.
 - Regenerated contract types: `ErrorCode` includes `quota_exceeded` for the workspace gateway; allowance
   `enforcement` adds `storage_block`, `cap_state` adds `storage_blocked`.
 
+### Inbound ports
+
+Additive. A TCP port of a processful workspace can be served at its own private HTTPS URL,
+`https://<port>-<handle>.<domain>`; a request wakes a parked or suspended workspace and is answered once it runs.
+
+- `workspace.ports` and `cloud.workspaces.ports(id)` (class `WorkspacePorts`): `expose(port)` →
+  `{port, url, createdAt, callback, created}` (`ExposePortResult`; idempotent, `created` false when it already was),
+  `list()` → `ExposedPort[]`, `close(port)`, `token(port, {ttlSeconds?})` → `{token, expiresAt, url}` (`PortToken`),
+  `link(port, {ttlSeconds?, path?})` → `{url, expiresAt}` (`PortLink`), `createCallbackUrl(port)` →
+  `{url, createdAt}` (`PortCallbackUrl`) and `revokeCallbackUrl(port)`. `expose`, `close` and `revokeCallbackUrl` are
+  retried on transient failures; minting calls are not.
+- Types `ExposedPort`, `ExposePortResult`, `PortToken`, `PortLink`, `PortCallbackUrl`, `PortTokenOptions`,
+  `PortLinkOptions` and the raw API shapes `PortView`, `PortTokenResponse`, `PortLinkResponse`, `PortCallbackResponse`
+  (regenerated contract types).
+- `KnownErrorReason` adds `inbound_ports_not_available`, `port_not_exposed` and `port_limit`.
+
+### Memory across platform upgrades
+
+Additive. A resume keeps the workspace's memory and running processes across host kernel, CPU generation and
+Firecracker upgrades of the platform.
+
+- `ColdBootReason` gains `runtime_retired`, and `COLD_BOOT_REASONS` lists every reason this version knows
+  (`runtime_changed`, `host_lost`, `runtime_retired`). `runtime_retired`: the runtime the workspace was suspended on
+  was retired after an announced window; the resume booted the saved disk (`resumePath` `cold_boot`,
+  `memoryRestored` false). A reason this version does not know is still passed through as a string.
+
+### Resize a workspace
+
+Additive. Change the memory, CPU and disk of any workspace, running or suspended, fixed or elastic, without a restart
+or a fork.
+
+- `workspace.resize({ memoryMib, memoryMibHeld, allocationMode, cpuMillis, diskGib })` and
+  `cloud.workspaces.resize(id, params)` send `PATCH /v1/workspaces/{id}/caps` with the given caps (snake_case, at
+  least one; none throws `TypeError` before any request), an `Idempotency-Key` (`idempotencyKey`, default a fresh key
+  per call, so a retried request replays) and `Prefer: wait` (up to 20 s, within `timeoutMs`). They resolve once the
+  resize has finished: a resize the server answers with `202` is waited for like any operation (`timeoutMs`, default
+  300 000 ms; `signal`; `onProgress`, action `resize`). A resize that meets another lifecycle operation (409
+  `operation_in_progress`) waits for it and is sent again with the same `Idempotency-Key`, within `timeoutMs`. A failed
+  resize is its error: `ShardfluxApiError` 409 with `operationId` (reason `resize_failed`, ...) when the server held
+  the request until then, `OperationFailedError` when the SDK waited for the operation.
+- `ResizeResult`: `workspaceId`, `operationId`, `state`, `caps` (the stored caps every later start uses),
+  `operation` (the finished operation after a `202`, else null) and, for each resource the request named,
+  `memory` / `cpu` / `disk` (`ResizeMemory`, `ResizeCpu`, `ResizeDisk`): `applies_at` (`now`, `resume` or
+  `next_start`), `requested_*`, `target_*`, `previous_*`, `applied_*`, `limit_reason` (`plan`, `template`,
+  `host_capacity`, `shrink_stalled`) and `reason` (`suspended`, `stopped`, `boot_vcpus`, `region`, `below_base`,
+  `legacy_layout`); memory adds `allocation_mode`, `held_mib` and `converged`. Types `ResizeParams`,
+  `ResizeAppliesAt`, `ResizeLimitReason` and `ResizeDeferReason` are exported.
+- The handle refreshes its view after a resize. A file-first workspace is refused locally with
+  `NotSupportedForModeError`.
+- A finished operation's `result` (the cell's) is returned in the held answer's shape: each named resource with its
+  documented keys, a key left out taken from the operation's input or null, other keys dropped.
+- `KnownErrorReason` adds `resize_not_available` (409 `conflict`), `resize_failed` (409 `conflict`, a failed resize)
+  and `shrink_not_supported` (422 `validation_failed`, `details.current_disk_gib`). `LifecycleAction` adds `resize`.
+
+### Memory hint for commands
+
+Additive. `RunOptions.resourceHint` (`'auto' | 'light' | 'heavy'`, type `ResourceHint`) on `exec.run()`, and
+`resource_hint` on `exec.start()` requests: `heavy` gives an elastic workspace its memory before the command starts,
+`light` starts it at once, `auto` (the default) decides from the command. Sent only when set, so other requests are
+unchanged. The processful `exec` agent tool takes `resource_hint` with the same values.
+
+### Elastic by default
+
+With elastic-by-default enabled for the organization, an open of a new processful workspace without
+`caps.allocation_mode` is elastic: it holds the memory its commands use and grows up to `memory_mib` (when not given,
+the plan's largest workspace, bounded by the template); billing counts the memory it holds. `allocation_mode: 'fixed'`
+gives a static allocation of `memory_mib`. Reopening an existing workspace with caps that omit `allocation_mode` then
+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)
 
 Patch, additive: the transport, a documented value, a fix for tool calls across a move and self-healing workspaces.

package/README.md

@@ -360,10 +360,11 @@ lookups by key.
 
 ### Elastic memory (0.13.0+)
 
-Promise a workspace a lot of memory while it holds only what it uses. An elastic workspace idles at its held floor
-(`memory_mib_held`, default 1024) and grows before each command starts, so compilers, test runners and V8 size
-themselves from the memory they will actually get. After 30 s without work it shrinks back. The layout takes effect at
-the workspace's next start.
+A workspace can hold only the memory its commands use and grow up to `memory_mib` when they need more; billing counts
+the memory it holds. An elastic workspace idles at its held floor (`memory_mib_held`, default 1024) and shrinks back
+after 30 s without work. Package installs, test runners, compilers, type checkers and bundlers get their memory before
+they start, so they size their heaps and workers from what they will actually get; everything else starts at once and
+the workspace grows while it runs.
 
 ```ts
 const ws = await cloud.workspaces.open({
@@ -375,10 +376,32 @@ ws.memory;           // { allocation_mode: 'elastic', promised_mib: 8192, held_m
 
 const r = await ws.cell().exec.run(['npm', 'test']);
 r.memoryGrow;        // { outcome: 'delivered', from_mib: 1024, want_mib: 4096, got_mib: 4096, deliver_ms: 175 }
+
+await ws.cell().exec.run(['python3', 'train.py'], { resourceHint: 'heavy' });   // 0.14.0+: memory first, then the command
+```
+
+`resourceHint` (0.14.0+) is `'auto'` (the default: decided from the command), `'heavy'` or `'light'`; the exec agent
+tool takes `resource_hint`. `allocation_mode: 'fixed'` gives a static allocation of `memory_mib`. Send
+`allocation_mode` with every `caps` you pass to keep the mode you chose; an open without `caps` keeps the stored
+layout, and a fork without `caps` inherits its source's. The exec agent tool adds `memory_grow` to its result when the
+command's start grew the workspace.
+
+### Resize a workspace (0.14.0+)
+
+Change the memory, CPU and disk of any workspace, running or suspended, fixed or elastic, without a restart:
+
+```ts
+const r = await ws.resize({ memoryMib: 6144, diskGib: 20 });
+r.memory;   // { applies_at: 'now', previous_mib: 2048, applied_mib: 6144, converged: true, ... }
+r.disk;     // { applies_at: 'now', previous_gib: 10, applied_gib: 20, ... }
+
+await ws.resize({ allocationMode: 'elastic', memoryMibHeld: 1024 });   // switch modes live
 ```
 
-Given `caps` replace the stored ones, so send `allocation_mode` with every `caps` you pass; an open without `caps`
-keeps the stored layout. The exec agent tool adds `memory_grow` to its result when the command's start grew the VM.
+Memory changes live, and disks grow online. A suspended workspace gets its new size when it resumes, before its first
+call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. Each
+resource says when it applies (`applies_at`: `now`, `resume` or `next_start`), and the new caps are stored, so every
+later start uses them.
 
 ### Burst execution (0.13.0+)
 
@@ -398,6 +421,36 @@ workspace's own processes resume where they were. A burst is not signalled or ca
 fails (`burst_apply_failed`), retry `exec.run` with the same `sessionId` to finish the apply. The agent tools offer
 bursts when asked: `workspaceTools(ws, { burst: true })`.
 
+### Inbound ports (0.14.0+)
+
+Serve a port of the workspace at its own HTTPS URL: a preview of the app your agent is building, a webhook receiver,
+an OAuth redirect, a live view. A request wakes a parked or suspended workspace and is answered once it runs, so the
+workspace can sleep between visits. Every port is private: a request carries a port token, a signed link's browser
+session, or arrives on the port's callback URL.
+
+```ts
+await ws.cell().exec.start({ argv: ['python3', '-m', 'http.server', '3000', '--bind', '0.0.0.0'] });
+const { url } = await ws.ports.expose(3000);   // https://3000-<handle>.shardflux.app
+
+const { token } = await ws.ports.token(3000);  // { token: 'sfp_…', expiresAt, url }, 1 h by default
+await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+
+const link = await ws.ports.link(3000, { path: '/dashboard' }); // open link.url in a browser (24 h by default)
+const hook = await ws.ports.createCallbackUrl(3000);            // register `${hook.url}github` as a webhook URL
+```
+
+- The server inside the workspace listens on `0.0.0.0` (all interfaces), not only `127.0.0.1`.
+- `expose(port)` is idempotent: `created` is true when this call exposed the port; an exposed port keeps its URL, tokens,
+  links and callback URL. `list()` returns `{ port, url, createdAt, callback }` for each exposed port.
+- `token(port, { ttlSeconds })` (60-86400): send it as `Authorization: Bearer <token>`, or as `X-Shardflux-Token`
+  when the app reads `Authorization` itself. `link(port, { ttlSeconds, path })` (60-604800 s): anyone with the link can
+  open the port until it expires, so share it like a password.
+- `createCallbackUrl(port)`: a URL with a secret in its path for GitHub, Slack, Stripe or an OAuth provider; a request
+  to `<url><rest>` reaches `/<rest>` without a token header. Its secret is shown only once; calling it again replaces
+  it, `revokeCallbackUrl(port)` revokes it.
+- `close(port)` stops the port's tokens, links and callback URL at once (also when the port is exposed again).
+- By id, without reading the workspace: `cloud.workspaces.ports(id)`.
+
 ### Timing and progress (0.6.0+)
 
 Every open, wake and waited lifecycle call is traced. `workspace.lastTiming` (and `err.timing` when the call fails)
@@ -849,7 +902,7 @@ await workspace.cell().exec.run(['python3', 'agent.py']);          // sees $OPEN
 
 `ShardfluxAccount` does what a person does in the web app, with a user session instead of an API key: sign up, sign
 in (with MFA), organizations, projects, API keys, members, invitations, billing, audit, data export and account
-deletion. Two steps stay human: opening the verification email, and paying in Stripe Checkout.
+deletion. Paying in Stripe Checkout is the step a person does.
 
 ```ts
 import { Shardflux, ShardfluxAccount } from '@shardflux/sdk';
@@ -887,6 +940,37 @@ const cloud = new Shardflux({ apiKey: secret });
 - `parseEmailToken(input)` returns the `token` of a link's `#token=` fragment or `?token=` query (else the trimmed
   input), and throws for a link without one.
 
+### Sign up from an agent (0.14.0+)
+
+One call gives a working account, with no browser and no email round-trip. With the Codex CLI signed in with ChatGPT
+on the machine, the account is verified by that login and starts with its trial:
+
+```ts
+import { ShardfluxAccount, codexIdentityProof } from '@shardflux/sdk';
+
+const proof = await codexIdentityProof();            // asks Codex to refresh its login, returns the ID token
+const { account, result } = proof.ok
+  ? await ShardfluxAccount.signup({ codexIdToken: proof.idToken, onSessionToken: (s) => save(s.token) })
+  : await ShardfluxAccount.signup({ email: 'ada@example.com', onSessionToken: (s) => save(s.token) });
+// result.access: 'verified' | 'provisional' | 'verification_required'; result.created: false when it signed in
+
+if (result.access !== 'verified') {
+  await account.auth.requestEmailCode();             // a 6-digit code to the inbox (15 minutes)
+  await account.auth.verifyEmailCode('123456');      // verified; the session and keys keep working
+}
+```
+
+- `codexIdentityProof()` (Node) reads only the ID token from `$CODEX_HOME/auth.json` (default `~/.codex`), after
+  `codex app-server` refreshes it; it never throws: `{ ok: false, reason }` is `codex_not_found`, `not_signed_in`,
+  `api_key_login` or `stale`. The token proves the ChatGPT account's verified email and is not a credential to
+  OpenAI.
+- With a Codex proof, `signup` signs in to the account of that ChatGPT identity or email when there is one, else
+  creates it. `result.status` `mfa_required`: `account.auth.completeMfa({ code })`.
+- With an email only, a `provisional` account works at once on the Free plan; verifying the email starts the trial.
+  An address that has an account is 409 `conflict` (`details.reason` `email_registered`).
+- `account.auth.stepUp({ codexIdToken })` confirms a sensitive action with the linked Codex login instead of a
+  password.
+
 Upgrading a plan: a person pays at the Checkout `url`; the code waits for the subscription.
 
 ```ts
@@ -966,6 +1050,11 @@ of that base), or `invalid_path` (`details.field` `recipe.immutable[<i>]`). A bu
 `failure.code` `immutable_path_missing` (`failure.details.path` is not a directory in the built filesystem) or
 `immutable_image_too_large`.
 
+Inbound ports **(0.14.0+)**: 403 `forbidden` with `reason` `inbound_ports_not_available` (inbound ports are not enabled
+for the organization), 404 `not_found` with `reason` `port_not_exposed` (a token, link or callback URL of a port that is
+not exposed: expose it first; `details.port`), 409 `conflict` with `reason` `port_limit` (close a port first;
+`details.limit`), and 422 `validation_failed` for a port outside 1-65535 or an option out of range.
+
 ## Usage and overage
 
 `cloud.usage` reads the organization's usage (API keys see organization totals and their own project's workspaces):
@@ -1110,3 +1199,13 @@ import { isWorkspaceGone, ShardfluxProtocolError } from '@shardflux/sdk';
 ### Repositories with a minimum release age
 
 Keep your repository's age policy. Pin an exact version that has aged enough; do not exempt the entire `@shardflux/*` scope. The first SDK, 0.5.0, was published September 26, 2026 at 21:13:52 UTC and reaches seven days on October 3 at that time. New versions, including 0.12.0, need their own seven days after publication. Before then no registry setting on our side can make them eligible. `npm view @shardflux/sdk time --json` shows publication times. A targeted exception for an inspected exact release is a repository-owner decision, not an installation requirement we bypass. Older versions do not contain this release's fixes.
+
+### Prepare tool input (0.14.0+)
+
+`workspaceTools(workspace, { prewake: true })` adds an optional `onInputStart()` callback to tools that need the VM. Call the matching tool's callback when the model starts streaming its input, then execute the tool normally once its arguments are complete. The callback returns immediately and prepares the workspace in the background. Without `prewake`, tools have no input-start callback. File reads served from disk and file-first tools have no callback.
+
+```ts
+const tools = workspaceTools(workspace, { prewake: true });
+// In your model stream's tool-input-start handler:
+tools.find(tool => tool.name === toolName)?.onInputStart?.();
+```

package/dist/account.d.ts

@@ -2,6 +2,8 @@
  * The account plane with a user session (0.9.0): what a person does in the web app, from code.
  *
  *   // Before a session exists (no token needed)
+ *   const proof = await codexIdentityProof();                       // 0.14.0+: this machine's Codex login
+ *   const { account } = await ShardfluxAccount.signup(proof.ok ? { codexIdToken: proof.idToken } : { email });
  *   await ShardfluxAccount.register({ email, password, displayName });
  *   await ShardfluxAccount.verifyEmail(linkFromTheEmail);
  *   const { account, result } = await ShardfluxAccount.login({ email, password, onSessionToken: (s) => save(s.token) });
@@ -44,6 +46,14 @@ type Ok<Op> = Op extends {
     [K in keyof R]: K extends 200 | 201 | 202 ? JsonOf<R[K]> : never;
 }[keyof R] : never;
 export type RegisterResult = Ok<operations['postV1AuthRegister']>;
+/**
+ * Agent signup (0.14.0+): `status`, `created`, `access` (`verified` | `provisional` | `verification_required`), the
+ * user, and the new `session_token`.
+ */
+export type SignupResult = Ok<operations['postV1AuthSignup']>;
+export type SignupAccess = SignupResult['access'];
+/** POST /v1/auth/verify-email/code: `{ status: 'accepted' }` (code sent) or `{ status: 'verified' }`. */
+export type EmailCodeResult = Ok<operations['postV1AuthVerifyEmailCode']>;
 export type VerifyEmailResult = Ok<operations['postV1AuthVerifyEmail']>;
 export type PasswordResetRequestResult = Ok<operations['postV1AuthPasswordResetRequest']>;
 export type PasswordResetConfirmResult = Ok<operations['postV1AuthPasswordResetConfirm']>;
@@ -178,11 +188,15 @@ export declare class AccountAuthApi {
     sessions(): Promise<AuthSessionPage>;
     revokeSession(sessionId: string): Promise<void>;
     /**
-     * Confirms the password (and a code when MFA is on) for the calls that need a recent check (403
+     * Confirms the password, or a Codex identity proof of the Codex login linked to the account (0.14.0+:
+     * `codexIdToken` from codexIdentityProof()), plus a code when MFA is on, for the calls that need a recent check (403
      * `step_up_required`). Rotates the session token.
      */
-    stepUp(params: {
+    stepUp(params: ({
         password: string;
+    } | {
+        codexIdToken: string;
+    }) & {
         code?: string;
         recoveryCode?: string;
     }): Promise<StepUpResult>;
@@ -195,6 +209,13 @@ export declare class AccountAuthApi {
     changeEmail(newEmail: string): Promise<EmailChangeResult>;
     /** Sends the verification email again. */
     resendVerification(): Promise<ResendVerificationResult>;
+    /**
+     * Emails a 6-digit verification code to the account address (0.14.0+; valid 15 minutes, once). Confirm it with
+     * verifyEmailCode: nothing is signed out, and an account from `signup` gets its trial.
+     */
+    requestEmailCode(): Promise<EmailCodeResult>;
+    /** Verifies the email with the 6-digit code (0.14.0+). A wrong code is 400 `token_invalid`; 5 wrong attempts end it. */
+    verifyEmailCode(code: string): Promise<EmailCodeResult>;
 }
 export declare class OrganizationExportsApi {
     #private;
@@ -458,6 +479,24 @@ export declare class ShardfluxAccount {
     sendFeedback(params: AccountFeedbackParams): Promise<FeedbackReceipt>;
     /** Raw access to any /v1 endpoint with the session's authentication and the SDK's error handling. */
     request<T>(method: string, path: string, init?: RequestOptions): Promise<T>;
+    /**
+     * Signs up from an agent with no browser or email round-trip (0.14.0+); `account` holds the new session.
+     *
+     * - `codexIdToken` (from codexIdentityProof()): the email is verified by the Codex login's ChatGPT account. Signs in
+     *   to the account of that identity or email when there is one (`result.created` false), else creates it.
+     *   `result.status` `mfa_required`: complete with `account.auth.completeMfa({ code })`.
+     * - `email` only: creates an unverified account. `result.access` `provisional`: it works now on the default plan,
+     *   and the trial comes with `auth.requestEmailCode()` + `auth.verifyEmailCode(code)`; `verification_required`:
+     *   verify first. An address that has an account is 409 `conflict` (`details.reason` `email_registered`).
+     */
+    static signup(params: PreSession<{
+        email?: string;
+        displayName?: string;
+        codexIdToken?: string;
+    }>): Promise<{
+        account: ShardfluxAccount;
+        result: SignupResult;
+    }>;
     /** Creates an account; a verification link is emailed (`{ status: 'accepted' }` also when the email is taken). */
     static register(params: PreSession<{
         email: string;

package/dist/account.js

@@ -149,11 +149,12 @@ export class AccountAuthApi {
         return json(this.#core, 'DELETE', `/v1/auth/sessions/${enc(sessionId)}`);
     }
     /**
-     * Confirms the password (and a code when MFA is on) for the calls that need a recent check (403
+     * Confirms the password, or a Codex identity proof of the Codex login linked to the account (0.14.0+:
+     * `codexIdToken` from codexIdentityProof()), plus a code when MFA is on, for the calls that need a recent check (403
      * `step_up_required`). Rotates the session token.
      */
     async stepUp(params) {
-        const body = { password: params.password };
+        const body = 'password' in params ? { password: params.password } : { codex_id_token: params.codexIdToken };
         if (params.code !== undefined)
             body.code = params.code;
         if (params.recoveryCode !== undefined)
@@ -173,6 +174,17 @@ export class AccountAuthApi {
     resendVerification() {
         return json(this.#core, 'POST', '/v1/auth/verify-email/resend');
     }
+    /**
+     * Emails a 6-digit verification code to the account address (0.14.0+; valid 15 minutes, once). Confirm it with
+     * verifyEmailCode: nothing is signed out, and an account from `signup` gets its trial.
+     */
+    requestEmailCode() {
+        return json(this.#core, 'POST', '/v1/auth/verify-email/code', { json: {} });
+    }
+    /** Verifies the email with the 6-digit code (0.14.0+). A wrong code is 400 `token_invalid`; 5 wrong attempts end it. */
+    verifyEmailCode(code) {
+        return json(this.#core, 'POST', '/v1/auth/verify-email/code', { json: { code: code.replace(/\s+/g, '') } });
+    }
 }
 export class OrganizationExportsApi {
     #core;
@@ -603,6 +615,28 @@ export class ShardfluxAccount {
         const account = ShardfluxAccount.#client(opts);
         return account.#ctx.http.json('POST', path, body === undefined ? {} : { json: body });
     }
+    /**
+     * Signs up from an agent with no browser or email round-trip (0.14.0+); `account` holds the new session.
+     *
+     * - `codexIdToken` (from codexIdentityProof()): the email is verified by the Codex login's ChatGPT account. Signs in
+     *   to the account of that identity or email when there is one (`result.created` false), else creates it.
+     *   `result.status` `mfa_required`: complete with `account.auth.completeMfa({ code })`.
+     * - `email` only: creates an unverified account. `result.access` `provisional`: it works now on the default plan,
+     *   and the trial comes with `auth.requestEmailCode()` + `auth.verifyEmailCode(code)`; `verification_required`:
+     *   verify first. An address that has an account is 409 `conflict` (`details.reason` `email_registered`).
+     */
+    static async signup(params) {
+        const { email, displayName, codexIdToken, ...opts } = params;
+        const account = ShardfluxAccount.#client(opts);
+        const body = {
+            ...(email === undefined ? {} : { email }),
+            ...(displayName === undefined ? {} : { display_name: displayName }),
+            ...(codexIdToken === undefined ? {} : { codex_id_token: codexIdToken }),
+        };
+        const result = await account.#ctx.http.json('POST', '/v1/auth/signup', { json: body });
+        await account.#adopt(result);
+        return { account, result };
+    }
     /** Creates an account; a verification link is emailed (`{ status: 'accepted' }` also when the email is taken). */
     static register(params) {
         const { email, password, displayName, ...opts } = params;

package/dist/cell.d.ts

@@ -30,6 +30,12 @@ import type { RequestOptions } from './http.js';
 import type { ProgressListener } from './progress.js';
 import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
+/**
+ * How much memory a command needs at its start (0.14.0; `resource_hint` of an exec start): `heavy` grows an elastic
+ * workspace's memory before the command starts (a build, a test suite, a package install), `light` starts it at once,
+ * `auto` (the default) decides from the command. A fixed workspace has its memory already.
+ */
+export type ResourceHint = NonNullable<S['ExecStartRequest']['resource_hint']>;
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
 /**
@@ -293,6 +299,14 @@ export interface RunOptions {
     burstVcpus?: number;
     /** Burst VM memory in MiB (512-65536; default the host's, 8192, or the plan's ceiling when lower). */
     burstMemoryMib?: number;
+    /**
+     * How much memory the command needs at its start (0.14.0; sent as `resource_hint`, omitted when unset): `'heavy'`
+     * grows an elastic workspace's memory before the command starts, so a build, test suite or install sizes its heap and
+     * workers from the memory it gets; `'light'` starts it at once and the workspace grows while it runs; `'auto'` (the
+     * default) decides from the command (package installers, test runners, compilers, type checkers and bundlers are
+     * heavy). A value outside these is ShardfluxApiError 422 `validation_failed` (details.field `resource_hint`).
+     */
+    resourceHint?: ResourceHint;
 }
 /** The API error of a burst's recorded failure (`burst.error` of its session). Internal (the agent tools use it too). */
 export declare function burstFailure(e: BurstError): ShardfluxApiError;

package/dist/cell.js

@@ -444,6 +444,8 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
+            if (opts.resourceHint !== undefined)
+                req.resource_hint = opts.resourceHint;
             if (opts.burst !== undefined)
                 req.burst = opts.burst;
             if (opts.burstVcpus !== undefined)

package/dist/client.d.ts

@@ -16,6 +16,7 @@ import type { ToolName, ToolToken } from './tokens.js';
 import { Workspace } from './workspace.js';
 import { AuditApi } from './audit.js';
 import { EgressPolicyApi } from './egress.js';
+import { WorkspacePorts } from './ports.js';
 import { SecretsApi } from './secrets.js';
 import { TemplatesApi } from './templates.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
@@ -158,8 +159,9 @@ export interface Caps {
     memory_mib?: number;
     disk_gib?: number;
     /**
-     * `fixed` (default) or `elastic` (0.13.0). Given caps replace the stored ones: caps without it make
-     * the workspace fixed again; omitted caps keep the stored layout. Elastic needs the organization's entitlement, else
+     * `fixed` or `elastic` (0.13.0). Omitted: fixed, or elastic where that is the organization's default (a reopen then
+     * keeps the stored mode); the SDK never fills it in. Given caps replace the stored ones; omitted caps keep the stored
+     * layout. `workspace.resize()` (0.14.0+) changes it on a running or suspended workspace. Elastic needs the organization's entitlement, else
      * ShardfluxApiError 422 `validation_failed` reason `allocation_mode_not_available` (nothing is created or changed);
      * a file-first workspace gets `not_supported_for_mode`. A promise that does not exceed the held floor by at least
      * 512 MiB is fixed at the promise (the returned `caps.allocation_mode` says which). Takes effect at the next VM start.
@@ -176,6 +178,64 @@ export interface ForkTarget {
     caps?: Caps;
     lifetime?: WorkspaceLifetime;
 }
+/**
+ * `workspace.resize()` / `workspaces.resize()` (0.14.0): the caps to change. Give at least one; the others keep their
+ * stored values. Each value is bounded by the plan's per-workspace maximum and the template's limit, as caps at open.
+ */
+export interface ResizeParams {
+    /** Memory in MiB: the size of a fixed workspace, the maximum an elastic one may grow to. */
+    memoryMib?: number;
+    /** Elastic only: the memory the workspace holds while idle, in MiB (at most the resulting `memoryMib`). */
+    memoryMibHeld?: number;
+    /** `fixed` or `elastic`: switches the mode, live on a running workspace. */
+    allocationMode?: AllocationMode;
+    /** CPU in millicores (1000 = one vCPU). */
+    cpuMillis?: number;
+    /** Disk in GiB; disks grow only. */
+    diskGib?: number;
+    /** 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. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Progress of the resize (the held request, the operation's states, retries, `done` with the timing). */
+    onProgress?: ProgressListener;
+}
+/** The held answer of `PATCH /v1/workspaces/{id}/caps` (and a finished resize operation's `result`). */
+export type ResizeResponse = components['schemas']['ResizeResult'];
+/** The memory part of a resize result (0.14.0). `*_mib` are MiB; `applied_mib` is what is live after the call (null when no VM runs), `held_mib` the elastic floor, `converged` whether a live change reached its target. */
+export type ResizeMemory = NonNullable<ResizeResponse['memory']>;
+/** The CPU part of a resize result (0.14.0), in millicores. */
+export type ResizeCpu = NonNullable<ResizeResponse['cpu']>;
+/** The disk part of a resize result (0.14.0), in GiB. */
+export type ResizeDisk = NonNullable<ResizeResponse['disk']>;
+/** When a resized resource takes effect (0.14.0): `now`, when the suspended workspace resumes, or at its next start. */
+export type ResizeAppliesAt = ResizeMemory['applies_at'];
+/** Why less than requested applied: clamped to the plan or template bound, the host had no room, or the guest kept memory it uses. */
+export type ResizeLimitReason = NonNullable<ResizeMemory['limit_reason']>;
+/**
+ * Why a resource applies later than now: `suspended` (at resume), `stopped` (at the next start), `boot_vcpus` (more CPU
+ * than the vCPUs the workspace booted with), `region` / `below_base` / `legacy_layout` (a memory size its running VM was
+ * not booted for).
+ */
+export type ResizeDeferReason = NonNullable<ResizeMemory['reason']>;
+/**
+ * What a resize did (0.14.0), per resource the request named (the others are null): when it applies (`applies_at`),
+ * what was asked, the bounded target, the size before, what is live now, and why less or later.
+ */
+export interface ResizeResult {
+    workspaceId: string;
+    operationId: string | null;
+    /** The workspace's state the result describes: `running`, `suspended` or `stopped`. */
+    state: string;
+    memory: ResizeMemory | null;
+    cpu: ResizeCpu | null;
+    disk: ResizeDisk | null;
+    /** The workspace's stored caps after the change: every later start uses them. */
+    caps: ResizeResponse['caps'] | null;
+    /** The finished `resize` operation when the API answered before it was done (202), else null. */
+    operation: Operation | null;
+}
 export interface WaitOptions {
     /**
      * Give up waiting after this long (default 300 000 ms); the operation continues server side. A queued start
@@ -338,6 +398,8 @@ export declare class WorkspacesApi {
         agentLabel?: string;
         tools?: ToolName[];
     }): Promise<Workspace>;
+    /** The exposed ports of a workspace by id (0.14.0; the same as `workspace.ports` without reading the workspace first). */
+    ports(workspaceId: string): WorkspacePorts;
     /** Replace labels. An empty map clears them. */
     setLabels(workspaceId: string, labels: Record<string, string>): Promise<Workspace>;
     /** null clears the override, restoring the template or platform policy. */
@@ -412,6 +474,28 @@ export declare class WorkspacesApi {
      * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
      */
     cancelSuspendWhenIdle(workspaceId: string): Promise<Workspace>;
+    /**
+     * Resizes a workspace (0.14.0; `PATCH /v1/workspaces/{id}/caps`): any of memory, the held floor, the allocation mode,
+     * CPU and disk, of a running, suspended or stopped workspace, fixed or elastic, without a restart or a fork. The new
+     * caps are stored, so every later start uses them. Resolves once the resize has finished, with what applied per
+     * resource: `now` (live), `resume` (a suspended workspace gets it when it resumes, before its first call) or
+     * `next_start` (with the `reason`). The request is held by the server while the resize runs; a resize still running
+     * after the hold is waited for like any operation.
+     *
+     * A resize that meets another lifecycle operation (409 `operation_in_progress`: a suspend, a resume, another resize)
+     * waits for it and is sent again, within `timeoutMs`.
+     *
+     * Errors: ShardfluxApiError 409 `conflict` (reason `resize_not_available`, `workspace_deleted`), 422
+     * `validation_failed` (reason `shrink_not_supported` with `details.current_disk_gib`, `requires_elastic`,
+     * `exceeds_memory_mib`, `allocation_mode_not_available`, `not_supported_for_mode`). A resize that fails is its
+     * error: ShardfluxApiError with `operationId` when the server held the request until then, OperationFailedError when
+     * the SDK waited for the operation. OperationTimeoutError after `timeoutMs`. Params without a resource throw
+     * TypeError before any request.
+     *
+     *   const r = await cloud.workspaces.resize(id, { memoryMib: 6144 });
+     *   r.memory?.applies_at; // 'now'
+     */
+    resize(workspaceId: string, params: ResizeParams): Promise<ResizeResult>;
     /**
      * Ends a session workspace now: the workspace is deleted exactly like delete() (ended_reason
      * closed) and returns the `delete` operation (input.reason session_closed); the key then opens a NEW workspace.