@shardflux/sdk 0.13.0 → 0.14.0

package/dist/codex-proof.js

@@ -0,0 +1,200 @@
+/**
+ * Codex identity proof (0.14.0+, Node): the OpenAI ID token of the Codex CLI signed in on this machine, for
+ * `ShardfluxAccount.signup({ codexIdToken })` and `auth.stepUp({ codexIdToken })`.
+ *
+ * Codex keeps the token in `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) and refreshes it only every few
+ * days, while the API accepts one issued in the last 15 minutes. So this first asks Codex to refresh its own login
+ * (`codex app-server`, JSON-RPC `account/read {"refreshToken": true}`: Codex runs its normal refresh flow and writes
+ * its own file), then reads the token. Only the ID token is returned: Codex's access and refresh tokens are never read
+ * into memory beyond parsing the file, and never leave the machine. The ID token proves the ChatGPT account's verified
+ * email; it is not a credential to OpenAI.
+ *
+ *   const proof = await codexIdentityProof();
+ *   if (proof.ok) {
+ *     const { account, result } = await ShardfluxAccount.signup({ codexIdToken: proof.idToken });
+ *   }
+ */
+function claimsOf(token) {
+    const part = token.split('.')[1];
+    if (!part)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function fresh(token, maxAgeSeconds) {
+    const c = claimsOf(token);
+    const now = Date.now() / 1000;
+    return c !== null && typeof c.iat === 'number' && typeof c.exp === 'number' && now - c.iat <= maxAgeSeconds && c.exp - now > 60;
+}
+async function codexHome(env) {
+    const path = await import('node:path');
+    const os = await import('node:os');
+    const set = env.CODEX_HOME?.trim();
+    return set ? path.resolve(set) : path.join(env.HOME?.trim() || os.homedir(), '.codex');
+}
+/** `tokens.id_token` of auth.json, or null (missing file, other shape, API-key login). */
+async function readIdToken(home) {
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(home, 'auth.json'), 'utf8');
+    }
+    catch {
+        return { token: null, apiKeyOnly: false, exists: false };
+    }
+    try {
+        const doc = JSON.parse(raw);
+        const token = typeof doc.tokens?.id_token === 'string' && doc.tokens.id_token.length > 0 ? doc.tokens.id_token : null;
+        const apiKeyOnly = token === null && (doc.auth_mode === 'apikey' || (typeof doc.OPENAI_API_KEY === 'string' && doc.OPENAI_API_KEY.length > 0));
+        return { token, apiKeyOnly, exists: true };
+    }
+    catch {
+        return { token: null, apiKeyOnly: false, exists: true };
+    }
+}
+/**
+ * The `codex` executables to try, in PATH order (CODEX_BIN alone when set). Every match is kept, not only the first:
+ * npx puts ancestor node_modules/.bin directories first on PATH, where an unrelated npm package named `codex` can
+ * shadow the Codex CLI. Distinct by real path.
+ */
+async function codexCandidates(env) {
+    const set = env.CODEX_BIN?.trim();
+    if (set)
+        return [set];
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const names = process.platform === 'win32' ? ['codex.exe', 'codex.cmd', 'codex'] : ['codex'];
+    const out = [];
+    const seen = new Set();
+    for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const file = path.join(dir, name);
+            try {
+                await fs.access(file, fs.constants.X_OK);
+                const real = await fs.realpath(file);
+                if (seen.has(real))
+                    continue;
+                seen.add(real);
+                out.push(file);
+            }
+            catch {
+                // not there, or not executable
+            }
+        }
+    }
+    return out;
+}
+/** Asks Codex to refresh its own login through the app server of the first candidate that speaks its protocol. */
+async function refreshViaAppServer(env, opts) {
+    const candidates = await codexCandidates(env);
+    if (candidates.length === 0)
+        return 'not_found';
+    let outcome = 'not_found';
+    for (const bin of candidates.slice(0, 4)) {
+        outcome = await appServerRefresh(bin, env, opts);
+        if (outcome !== 'failed' && outcome !== 'not_found')
+            return outcome;
+    }
+    return outcome;
+}
+async function appServerRefresh(bin, env, opts) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        let settled = false;
+        let buffer = '';
+        const child = spawn(bin, ['app-server'], { stdio: ['pipe', 'pipe', 'ignore'], env, windowsHide: true });
+        const done = (o) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.stdin.end();
+            child.kill();
+            resolve(o);
+        };
+        const timer = setTimeout(() => done('failed'), opts.timeoutMs);
+        const send = (msg) => child.stdin.write(`${JSON.stringify(msg)}\n`);
+        child.on('error', (err) => done(err.code === 'ENOENT' ? 'not_found' : 'failed'));
+        child.on('exit', () => done('failed'));
+        child.stdin.on('error', () => done('failed'));
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            buffer += chunk;
+            let nl;
+            while ((nl = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, nl).trim();
+                buffer = buffer.slice(nl + 1);
+                if (line.length === 0)
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.id === 1) {
+                    if (msg.error !== undefined)
+                        return done('failed');
+                    send({ jsonrpc: '2.0', method: 'initialized' });
+                    send({ jsonrpc: '2.0', id: 2, method: 'account/read', params: { refreshToken: true } });
+                }
+                else if (msg.id === 2) {
+                    if (msg.error !== undefined)
+                        return done('failed');
+                    const type = msg.result?.account?.type;
+                    return done(type === 'chatgpt' ? 'refreshed' : type === 'apiKey' ? 'api_key_login' : type === undefined || type === null ? 'not_signed_in' : 'failed');
+                }
+            }
+        });
+        send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { clientInfo: { name: opts.clientName, version: opts.clientVersion } } });
+    });
+}
+/**
+ * The ID token of this machine's Codex login, refreshed by Codex when needed. Never throws: `{ ok: false, reason }`
+ * says why there is none (sign up with an email address instead).
+ */
+export async function codexIdentityProof(opts = {}) {
+    const env = opts.env ?? process.env;
+    const maxAge = opts.maxAgeSeconds ?? 600;
+    const home = await codexHome(env);
+    let outcome = 'skipped';
+    // Always refresh first: each refresh mints a token with a new jti, and the API accepts each jti once, so a token
+    // still fresh on disk may already have been used. The file alone is the fallback when Codex cannot refresh.
+    let file = await readIdToken(home);
+    let renewed = false;
+    if (opts.refresh !== false) {
+        const appServer = { timeoutMs: opts.timeoutMs ?? 15_000, clientName: opts.clientName ?? 'shardflux', clientVersion: opts.clientVersion ?? '0' };
+        const before = file.token;
+        // A refresh counts only when the token on disk changed. One retry: a refresh can fail on a transient network
+        // error, answer without renewing, or race another Codex process refreshing the same login.
+        for (let attempt = 0; attempt < 2 && !renewed; attempt++) {
+            if (attempt > 0)
+                await new Promise((r) => setTimeout(r, 500));
+            outcome = await refreshViaAppServer(env, appServer);
+            file = await readIdToken(home);
+            renewed = file.token !== null && file.token !== before && fresh(file.token, maxAge);
+            if (outcome === 'api_key_login' || outcome === 'not_signed_in' || outcome === 'not_found')
+                break;
+        }
+    }
+    if (file.token !== null && fresh(file.token, maxAge)) {
+        const email = claimsOf(file.token)?.email;
+        return { ok: true, idToken: file.token, email: typeof email === 'string' ? email : null, refreshed: renewed };
+    }
+    if (outcome === 'api_key_login' || file.apiKeyOnly)
+        return { ok: false, reason: 'api_key_login', message: 'Codex is signed in with an API key, which carries no identity. Sign in with ChatGPT (codex login), or sign up with an email address.' };
+    if (outcome === 'not_signed_in' || (file.token === null && outcome !== 'not_found')) {
+        return { ok: false, reason: 'not_signed_in', message: 'Codex is not signed in with ChatGPT on this machine (codex login), or keeps its login in the OS keyring. Sign up with an email address instead.' };
+    }
+    if (outcome === 'not_found' && !file.exists)
+        return { ok: false, reason: 'codex_not_found', message: 'The Codex CLI is not installed (or not on PATH). Sign up with an email address instead.' };
+    return { ok: false, reason: 'stale', message: 'The Codex login on this machine could not be refreshed. Run any codex command (or codex login), then try again.' };
+}

