@shardflux/cli 0.7.0 → 0.8.1

package/dist/main.js

@@ -76,9 +76,17 @@ function hintFor(info, cred, file) {
         return 'this API has no billing configured: plans cannot be bought here';
     if (info.code === 'allowance_exhausted')
         return allowanceHint(info);
+    if (info.code === 'quota_exceeded') {
+        const quota = quotaHint(info);
+        if (quota)
+            return quota;
+    }
     const policyHint = spendPolicyHint(info);
     if (policyHint)
         return policyHint;
+    const immutable = immutableHint(info);
+    if (immutable)
+        return immutable;
     // File patches: what to do about each refusal. details.index is the 0-based edit (--old) index.
     const reason = info.details?.reason;
     const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
@@ -132,6 +140,21 @@ function allowanceHint(info) {
             return undefined;
     }
 }
+/**
+ * quota_exceeded (0.9.0): the cell gateway's 429 when every workspace the plan allows to work at once is busy (the SDK
+ * already retried it after Retry-After), and the API's 403 when the plan's Retained state is used up (new keys and
+ * forks are refused). Other limits keep the API's message alone.
+ */
+function quotaHint(info) {
+    const limit = info.details?.limit;
+    if (limit === 'concurrent_workspaces' && info.status === 429) {
+        const s = info.retry_after_seconds;
+        return `every workspace your plan allows to work at once is busy and the call did not run (it was already retried); retry ${typeof s === 'number' ? `in ${s} s` : 'in a few seconds'}, or upgrade: shard billing plans`;
+    }
+    if (limit === 'retained_state')
+        return 'delete workspaces you no longer need (shard ws delete <key> --yes), or upgrade: shard billing plans';
+    return undefined;
+}
 /** Dollars for a hint: `9` for 900 minor units, `9.50` for 950. */
 const dollars = (minor) => (typeof minor === 'number' ? (minor % 100 === 0 ? String(minor / 100) : (minor / 100).toFixed(2)) : undefined);
 /**
@@ -166,6 +189,35 @@ function spendPolicyHint(info) {
             return undefined;
     }
 }
+/**
+ * Immutable paths (0.8.0; contracts §34): the build refusals (422 validation_failed per details.reason, with the paths
+ * and base the API names) and a files write under an immutable path (409 conflict read_only_path from the cell).
+ */
+function immutableHint(info) {
+    const d = info.details ?? {};
+    const reason = reasonOf(info);
+    const list = (v) => (Array.isArray(v) ? v.filter((p) => typeof p === 'string').join(', ') : '');
+    if (info.code === 'conflict' && reason === 'read_only_path') {
+        return 'this path is an immutable path of the workspace’s template: read-only, it follows the template’s newest version. Write elsewhere, or change it in the template and build a new version (shard templates get <slug> lists the immutable paths)';
+    }
+    if (info.code !== 'validation_failed')
+        return undefined;
+    if (reason === 'immutable_path_removed') {
+        const removed = list(d.removed);
+        const open = typeof d.open_version === 'number' ? `v${d.open_version}` : 'the open version';
+        return `a new version keeps every immutable path of ${open}: add ${removed || 'them'} back to immutable in template.yaml (adding paths is fine)`;
+    }
+    if (reason === 'immutable_paths_unsupported_base') {
+        if (d.field === 'recipe')
+            return 'this template has immutable paths: build it from a template.yaml (shard templates export <slug>@<version> writes the current one, shard templates build builds it)';
+        const base = typeof d.base === 'object' && d.base !== null ? d.base.name : undefined;
+        return typeof base === 'string' ? `build on a newer version of ${base} (shard templates get ${base} lists its versions)` : 'build on a newer version of the base';
+    }
+    if (reason === 'invalid_path' && typeof d.field === 'string' && d.field.startsWith('recipe.immutable[')) {
+        return `fix ${d.field.slice('recipe.'.length)} in template.yaml (the list counts from 0)`;
+    }
+    return undefined;
+}
 /**
  * 409 conflict host_feature_unavailable (0.5.0): the call is not available for this workspace. Not retryable, so the
  * hint names the fallback that works now.
@@ -258,6 +310,8 @@ const NO_NUDGE_REASONS = new Set([
     'subscription_exists',
     // A stale spend policy (If-Match): the hint names the version to retry with (0.5.1).
     'version_mismatch',
+    // A write under an immutable path (0.8.0): the hint says where to change it.
+    'read_only_path',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback
@@ -266,6 +320,9 @@ const NO_NUDGE_REASONS = new Set([
 function nudges(info, command) {
     if (command === undefined || command === 'feedback')
         return false;
+    // A plan limit whose hint names the next step (0.9.0): busy working slots, or Retained state used up.
+    if (info.code === 'quota_exceeded' && quotaHint(info) !== undefined)
+        return false;
     const reason = reasonOf(info);
     return !NO_NUDGE_CODES.has(info.code) && !(reason !== undefined && NO_NUDGE_REASONS.has(reason));
 }

package/dist/template-yaml.js

@@ -20,6 +20,9 @@ export function initTemplateYaml(base) {
 # build: what goes into the template (languages, packages, files, steps). settings: what a workspace gets when it opens.
 schema: shardflux.template-recipe.v2
 base: ${base}
+# Immutable paths: directories every workspace of this template mounts read-only from its newest published version
+# (workspaces pick up a new version at their next cold boot or resume), e.g. tools or data you ship with each version.
+# immutable: [/opt/acme]
 build:
   # Languages from the platform's table: python, node, go, rust, java (version omitted: the base's default).
   languages: []

package/dist/timing.d.ts

@@ -15,6 +15,12 @@ export declare class TimingRecorder {
      * --wait`, an `operations wait` of that resume, or a command's wake. `lostSuspendNotice()` says it.
      */
     lostSuspend: LifecycleTiming | null;
