@shardflux/mcp 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -3,7 +3,34 @@
 Every tool, field and variable the README shows is available from the version named here. Below 1.0, a minor release
 may break compatibility; breaking changes are marked **Breaking**. Versions before 0.3.0 were not published.
 
-## 0.4.3 (not yet published)
+## 0.5.1
+
+Needs `@shardflux/sdk` 0.11.0 (the workspace version).
+
+`workspace_suspend` takes `after_seconds` from 0 to 3600 (before: 30 to 3600): 0 suspends the workspace as soon as it
+is idle (a few seconds of activity flush grace after its last work); a running command or a keepalive still postpones
+it. The result's `message` then says `the workspace is suspended as soon as it is idle`. Out of range is still
+`invalid_arguments` before any request.
+
+## 0.5.0
+
+Needs `@shardflux/sdk` 0.11.0 (the workspace version).
+
+A resume that restarted processes says so (cold boot, contracts §12). When the platform's VM runtime changed after a
+suspend and no host can restore the memory snapshot, the cell resumes the workspace by booting its saved disk,
+automatically, also when a workspace tool wakes it. Files are as of the suspend; every process was restarted.
+
+- `timing.server` of results and error results adds `memory_restored` (when the API reports it: `false` for a cold
+  boot, `true` for a memory resume) and `cold_boot_reason` (e.g. `runtime_changed`), next to `resume_path`
+  (`cold_boot`).
+- Such a result (`workspace_resume` or `operation_wait` of the resume, `workspace_open`, or any workspace tool whose
+  call woke the workspace) carries a top-level `notice` in plain language: the workspace was resumed from its saved
+  disk, files are kept, every process was restarted, so start dev servers, databases, watchers and background jobs
+  again. An error result carries it next to `error` when the wake before the failure did that.
+- The server instructions and the `workspace_resume` description tell the agent what `notice` and
+  `memory_restored: false` mean. `processRestartNotice()` is exported with `compactTiming()`.
+
+## 0.4.3
 
 Fix: the server (MCP initialize, User-Agent, update check) reports 0.4.3. 0.4.2 was published reporting 0.4.1, its previous version; the build now
 fails when `MCP_SERVER_VERSION` differs from package.json.

package/README.md

@@ -238,7 +238,7 @@ The management tools:
 | `workspace_list` | List the project's workspaces, with `prefix`, `state`, `lifetime`, `purpose`, `include_deleted`, `limit` and `cursor`. By default only persistent standard workspaces are listed. |
 | `workspace_status` | One workspace plus its five most recent operations. |
 | `workspace_suspend`, `workspace_resume` | Lifecycle operation. Returns at once unless `wait: true` (then once it finished, through the SDK's own `wait`). |
-| `workspace_suspend` with `after_seconds` | (0.4.1) Suspend when idle: the workspace is suspended once it has been idle for `after_seconds` (30-3600), instead of now. The description tells the agent to use it when it finishes its work, so the workspace stops using RAM soon after. Its next tool call on the workspace cancels it; a running command or a keepalive postpones it. Returns `suspend_request` (`not_before`: the earliest suspend) and a `message`; `operation` when a suspend was already in progress. Not with `wait`. `workspace_status` shows a pending request as `workspace.suspend_request`. Not for file-first workspaces. |
+| `workspace_suspend` with `after_seconds` | (0.4.1) Suspend when idle: the workspace is suspended once it has been idle for `after_seconds` (0-3600; 0 = as soon as it is idle, 0.5.1+), instead of now. The description tells the agent to use it when it finishes its work, so the workspace stops using RAM soon after. Its next tool call on the workspace cancels it; a running command or a keepalive postpones it. Returns `suspend_request` (`not_before`: the earliest suspend) and a `message`; `operation` when a suspend was already in progress. Not with `wait`. `workspace_status` shows a pending request as `workspace.suspend_request`. Not for file-first workspaces. |
 | `workspace_fork` | Fork into `new_key`. |
 | `operation_wait` | Keep waiting for an operation. |
 | `usage_summary` | The organization's usage summary for the current period: meters, allowances with their cap state, `allowance_exhausted` with `exhausted_reason`, and (0.4.1+, an API with opt-in overage) `spend_cap`: the overage state, cap, charges, lines per allowance and the date the cap is projected to be reached. |
@@ -371,6 +371,7 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
   - Phases are in order, as `phase(reason) ms`. `request(held)` means the API held the open until the workspace was
     ready. `capacity_pending(no_ready_host)` is time spent waiting for a host.
   - `server` is the operation's own queued, run and total time, plus the start or resume path the cell reported.
+    A resume also has `memory_restored` (0.5.0+) when the API reports it, and `cold_boot_reason` when it is false.
   - `outside_server_ms` is everything else: network, polling, reading the workspace, the tool token.
   - A failed or timed-out call carries it too, next to `error` (`{error, timing}`).
   - `workspace_open` uses the SDK's waited open: the API holds the request until the workspace is ready and answers
@@ -398,6 +399,13 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
     suspended).
   - With `SHARDFLUX_WAKE=off` the API's refusal comes back instead (`conflict`,
     `details.reason: workspace_not_running`, or `workspace_not_running` from the cell gateway).