package/dist/errors.d.ts

@@ -70,8 +70,19 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * 409 conflict read_only_path (a files write under an immutable path, from the cell gateway). The reason
  * `update_policy_not_available` is gone with the update policy. A build that fails on them carries `failure.code`
  * immutable_path_missing (details.path) or immutable_image_too_large.
+ * Host loss (0.13.1; the machine a workspace ran on failed, and the workspace restores itself on its next use): the
+ * operation error `workspace_storage_unavailable` carries details.reason host_lost (and details.workspace_state
+ * `suspended`) when neither the workspace's disk nor a checkpoint could be restored (not retryable). A fork or snapshot
+ * of such a workspace before its resume fails with the operation error `resume_required` (details.reason host_lost;
+ * not retryable): resume the workspace first.
+ * Workspaces working at once (0.14.0): the cell gateway answers a tool call that finds every working slot of the plan
+ * taken with 429 `quota_exceeded` (retryable, Retry-After; details.limit `concurrent_workspaces`, limit_value, current,
+ * retry_after_seconds); the call did not run and the SDK retries it like any transient refusal. The API's 403
+ * `quota_exceeded` (not retryable) names details.limit `concurrent_workspaces` on open, resume and fork, and
+ * `retained_state` (details.limit_value and details.current in GiB) when opening a new key or forking with the plan's
+ * Retained state used up. `details.limit` is not a reason: these are not in this union.
  */