+    /**
+     * (0.8.1+) The last traced resume that restored the workspace's newest checkpoint after the machine it ran on failed
+     * (`host_lost.restored_from` `checkpoint`): a `ws resume --wait`, an `operations wait` of that resume, or a command's
+     * wake. `hostLostNotice()` says it. A restore from the disk is a cold boot (`coldBootNotice()`).
+     */
+    hostLost: LifecycleTiming | null;
     readonly listener: ProgressListener;
     /**
      * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
@@ -24,15 +30,21 @@ export declare class TimingRecorder {
 }
 /**
  * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without
- * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
+ * `--timing`: the workspace runs with its files kept, but running processes were restarted. The reason follows in
+ * parentheses: `runtime_changed`, or in words for `host_lost` (0.8.1+).
  */
 export declare function coldBootNotice(t: LifecycleTiming): string;
+/**
+ * The one-line stderr notice after a command whose resume restored the workspace's newest checkpoint after the machine
+ * it ran on failed (0.8.1+; `host_lost.restored_from` `checkpoint`): the state is as of `state_as_of`.
+ */
+export declare function hostLostNotice(t: LifecycleTiming): string;
 /**
  * The one-line stderr notice after a command whose resume restored an earlier checkpoint because the latest suspend
  * could not be kept (0.7.0+; `lost_suspend`): the state the workspace runs with is as of `state_as_of`.
  */
 export declare function lostSuspendNotice(t: LifecycleTiming): string;
-/** The notices a command's traced calls leave on stderr (cold boot, lost suspend), in that order. */
+/** The notices a command's traced calls leave on stderr (cold boot, lost suspend, host loss), in that order. */
 export declare function notices(r: TimingRecorder): string;
 /** The human form (stderr): formatTiming() of the SDK, one block. */
 export declare function timingText(t: LifecycleTiming): string;

package/dist/timing.js

@@ -6,6 +6,7 @@
  * carry no `timing` (network errors, Ctrl-C).
  */
 import { formatTiming } from '@shardflux/sdk';
