@shardflux/sdk 0.7.0 → 0.9.0

package/dist/tools.js

@@ -11,6 +11,7 @@
  * providers' formats and executeToolCall dispatches a model's tool call.
  */
 import { CAPTURE_BARRIER } from "./cell.js";
+import { newExecutionId } from "./executions.js";
 export class ToolArgumentError extends Error {
     tool;
     issues;
@@ -51,6 +52,8 @@ export function validateArgs(schema, value, path = '$') {
             issues.push(`${path} is too short`);
         if (schema.maxLength !== undefined && value.length > schema.maxLength)
             issues.push(`${path} is too long`);
+        if (schema.pattern !== undefined && !new RegExp(schema.pattern, 'u').test(value))
+            issues.push(`${path} must match ${schema.pattern}`);
     }
     else if (t === 'integer' || t === 'number') {
         if (typeof value !== 'number' || !Number.isFinite(value) || (t === 'integer' && !Number.isInteger(value)))
@@ -79,6 +82,12 @@ export function validateArgs(schema, value, path = '$') {
     return issues;
 }
 const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
+/** The tool permissions whose tools work on a file-first workspace (contracts §29.8): files and executions. */
+const FILE_FIRST_TOOLS = ['exec', 'files'];
+/** Changed paths returned to the model per execution (the rest is flagged `changed_truncated`). */
+const MAX_CHANGED_LISTED = 200;
+/** Tools served from a sleeping workspace's disk without waking it (contracts §26.4): the runner sends no hint. */
+const DISK_READS = new Set(['read_file', 'list_files', 'search_files']);
 const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
 const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
 const signal = { type: 'string', description: 'Signal name such as SIGTERM, SIGINT or SIGKILL.', minLength: 2, maxLength: 12 };
@@ -97,29 +106,70 @@ export function workspaceTools(workspace, opts = {}) {
     });
     const max = opts.maxOutputBytes ?? 65_536;
     const prefix = opts.prefix ?? '';
-    const allowed = new Set(opts.tools ?? workspace.grantedTools ?? ALL);
+    // A file-first workspace (contracts §29) has files and executions only: no processes, terminals, version control or
+    // browser between calls, so those tools are not offered, and exec runs each command as an execution.
+    const fileFirst = (opts.mode ?? workspace.mode) === 'file_first';
+    const allowed = new Set((opts.tools ?? workspace.grantedTools ?? ALL).filter((t) => !fileFirst || FILE_FIRST_TOOLS.includes(t)));
+    const execParameters = obj({
+        command: { type: 'string', minLength: 1, maxLength: 100_000, description: 'Shell command line, e.g. "pip install -r requirements.txt && pytest -q".' },
+        cwd: { type: 'string', maxLength: 4096, description: 'Working directory (absolute).' },
+        timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
+        stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
+    }, ['command']);
     const defs = [
-        {
-            name: 'exec',
-            permission: 'exec',
-            description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
-            parameters: obj({
-                command: { type: 'string', minLength: 1, maxLength: 100_000, description: 'Shell command line, e.g. "pip install -r requirements.txt && pytest -q".' },
-                cwd: { type: 'string', maxLength: 4096, description: 'Working directory (absolute).' },
-                timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
-                stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
-            }, ['command']),
-            run: async (a, o) => {
-                const r = await cell().exec.run(['bash', '-lc', String(a.command)], {
-                    ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
-                    timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
-                    ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
-                    maxOutputBytes: max,
-                    ...(o.signal ? { signal: o.signal } : {}),
-                });
-                return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+        fileFirst
+            ? {
+                name: 'exec',
+                permission: 'exec',
+                description: 'Run a shell command (Linux; bash -lc) in a fresh VM on the workspace’s files and return its exit code, stdout, stderr, the files it changed and the new tree revision. Only files under /home/user persist between calls: processes, background jobs and changes elsewhere (e.g. system packages) do not, so install dependencies into /home/user (e.g. a virtualenv) and start servers within the same command.',
+                parameters: execParameters,
+                run: async (a, o) => {
+                    const executionId = newExecutionId();
+                    opts.onExecution?.(executionId);
+                    const r = await cell().executions.run(['bash', '-lc', String(a.command)], {
+                        executionId,
+                        ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                        timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
+                        ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                        // The cell captures what the model can be given, and flags the rest as truncated.
+                        outputLimitBytes: Math.max(1, Math.min(16_777_216, max)),
+                        ...(o.signal ? { signal: o.signal } : {}),
+                    });
+                    const out = clip(r.stdoutText, max);
+                    const err = clip(r.stderrText, max);
+                    const changed = r.changed.slice(0, MAX_CHANGED_LISTED).map((c) => ({ path: c.path, change: c.change, type: c.type }));
+                    return {
+                        exit_code: r.exitCode,
+                        term_signal: r.termSignal,
+                        timed_out: r.timedOut,
+                        stdout: out.text,
+                        stderr: err.text,
+                        truncated: r.stdoutTruncated || r.stderrTruncated || out.truncated || err.truncated,
+                        execution_id: r.executionId,
+                        state: r.state,
+                        tree_revision: r.treeRevision,
+                        changed,
+                        changed_truncated: r.changedTruncated || r.changed.length > changed.length,
+                        ...(r.error ? { error: { code: r.error.code, message: r.error.message, reason: r.errorReason } } : {}),
+                    };
+                },
+            }
+            : {
+                name: 'exec',
+                permission: 'exec',
+                description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
+                parameters: execParameters,
+                run: async (a, o) => {
+                    const r = await cell().exec.run(['bash', '-lc', String(a.command)], {
+                        ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                        timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
+                        ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                        maxOutputBytes: max,
+                        ...(o.signal ? { signal: o.signal } : {}),
+                    });
+                    return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+                },
             },
-        },
         {
             name: 'read_file',
             permission: 'files',
@@ -159,6 +209,77 @@ export function workspaceTools(workspace, opts = {}) {
                 return { entries: r.entries.map((e) => ({ name: e.name, path: e.path, type: e.type, size: e.size, modified_at: e.modified_at })), truncated: r.truncated };
             },
         },
+        {
+            name: 'search_files',
+            permission: 'files',
+            description: 'Search file contents under a directory (or in one file) in the workspace (like grep -rn) and return the matching lines with path, line and column. The pattern is literal text unless regex is true (RE2 syntax). Binary files, symbolic links and .git/node_modules directories are skipped.',
+            parameters: obj({
+                path: path('Directory (or one file) to search, absolute, e.g. /home/user/project.'),
+                pattern: { type: 'string', minLength: 1, maxLength: 1000, description: 'Text to find, or an RE2 regular expression when regex is true.' },
+                regex: { type: 'boolean', description: 'Treat pattern as an RE2 regular expression.' },
+                case_insensitive: { type: 'boolean', description: 'Ignore case.' },
+                include: { type: 'array', maxItems: 32, items: { type: 'string', minLength: 1, maxLength: 256 }, description: 'Only files matching one of these gitignore-style globs: "*.py" matches the name at any depth, "src/**/*.ts" the path relative to path.' },
+                exclude: { type: 'array', maxItems: 32, items: { type: 'string', minLength: 1, maxLength: 256 }, description: 'Skip files and directories matching these globs, e.g. "build/" (default .git and node_modules; [] searches everything).' },
+                max_matches: { type: 'integer', minimum: 1, maximum: 5000, description: 'Stop after this many matches (default 200).' },
+                context_lines: { type: 'integer', minimum: 0, maximum: 5, description: 'Lines of context to return before and after each match.' },
+            }, ['path', 'pattern']),
+            run: async (a, o) => {
+                const r = await cell().files.search(String(a.path), String(a.pattern), {
+                    ...(typeof a.regex === 'boolean' ? { regex: a.regex } : {}),
+                    ...(typeof a.case_insensitive === 'boolean' ? { caseInsensitive: a.case_insensitive } : {}),
+                    ...(Array.isArray(a.include) ? { include: a.include } : {}),
+                    ...(Array.isArray(a.exclude) ? { exclude: a.exclude } : {}),
+                    ...(typeof a.max_matches === 'number' ? { maxMatches: a.max_matches } : {}),
+                    ...(typeof a.context_lines === 'number' ? { contextLines: a.context_lines } : {}),
+                    ...(o.signal ? { signal: o.signal } : {}),
+                });
+                // Whole matches only, up to the output budget; the rest is counted.
+                const matches = [];
+                let used = 0;
+                for (const m of r.matches) {
+                    used += Buffer.byteLength(JSON.stringify(m), 'utf8');
+                    if (used > max)
+                        break;
+                    matches.push(m);
+                }
+                const omitted = r.matches.length - matches.length;
+                return { matches, truncated: r.truncated || omitted > 0, stop_reason: r.stop_reason ?? null, omitted_matches: omitted, files_scanned: r.files_scanned };
+            },
+        },
+        {
+            name: 'edit_file',
+            permission: 'files',
+            description: 'Edit a text file in the workspace by replacing exact text. Each old_text must occur exactly once in the file (include enough surrounding lines to make it unique) unless replace_all is true. The edits apply in order and atomically: all of them or none. Fails without changing anything if the file changed since expected_revision; read it again then.',
+            parameters: obj({
+                path: path(),
+                edits: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 100,
+                    description: 'Edits applied in order.',
+                    items: obj({
+                        old_text: { type: 'string', minLength: 1, maxLength: 1_048_576, description: 'Exact text to replace, including whitespace and indentation.' },
+                        new_text: { type: 'string', maxLength: 1_048_576, description: 'Replacement text (empty to delete).' },
+                        replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring exactly one.' },
+                    }, ['old_text', 'new_text']),
+                },
+                expected_revision: {
+                    type: 'string',
+                    pattern: '^[0-9a-f]{64}$',
+                    description: 'The revision your edits are based on (the revision returned by the previous edit_file of this file). Default: the file’s revision read just before editing.',
+                },
+            }, ['path', 'edits']),
+            run: async (a, o) => {
+                const c = cell();
+                const file = String(a.path);
+                // Without a revision from the model, pin the edit to the content current now, so a concurrent change between
+                // this read and the patch is refused (revision_mismatch) instead of edited blindly.
+                const expected = typeof a.expected_revision === 'string' ? a.expected_revision : (await c.files.stat(file, { revision: true })).revision;
+                const edits = a.edits.map((e) => ({ oldText: e.old_text, newText: e.new_text, ...(e.replace_all !== undefined ? { replaceAll: e.replace_all } : {}) }));
+                const r = await c.files.patch({ path: file, edits, ...(expected !== undefined ? { expectedRevision: expected } : {}) }, o.signal ? { signal: o.signal } : {});
+                return { path: r.path, revision: r.revision, previous_revision: r.previous_revision, replacements: r.replacements ?? null, bytes_written: r.bytes_written };
+            },
+        },
         {
             name: 'list_processes',
             permission: 'process',
@@ -296,6 +417,17 @@ export function workspaceTools(workspace, opts = {}) {
             const issues = validateArgs(d.parameters, args);
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
+            // Fire and forget: a parked workspace starts restoring while this call is prepared (contracts §26.6). Not for
+            // the reads a sleeping workspace serves from its disk (§26.4): the hint would wake it for nothing.
+            if (opts.hint !== false && !DISK_READS.has(d.name)) {
+                workspace
+                    .hint({
+                    ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}),
+                    ...(opts.wake !== undefined ? { wake: opts.wake } : {}),
+                    ...(opts.transitionTimeoutMs !== undefined ? { wakeTimeoutMs: opts.transitionTimeoutMs } : {}),
+                })
+                    .catch(() => undefined);
+            }
             // Read-your-writes: tool calls captured before this one are in the workspace before it runs (bounded).
             const barrier = workspace[CAPTURE_BARRIER];
             const pending = typeof barrier === 'function' ? barrier.call(workspace) : undefined;
@@ -305,7 +437,6 @@ export function workspaceTools(workspace, opts = {}) {
         },
     }));
 }
-/** OpenAI tool definitions: Chat Completions (`{type:'function', function:{...}}`) or Responses API. */
 export function toOpenAITools(tools, opts = {}) {
     return opts.api === 'responses'
         ? tools.map((t) => ({ type: 'function', name: t.name, description: t.description, parameters: t.parameters, strict: false }))
@@ -318,7 +449,9 @@ export function toAnthropicTools(tools) {
 /**
  * Runs a model's tool call: `arguments` may be the JSON string (OpenAI) or an object (Anthropic
  * `input`). Throws for unknown tools and invalid arguments (ToolArgumentError). The call's `id` / `call_id` is passed
- * to `execute` as `toolCallId` (0.7.0+), so `executeToolCall(capture.tools(tools), call)` records it.
+ * to `execute` as `toolCallId` (0.7.0+), so `executeToolCall(capture.tools(tools), call)` records it. `input` is
+ * `unknown` (0.8.0+), as in the Anthropic SDK's `ToolUseBlock`, so a tool_use block is passed as it is; `execute`
+ * validates it.
  */
 export async function executeToolCall(tools, call, options = {}) {
     const tool = tools.find((t) => t.name === call.name);

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();
+}