+  - **A resume can restart processes (0.5.0+).** A resume normally restores memory and running processes. When the
+    platform's VM runtime changed after the suspend and no host can restore that memory snapshot, the resume boots
+    the workspace's saved disk instead (a cold boot), also when a workspace tool wakes it. The call still runs, and
+    files are as of the suspend, but every process was restarted. The result (or the error result) then carries
+    `timing.server.resume_path: "cold_boot"`, `memory_restored: false`, `cold_boot_reason` (e.g. `runtime_changed`)
+    and a `notice` the agent reads: to start its dev servers, databases, watchers and background jobs again. The
+    server instructions and the `workspace_resume` description say so too.
   - Tool tokens are never returned to the model.
 - **Keys, not ids.** Tools take workspace keys, resolved by exact match within the key's project.
 

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * `shardflux-mcp` (bin.ts); `createShardfluxMcpServer()` builds the same server for any
  * MCP transport.
  */
-export { ALL_TOOL_PERMISSIONS, MCP_PACKAGE, MCP_SERVER_VERSION, checkServerVersion, compactTiming, createShardfluxMcpServer, errorResult, feedbackSuggestion, okResult, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from './server.js';
+export { ALL_TOOL_PERMISSIONS, MCP_PACKAGE, MCP_SERVER_VERSION, checkServerVersion, compactTiming, createShardfluxMcpServer, errorResult, feedbackSuggestion, okResult, processRestartNotice, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from './server.js';
 export type { Logger, ObjectSchema, ServerOptions } from './server.js';
 export { ConfigError, DEFAULT_TOOL_TIMEOUT_MS, DEFAULT_WAKE_TIMEOUT_MS, MAX_TOOL_TIMEOUT_MS, apiUrlFrom, loadConfig } from './config.js';
 export type { McpConfig } from './config.js';

package/dist/index.js

@@ -4,7 +4,7 @@
  * `shardflux-mcp` (bin.ts); `createShardfluxMcpServer()` builds the same server for any
  * MCP transport.
  */
-export { ALL_TOOL_PERMISSIONS, MCP_PACKAGE, MCP_SERVER_VERSION, checkServerVersion, compactTiming, createShardfluxMcpServer, errorResult, feedbackSuggestion, okResult, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from "./server.js";
+export { ALL_TOOL_PERMISSIONS, MCP_PACKAGE, MCP_SERVER_VERSION, checkServerVersion, compactTiming, createShardfluxMcpServer, errorResult, feedbackSuggestion, okResult, processRestartNotice, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from "./server.js";
 export { ConfigError, DEFAULT_TOOL_TIMEOUT_MS, DEFAULT_WAKE_TIMEOUT_MS, MAX_TOOL_TIMEOUT_MS, apiUrlFrom, loadConfig } from "./config.js";
 export { ToolError, describeToolError, hostFeatureHint, modeHint, redact } from "./errors.js";
 export { main, stderrLogger } from "./main.js";

package/dist/server.d.ts

@@ -3,7 +3,7 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ClientVersionStatus, JsonSchema, LifecycleTiming, Operation, TemplateBuild, TemplateDetail, TemplateOwner, ToolName, WorkspaceMode, WorkspaceTool, WorkspaceView } from '@shardflux/sdk';
 import type { McpConfig } from './config.js';
 import type { ToolErrorInfo } from './errors.js';
-export declare const MCP_SERVER_VERSION = "0.4.3";
+export declare const MCP_SERVER_VERSION = "0.5.1";
 /** The package this server is distributed as: its entry in GET /v1/client-versions (contracts §30.4). */
 export declare const MCP_PACKAGE = "@shardflux/mcp";
 export declare const ALL_TOOL_PERMISSIONS: readonly ToolName[];
@@ -192,6 +192,8 @@ export declare function compactTiming(t: LifecycleTiming): {
     total_ms: number;
     phases: string[];
     server: {
+        cold_boot_reason?: string | undefined;
+        memory_restored?: boolean | undefined;
         resume_path?: string | undefined;
         warm_fallback?: string | undefined;
         start_path?: string | undefined;
@@ -205,6 +207,12 @@ export declare function compactTiming(t: LifecycleTiming): {
     action: import("@shardflux/sdk").LifecycleAction;
     outcome: import("@shardflux/sdk").TimingOutcome;
 };
+/**
+ * (0.5.0) The `notice` of a result whose resume or wake booted the workspace's saved disk instead of restoring its memory
+ * (`resume_path` `cold_boot`, `memory_restored` false): plain language an agent acts on, since the dev servers, watchers
+ * and background jobs it started are gone. Undefined for any other timing, including one whose memory_restored is unknown.
+ */
+export declare function processRestartNotice(t: LifecycleTiming): string | undefined;
 export declare function okResult(value: unknown): CallToolResult;
 /**
  * `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. `extra` (0.4.0): more sibling

package/dist/server.js

@@ -53,7 +53,7 @@ import { parse as parseYaml } from 'yaml';
 import { DEFAULT_WAKE_TIMEOUT_MS } from "./config.js";
 import { ToolError, describeToolError, redact } from "./errors.js";
 import { makeFetch } from "./http.js";
-export const MCP_SERVER_VERSION = '0.4.3';
+export const MCP_SERVER_VERSION = '0.5.1';
 /** The package this server is distributed as: its entry in GET /v1/client-versions (contracts §30.4). */
 export const MCP_PACKAGE = '@shardflux/mcp';
 const USER_AGENT = `shardflux-mcp/${MCP_SERVER_VERSION} shardflux-sdk-ts/${SDK_VERSION}`;
@@ -222,12 +222,32 @@ export function compactTiming(t) {
                 ...(s.startPath ? { start_path: s.startPath } : {}),
                 ...(s.warmFallback ? { warm_fallback: s.warmFallback } : {}),
                 ...(s.resumePath ? { resume_path: s.resumePath } : {}),
+                // 0.5.0: false when the resume booted the saved disk (processes restarted); absent when the API did not say.
+                ...(typeof s.memoryRestored === 'boolean' ? { memory_restored: s.memoryRestored } : {}),
+                ...(s.coldBootReason ? { cold_boot_reason: s.coldBootReason } : {}),
             }
             : null,
         outside_server_ms: ms(t.outsideServerMs),
         retries: t.retries.length,
     };
 }
+/** What a cold boot's reason means, for the agent (the cell's cold_boot_reason values). */
+const COLD_BOOT_REASONS = {
+    runtime_changed: "the platform's VM runtime changed since the workspace was suspended, so its memory snapshot could not be restored",
+};
+/**
+ * (0.5.0) The `notice` of a result whose resume or wake booted the workspace's saved disk instead of restoring its memory
+ * (`resume_path` `cold_boot`, `memory_restored` false): plain language an agent acts on, since the dev servers, watchers
+ * and background jobs it started are gone. Undefined for any other timing, including one whose memory_restored is unknown.
+ */
+export function processRestartNotice(t) {
+    const s = t.server;
+    if (s?.resumePath !== 'cold_boot' || s.memoryRestored !== false)
+        return undefined;
+    const why = s.coldBootReason ? ` (${s.coldBootReason}: ${COLD_BOOT_REASONS[s.coldBootReason] ?? 'the memory snapshot could not be restored'})` : '';
+    return (`The workspace was resumed from its saved disk, not from memory${why}. Its files are as they were when it was suspended, ` +
+        'but every process was restarted, as after a reboot: start again any dev server, database, watcher or background job you had running, and open new terminals.');
+}
 export function okResult(value) {
     if (isObject(value) && value.mime_type === 'image/png' && typeof value.data_base64 === 'string') {
         const { data_base64: data, ...meta } = value;
@@ -284,6 +304,7 @@ const INSTRUCTIONS = [
     'When you finish your work on a workspace, call workspace_suspend with after_seconds (e.g. 60): it is suspended once idle that long, so it stops using RAM; your next tool call on it cancels that.',
     'A start (open, resume, fork) that no host can admit waits for capacity for at most 15 minutes, then fails with code operation_failed, details.error_code capacity_unavailable and retryable true: nothing was started; retry later if you still need it. retryable false means retrying will not help.',
     'Opens, waits and wakes add timing (phases, server queued/run time) saying where the time went.',
+    'A resume (also the automatic one when a tool call finds the workspace suspended) normally restores memory and running processes. If a result carries notice and timing.server.memory_restored false (resume_path cold_boot), the workspace booted from its saved disk instead: files are kept, but every process was restarted, so start your dev servers and background jobs again.',
     'Templates: template_get shows a template’s versions and settings (the inputs workspace_open takes); template_languages lists what a base offers build.languages; template_build builds a new version from a recipe v2 (unpublished unless publish is true).',
     'search_files finds text in files under a directory; edit_file replaces exact text in a file (each old_text must occur once) and returns the new revision, which you can pass as expected_revision to the next edit_file of that file so a change made by someone else is detected.',
     'File-first workspaces (workspace_open mode "file_first"; results show mode and tree_revision) keep only files: there is no VM between calls, each exec runs in a fresh VM, and only files under /home/user persist between exec calls (install dependencies there, e.g. a virtualenv, and start servers within the command that needs them).',
@@ -630,9 +651,9 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 workspace_key: workspaceKeyProp(pinned),
                 after_seconds: {
                     type: 'integer',
-                    minimum: 30,
+                    minimum: 0,
                     maximum: 3600,
-                    description: 'Suspend once the workspace has been idle this many seconds (30-3600) instead of now. Omit to suspend now.',
+                    description: 'Suspend once the workspace has been idle this many seconds (0-3600; 0 = as soon as it is idle) instead of now. Omit to suspend now.',
                 },
                 wait: { type: 'boolean', description: 'Wait until the suspend finishes (default false). Not with after_seconds.' },
             }, keyRequired),
@@ -660,12 +681,12 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     operation: r.operation ? summarizeOperation(r.operation) : null,
                     workspace: summarizeWorkspace(ws.data),
                     message: r.suspendRequest
-                        ? `Suspend scheduled: the workspace is suspended once it has been idle for ${r.suspendRequest.after_seconds} s (not before ${r.suspendRequest.not_before}). Your next tool call on it cancels this; a running command or keepalive postpones it.`
+                        ? `Suspend scheduled: the workspace is suspended ${r.suspendRequest.after_seconds === 0 ? 'as soon as it is idle' : `once it has been idle for ${r.suspendRequest.after_seconds} s`} (not before ${r.suspendRequest.not_before}). Your next tool call on it cancels this; a running command or keepalive postpones it.`
                         : `A suspend is already in progress (operation ${r.operation.id}, ${r.operation.state}); nothing was scheduled.`,
                 };
             },
         },
-        lifecycleTool('workspace_resume', 'Resume workspace', 'Resume a suspended workspace. Returns the resume operation (with wait: once finished, and its timing). Not for file-first workspaces (never suspended).', 'resume', 
+        lifecycleTool('workspace_resume', 'Resume workspace', 'Resume a suspended workspace. Returns the resume operation (with wait: once finished, and its timing). A notice in the result (timing.server.memory_restored false) means it booted from its saved disk: files kept, processes restarted. Not for file-first workspaces (never suspended).', 'resume', 
         // Through the server's handle: a waited resume is held until the workspace runs (contracts §22.6) and the handle
         // keeps the view and this server's tool token, so the next workspace tool starts at once.
         (ws, o) => ws.resume({ ...o, agentLabel: config.agentLabel })),
@@ -994,7 +1015,8 @@ export function createShardfluxMcpServer(config, opts = {}) {
         try {
             const value = await Promise.race([running, aborted]);
             log('info', 'tool call', { tool: name, outcome: 'ok', ms: Date.now() - started });
-            return okResult(call.timed && call.timing && isObject(value) ? { ...value, timing: compactTiming(call.timing) } : value);
+            const notice = call.timed && call.timing ? processRestartNotice(call.timing) : undefined;
+            return okResult(call.timed && call.timing && isObject(value) ? { ...value, timing: compactTiming(call.timing), ...(notice ? { notice } : {}) } : value);
         }
         catch (err) {
             if (extra.signal.aborted) {
@@ -1032,7 +1054,9 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 : suggestsFeedback(info)
                     ? { feedback: feedbackSuggestion(info) }
                     : {};
-            return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined, siblings);
+            // A wake that booted the saved disk before the failure still restarted every process: said next to the error.
+            const notice = call.timed && call.timing ? processRestartNotice(call.timing) : undefined;
+            return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined, { ...siblings, ...(notice ? { notice } : {}) });
         }
     });
     return server;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/mcp",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "mcpName": "dev.shardflux/mcp",
   "type": "module",
   "description": "Shardflux MCP server (stdio): give Claude, Cursor, Codex or any MCP client persistent cloud workspaces to run commands, edit files, use git and a browser in. Uses your scoped Shardflux API key.",
@@ -46,7 +46,7 @@
     "@modelcontextprotocol/sdk": "1.30.0",
     "yaml": "2.9.1",
     "zod": "4.6.5",
-    "@shardflux/sdk": "^0.10.2"
+    "@shardflux/sdk": "^0.11.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",