+import { byteSize } from "./format.js";
 export class TimingRecorder {
     /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
     last = null;
@@ -22,6 +23,12 @@ export class TimingRecorder {
      * --wait`, an `operations wait` of that resume, or a command's wake. `lostSuspendNotice()` says it.
      */
     lostSuspend = null;
+    /**
+     * (0.8.1+) The last traced resume that restored the workspace's newest checkpoint after the machine it ran on failed
+     * (`host_lost.restored_from` `checkpoint`): a `ws resume --wait`, an `operations wait` of that resume, or a command's
+     * wake. `hostLostNotice()` says it. A restore from the disk is a cold boot (`coldBootNotice()`).
+     */
+    hostLost = null;
     listener = (e) => {
         if (e.action === 'token' || e.action === 'tool')
             return;
@@ -34,6 +41,8 @@ export class TimingRecorder {
             this.coldBoot = e.timing;
         if (e.timing.server?.lostSuspend)
             this.lostSuspend = e.timing;
+        if (e.timing.server?.hostLost?.restoredFrom === 'checkpoint')
+            this.hostLost = e.timing;
     };
     /**
      * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
@@ -48,13 +57,29 @@ export class TimingRecorder {
 function restartedProcesses(t) {
     return t.server?.resumePath === 'cold_boot' && t.server.memoryRestored === false;
 }
+/** Cold boot reasons the notice says in words (0.8.1+); any other reason is printed as the API sent it. */
+const COLD_BOOT_WORDS = {
+    host_lost: 'the machine it ran on failed',
+};
 /**
  * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without
- * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
+ * `--timing`: the workspace runs with its files kept, but running processes were restarted. The reason follows in
+ * parentheses: `runtime_changed`, or in words for `host_lost` (0.8.1+).
  */
 export function coldBootNotice(t) {
     const reason = t.server?.coldBootReason;
-    return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from its saved disk; running processes were restarted${reason ? ` (${reason})` : ''}\n`;
+    const why = reason ? (COLD_BOOT_WORDS[reason] ?? reason) : null;
+    return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from its saved disk; running processes were restarted${why ? ` (${why})` : ''}\n`;
+}
+/**
+ * The one-line stderr notice after a command whose resume restored the workspace's newest checkpoint after the machine
+ * it ran on failed (0.8.1+; `host_lost.restored_from` `checkpoint`): the state is as of `state_as_of`.
+ */
+export function hostLostNotice(t) {
+    const h = t.server?.hostLost;
+    if (h?.restoredFrom !== 'checkpoint')
+        return '';
+    return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from checkpoint ${h.restoredCheckpointId ?? '-'}${h.stateAsOf ? ` (state as of ${h.stateAsOf})` : ''} after the machine it ran on failed; changes after that time are not in it\n`;
 }
 /**
  * The one-line stderr notice after a command whose resume restored an earlier checkpoint because the latest suspend
@@ -66,9 +91,9 @@ export function lostSuspendNotice(t) {
         return '';
     return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from checkpoint ${l.restoredCheckpointId ?? '-'}${l.stateAsOf ? ` (state as of ${l.stateAsOf})` : ''}; the suspend of ${l.suspendedAt ?? l.checkpointId} was not kept${l.reason ? ` (${l.reason})` : ''}\n`;
 }
-/** The notices a command's traced calls leave on stderr (cold boot, lost suspend), in that order. */
+/** The notices a command's traced calls leave on stderr (cold boot, lost suspend, host loss), in that order. */
 export function notices(r) {
-    return `${r.coldBoot ? coldBootNotice(r.coldBoot) : ''}${r.lostSuspend ? lostSuspendNotice(r.lostSuspend) : ''}`;
+    return `${r.coldBoot ? coldBootNotice(r.coldBoot) : ''}${r.lostSuspend ? lostSuspendNotice(r.lostSuspend) : ''}${r.hostLost ? hostLostNotice(r.hostLost) : ''}`;
 }
 /** The human form (stderr): formatTiming() of the SDK, one block. */
 export function timingText(t) {
@@ -125,6 +150,15 @@ export function timingJson(t) {
                         state_as_of: s.lostSuspend.stateAsOf,
                     }
                     : null,
+                // 0.8.1+: the machine the workspace ran on failed (resume: what it restored; suspend: detected_at only).
+                host_lost: s.hostLost
+                    ? {
+                        detected_at: s.hostLost.detectedAt,
+                        restored_from: s.hostLost.restoredFrom,
+                        restored_checkpoint_id: s.hostLost.restoredCheckpointId,
+                        state_as_of: s.hostLost.stateAsOf,
+                    }
+                    : null,
                 boot_to_ready_ms: s.bootToReadyMs,
                 host_timings_ms: s.hostTimingsMs,
             }
@@ -196,7 +230,7 @@ export class BuildTimer {
 }
 const fmtMs = (ms) => (ms === null ? '-' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
 const short = (sha) => sha.slice(0, 12);
-const bytes = (n) => (n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`);
+const bytes = byteSize;
 /** One stderr line per build-from-file progress event. */
 export function progressLine(e) {
     if (e.type === 'pack')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.12.0"
+    "@shardflux/sdk": "^0.13.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",