@shardflux/sdk 0.8.0 → 0.9.0

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

@@ -6,11 +6,12 @@ import type { ClientContext, DiskLayout, ForkTarget, Operation, WaitOptions, Wor
 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;
@@ -69,6 +102,27 @@ export declare class Workspace {
     get startup(): WorkspaceStartup | 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). */
@@ -93,10 +147,13 @@ export declare class Workspace {
     suspend(opts?: LifecycleOptions): Promise<Operation>;
     /**
      * 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 +208,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 +238,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;
 }