-export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch' | 'allocation_mode_not_available' | 'requires_elastic' | 'exceeds_memory_mib' | 'burst_mode_not_supported' | 'burst_not_supported' | 'burst_size_exceeds_plan' | 'not_available' | 'shared_volumes' | 'fence_not_drained' | 'apply_pending' | 'park_failed' | 'workspace_resumed' | 'interrupted' | 'burst_lost' | 'disk_full' | 'apply_failed' | 'reverted' | 'revert_failed' | 'immutable_path_removed' | 'immutable_paths_unsupported_base' | 'read_only_path';
+export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch' | 'allocation_mode_not_available' | 'requires_elastic' | 'exceeds_memory_mib' | 'burst_mode_not_supported' | 'burst_not_supported' | 'burst_size_exceeds_plan' | 'not_available' | 'shared_volumes' | 'fence_not_drained' | 'apply_pending' | 'park_failed' | 'workspace_resumed' | 'interrupted' | 'burst_lost' | 'disk_full' | 'apply_failed' | 'reverted' | 'revert_failed' | 'immutable_path_removed' | 'immutable_paths_unsupported_base' | 'read_only_path' | 'resize_not_available' | 'shrink_not_supported' | 'resize_failed' | 'host_lost' | 'inbound_ports_not_available' | 'port_not_exposed' | 'port_limit';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
@@ -106,6 +117,13 @@ export declare class ShardfluxApiError extends Error {
     readonly treeRevision: number | undefined;
     constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number);
 }
+/**
+ * The cell gateway's working-at-once refusal (0.14.0+): 429 `quota_exceeded`, retryable, with Retry-After. The gateway
+ * refuses the call at admission, before the workspace is touched, so nothing ran and any request (exec start, stdin,
+ * PTY create, keepalive included) may be sent again. The API's 403 `quota_exceeded` is a different refusal (not
+ * retryable) and never matches.
+ */
+export declare function isWorkingQuotaRefusal(err: unknown): err is ShardfluxApiError;
 /** processful (the default: one VM keeps processes, memory and files) or file_first. */
 export type WorkspaceMode = AppComponents['schemas']['WorkspaceMode'];
 /**
@@ -197,6 +215,7 @@ export declare class OperationTimeoutError extends Error {
  * The operation reached `failed` or `canceled`. A suspend-when-idle that found the workspace active (a tool call after
  * the request, an attached stream) is `canceled` with `errorCode` `workspace_active` (`workspaceActive` true, 0.12.0+):
  * nothing changed and the workspace keeps running. `waitUntilReady()` and `wake()` treat it as running, not as a failure.
+ * `resume_required` (0.13.1+): a fork or snapshot of a workspace whose machine failed; resume it, then call again.
  */
 export declare class OperationFailedError extends Error {
     readonly operation: Operation;

package/dist/errors.js

@@ -40,6 +40,15 @@ export class ShardfluxApiError extends Error {
         this.reason = typeof reason === 'string' ? reason : undefined;
     }
 }
+/**
+ * The cell gateway's working-at-once refusal (0.14.0+): 429 `quota_exceeded`, retryable, with Retry-After. The gateway
+ * refuses the call at admission, before the workspace is touched, so nothing ran and any request (exec start, stdin,
+ * PTY create, keepalive included) may be sent again. The API's 403 `quota_exceeded` is a different refusal (not
+ * retryable) and never matches.
+ */
+export function isWorkingQuotaRefusal(err) {
+    return err instanceof ShardfluxApiError && err.source === 'cell' && err.status === 429 && err.code === 'quota_exceeded' && err.retryable;
+}
 /**
  * The call does not exist for the workspace's mode: 409 `conflict` with details.reason
  * `not_supported_for_mode`, `details.mode` (the workspace's mode) and `details.operation`. File-first workspaces have no
@@ -187,6 +196,7 @@ export class OperationTimeoutError extends Error {
  * The operation reached `failed` or `canceled`. A suspend-when-idle that found the workspace active (a tool call after
  * the request, an attached stream) is `canceled` with `errorCode` `workspace_active` (`workspaceActive` true, 0.12.0+):
  * nothing changed and the workspace keeps running. `waitUntilReady()` and `wake()` treat it as running, not as a failure.
+ * `resume_required` (0.13.1+): a fork or snapshot of a workspace whose machine failed; resume it, then call again.
  */
 export class OperationFailedError extends Error {
     operation;