@shardflux/mcp 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -23,6 +23,27 @@ change).
   `host_feature_unavailable`: `search_files is not available for this workspace. Search with exec instead, ...
   Retrying does not help.` (the same for `edit_file` and other tools). `mode_not_available` drops "yet".
 
+## 0.6.0 (release candidate)
+
+Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
+
+Uses SDK 0.12.0 and its pooled transport. Adds label creation/filtering, workspace_idle, workspace_keepalive, workspace_set_idle_policy, workspace_set_labels, workspace_exec_start and workspace_exec_input. Exec tools follow key permissions and are hidden for file-first workspaces. Protocol errors include source.
+
+Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
+
+### Instant suspend: durable storage
+
+- Operations in tool results carry `durable`, `suspend_path`, `durability` (suspend, fork) and `lost_suspend` (resume)
+  when the result has them; `timing.server` adds `durable` and `durability_state`.
+- `workspace_suspend` takes `durable: true`: returns once the copy is in durable storage (implies `wait`; not with
+  `after_seconds`). A copy that cannot be made is the tool error `durability_lost` (`operation_id`, `details.state`
+  `lost`, `details.reason`); a durable wait that runs out is `timeout` with `details` `{durable: false, state:
+  "pending"}` and says to call `operation_wait` with `durable: true`.
+- `operation_wait` takes `durable: true` (a suspend or fork).
+- A resume whose result carries `lost_suspend` adds a `notice` naming the checkpoint it resumed from.
+- A suspend-when-idle canceled `workspace_active`: the `operation_failed` message says the workspace keeps running.
+- `workspace_suspend` no longer describes the suspend as a "durable" checkpoint.
+
 ## 0.5.1
 
 Needs `@shardflux/sdk` 0.11.0 (the workspace version).

package/README.md

@@ -174,7 +174,7 @@ environment `SHARDFLUX_API_KEY`.
 | `SHARDFLUX_WAKE_TIMEOUT_MS` | Longest wait per tool call for a workspace to wake or finish a transition, 1000-3600000 ms. Default 120000. It is clamped to `SHARDFLUX_MCP_TOOL_TIMEOUT_MS`, and each wake also ends 250 ms before the call's own deadline. |
 | `SHARDFLUX_AGENT_LABEL` | Attribution label of every tool token this server obtains. Default `mcp`. It appears as an agent session in `GET /v1/workspaces/{id}/agent-sessions`, the console and `shard ws sessions`. |
 | `SHARDFLUX_MCP_LOG_LEVEL` | `debug`, `info` (default), `warn` or `error`. Logs are JSON lines on **stderr**; stdout is the protocol. The key is never logged, and anything key-shaped is redacted. |
-| `SHARDFLUX_HTTP_KEEPALIVE=1` | Reuse HTTP connections. By default every request uses a fresh connection (`Connection: close`). |
+| `SHARDFLUX_HTTP_KEEPALIVE` | 0.6.0+: default private HTTP/1.1 pooling on Node 26; `0` forces close for diagnosis, `1` uses native pooling. |
 | `SHARDFLUX_NO_UPDATE_CHECK` | (0.4.0) `1`, `true`, `yes` or `on` turns off the startup version check (see "Updates"). |
 | `NO_UPDATE_NOTIFIER` | (0.4.0) The npm convention: any non-empty value also turns the check off. |
 
@@ -237,8 +237,9 @@ The management tools:
 | `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` (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. |
+| `workspace_suspend` with `durable: true` | (0.6.0+) Returns once the suspend is in durable storage. A suspend returns as soon as the workspace is sealed on its host, typically in a few hundred ms; its operation's `durable` turns true when the copy lands in durable storage, typically within a second (`durability` shows its progress). |
+| `workspace_fork` | Fork into `new_key`. A fork of a running workspace carries `durable` and `durability` the same way (0.6.0+). |
+| `operation_wait` | Keep waiting for an operation. `durable: true` (0.6.0+): a suspend or fork, until its copy is in durable storage. |
 | `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. |
 | `send_feedback` | (0.4.0) Feedback straight to the Shardflux team: `message`, `category`, and optional `workspace`, `request_id`, `error_code`, `command`. See [Feedback](#feedback-agents-are-asked-to-use-send_feedback-while-they-work). |
 | `template_get` | (0.3.0) A template's versions with their settings (env, inputs, start commands, services, defaults); with `version`, that version's recipe in request form. |
@@ -416,3 +417,10 @@ await server.connect(transport); // any @modelcontextprotocol/sdk transport
 ## License
 
 Apache-2.0
+
+
+## Integration controls (0.6.0+)
+
+`workspace_open` accepts `labels` and `idle_policy`; `workspace_list` accepts exact label filters. `workspace_set_labels` replaces all labels. `workspace_idle` reads activity without waking, `workspace_keepalive` declares ongoing work, and `workspace_set_idle_policy` accepts adaptive, never, fixed:<seconds>, or default.
+`workspace_exec_start` starts a tracked background command with optional `stdin_open`; `workspace_exec_input` writes data at an acknowledged byte offset and can send EOF with `close`. Both require exec permission and processful workspaces. Frames are bounded to 64 KiB; use the returned offset after partial acknowledgements. The host and guest must advertise pipe-input support.
+`workspace_resume` recovers failed IDs without replacing their disks. A completed delete frees the key for a new workspace ID. Protocol errors include their source; a bare 404 is not a workspace tombstone.

package/dist/errors.d.ts

@@ -18,7 +18,7 @@ export interface ToolErrorInfo {
     execution_id?: string;
     /** tree_revision_mismatch: the revision the workspace's file tree is at (0.4.0). */
     current_tree_revision?: number;
-    source?: 'api' | 'cell';
+    source?: 'api' | 'cell' | 'unknown';
     details?: Record<string, unknown>;
     issues?: string[];
     last_state?: string;

package/dist/errors.js

@@ -7,7 +7,7 @@
  * tool that is not available for the workspace (host_feature_unavailable), a
  * `hint` saying what to do instead.
  */
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateUploadError, ToolArgumentError, TreeRevisionMismatchError } from '@shardflux/sdk';
+import { DurabilityLostError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateUploadError, ToolArgumentError, TreeRevisionMismatchError } from '@shardflux/sdk';
 /** A refusal decided by this server (argument/pinning problems, unknown workspace key). */
 export class ToolError extends Error {
     name = 'ToolError';
@@ -112,15 +112,26 @@ export function describeToolError(err, context = {}) {
     if (err instanceof ToolError)
         return { code: err.code, message: err.message, ...(err.details ? { details: err.details } : {}) };
     if (err instanceof OperationTimeoutError) {
+        if (err.durable) {
+            return { code: 'timeout', message: `${err.message} Call operation_wait with this operation_id and durable: true to keep waiting.`, operation_id: err.operationId, last_state: err.lastState, retryable: true, details: { durable: false, state: 'pending' } };
+        }
         return { code: 'timeout', message: `${err.message} Call operation_wait with this operation_id to keep waiting.`, operation_id: err.operationId, last_state: err.lastState, retryable: true };
     }
+    // 0.6.0: the suspend (or fork) succeeded; its durable copy could not be made (durability.state lost).
+    if (err instanceof DurabilityLostError) {
+        return { code: 'durability_lost', message: err.message, operation_id: err.operationId, retryable: false, details: { state: 'lost', ...(err.durability.reason ? { reason: err.durability.reason } : {}), ...(err.durability.checkpointId ? { checkpoint_id: err.durability.checkpointId } : {}) } };
+    }
     if (err instanceof OperationFailedError) {
         // retryable: the operation error's own flag. capacity_unavailable (the start passed its deadline) is retryable:
         // nothing was started, so the agent may send it again.
         const opDetails = err.operation.error?.details;
         const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
         const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
-        const hint = err.errorCode === 'capacity_unavailable' ? '. The start passed its deadline and nothing was started; send it again.' : '';
+        const hint = err.errorCode === 'capacity_unavailable'
+            ? '. The start passed its deadline and nothing was started; send it again.'
+            : err.workspaceActive
+                ? '. The workspace was in use, so the suspend-when-idle was canceled; nothing changed and it keeps running.'
+                : '';
         return { code: 'operation_failed', message: `${err.message}${hint}`, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}) };
     }
     if (named(err, 'TimeoutError')) {
@@ -141,7 +152,7 @@ export function describeToolError(err, context = {}) {
     if (err instanceof TemplateUploadError)
         return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof ShardfluxProtocolError)
-        return { code: 'protocol_error', message: err.message, status: err.status, ...(context.executionId ? { execution_id: context.executionId } : {}) };
+        return { code: 'protocol_error', message: err.message, status: err.status, source: err.source, ...(context.executionId ? { execution_id: context.executionId } : {}) };
     if (err instanceof TypeError && err.message === 'fetch failed') {
         const cause = err.cause;
         return {

package/dist/http.d.ts

@@ -1,6 +1,2 @@
-/**
- * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
- * default every request uses a fresh connection (`Connection: close`);
- * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
- */
+/** Share the SDK's pooled transport. A caller-supplied fetch stays under the caller's control. */
 export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;

package/dist/http.js

@@ -1,15 +1,5 @@
-/**
- * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
- * default every request uses a fresh connection (`Connection: close`);
- * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
- */
-export function makeFetch(env, base = fetch) {
-    // Why a fresh connection by default (Node 26 keep-alive measurements): docs/progress/startup-latency.md.
-    if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
-        return base;
-    return (input, init) => {
-        const headers = new Headers(init?.headers);
-        headers.set('connection', 'close');
-        return base(input, { ...init, headers });
-    };
+import { defaultFetch } from '@shardflux/sdk';
+/** Share the SDK's pooled transport. A caller-supplied fetch stays under the caller's control. */
+export function makeFetch(env, base = defaultFetch(env)) {
+    return base;
 }

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.5.2";
+export declare const MCP_SERVER_VERSION = "0.6.0";
 /** The package this server is distributed as: its entry in GET /v1/client-versions. */
 export declare const MCP_PACKAGE = "@shardflux/mcp";
 export declare const ALL_TOOL_PERMISSIONS: readonly ToolName[];
@@ -36,6 +36,33 @@ export declare function summarizeWorkspace(v: WorkspaceView): {
         version: number;
     };
     active_operation: {
+        lost_suspend?: ({
+            checkpoint_id: string;
+            generation_id?: string;
+            reason?: string;
+            suspended_at?: string;
+            restored_checkpoint_id?: string;
+            state_as_of?: string;
+        } & {
+            [key: string]: unknown;
+        }) | undefined;
+        durability?: ({
+            state: "pending" | "durable" | "lost";
+            checkpoint_id?: string;
+            generation_id?: string;
+            local_commit_at?: string;
+            durable_by?: string;
+            durable_at?: string;
+            local_commit_to_durable_ms?: number;
+            overdue_at?: string;
+            reason?: string;
+            code?: string;
+            recovery_point_checkpoint_id?: string | null;
+        } & {
+            [key: string]: unknown;
+        }) | undefined;
+        suspend_path?: string | undefined;
+        durable?: boolean | undefined;
         error?: {
             [key: string]: unknown;
         } | undefined;
@@ -62,6 +89,9 @@ export declare function summarizeWorkspace(v: WorkspaceView): {
     purpose: "standard" | "template_draft" | "template_test";
     disk_layout: "legacy" | "layered";
     idle_timeout_seconds: number | null;
+    labels: {
+        [key: string]: string;
+    };
     ended_reason: "closed" | "idle_timeout" | "draft_discarded" | null;
     /** Start commands and services of the template version; null when it has none. */
     startup: {
@@ -171,6 +201,33 @@ export declare function summarizeTemplate(t: TemplateDetail): {
     versions_truncated: boolean;
 };
 export declare function summarizeOperation(o: Operation): {
+    lost_suspend?: ({
+        checkpoint_id: string;
+        generation_id?: string;
+        reason?: string;
+        suspended_at?: string;
+        restored_checkpoint_id?: string;
+        state_as_of?: string;
+    } & {
+        [key: string]: unknown;
+    }) | undefined;
+    durability?: ({
+        state: "pending" | "durable" | "lost";
+        checkpoint_id?: string;
+        generation_id?: string;
+        local_commit_at?: string;
+        durable_by?: string;
+        durable_at?: string;
+        local_commit_to_durable_ms?: number;
+        overdue_at?: string;
+        reason?: string;
+        code?: string;
+        recovery_point_checkpoint_id?: string | null;
+    } & {
+        [key: string]: unknown;
+    }) | undefined;
+    suspend_path?: string | undefined;
+    durable?: boolean | undefined;
     error?: {
         [key: string]: unknown;
     } | undefined;
@@ -192,6 +249,8 @@ export declare function compactTiming(t: LifecycleTiming): {
     total_ms: number;
     phases: string[];
     server: {
+        durability_state?: "pending" | "durable" | "lost" | undefined;
+        durable?: boolean | undefined;
         cold_boot_reason?: string | undefined;
         memory_restored?: boolean | undefined;
         resume_path?: string | undefined;
@@ -213,6 +272,13 @@ export declare function compactTiming(t: LifecycleTiming): {
  * 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;
+/**
+ * (0.6.0) The `notice` of a result whose resume restored an earlier checkpoint because the workspace's latest suspend
+ * could not be kept (`lost_suspend`): the files and processes are as of that checkpoint.
+ */
+export declare function lostSuspendNotice(t: LifecycleTiming): string | undefined;
+/** The notices of a timing (cold boot, lost suspend), joined; undefined when there are none. */
+export declare function timingNotice(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.5.2';
+export const MCP_SERVER_VERSION = '0.6.0';
 /** The package this server is distributed as: its entry in GET /v1/client-versions. */
 export const MCP_PACKAGE = '@shardflux/mcp';
 const USER_AGENT = `shardflux-mcp/${MCP_SERVER_VERSION} shardflux-sdk-ts/${SDK_VERSION}`;
@@ -75,7 +75,7 @@ export function sdkToolDefinitions(tools = ALL_TOOL_PERMISSIONS, mode = 'process
     return workspaceTools(noWorkspace, { tools: [...tools], mode });
 }
 /** Management tools that need a workspace VM or an operation: not listed for a pinned file-first workspace. */
-const VM_ONLY_MANAGEMENT = new Set(['workspace_suspend', 'workspace_resume', 'workspace_fork', 'operation_wait']);
+const VM_ONLY_MANAGEMENT = new Set(['workspace_suspend', 'workspace_resume', 'workspace_fork', 'operation_wait', 'workspace_idle', 'workspace_keepalive', 'workspace_set_idle_policy', 'workspace_exec_start', 'workspace_exec_input']);
 /** What to use instead of a workspace tool a file-first workspace does not have, by the tool's permission. */
 const FILE_FIRST_INSTEAD = {
     process: 'Nothing runs between exec calls: run the program, and whatever needs it, within one exec command.',
@@ -132,6 +132,7 @@ export function summarizeWorkspace(v) {
         purpose: v.purpose,
         disk_layout: v.disk_layout,
         idle_timeout_seconds: v.idle_timeout_seconds,
+        labels: v.labels,
         ended_reason: v.ended_reason,
         /** Start commands and services of the template version; null when it has none. */
         startup: v.startup ?? null,
@@ -194,6 +195,11 @@ export function summarizeOperation(o) {
         created_at: o.created_at,
         completed_at: o.completed_at ?? null,
         ...(o.error ? { error: o.error } : {}),
+        // 0.6.0: suspend and fork say whether their copy is in durable storage; a resume names a suspend it could not restore.
+        ...(typeof o.result?.durable === 'boolean' ? { durable: o.result.durable } : {}),
+        ...(o.result?.suspend_path ? { suspend_path: o.result.suspend_path } : {}),
+        ...(o.result?.durability ? { durability: o.result.durability } : {}),
+        ...(o.result?.lost_suspend ? { lost_suspend: o.result.lost_suspend } : {}),
     };
 }
 function isObject(v) {
@@ -225,6 +231,8 @@ export function compactTiming(t) {
                 // 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 } : {}),
+                ...(typeof s.durable === 'boolean' ? { durable: s.durable } : {}),
+                ...(s.durability ? { durability_state: s.durability.state } : {}),
             }
             : null,
         outside_server_ms: ms(t.outsideServerMs),
@@ -248,6 +256,23 @@ export function processRestartNotice(t) {
     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.');
 }
+/**
+ * (0.6.0) The `notice` of a result whose resume restored an earlier checkpoint because the workspace's latest suspend
+ * could not be kept (`lost_suspend`): the files and processes are as of that checkpoint.
+ */
+export function lostSuspendNotice(t) {
+    const l = t.server?.lostSuspend;
+    if (!l)
+        return undefined;
+    return (`The workspace was resumed from its checkpoint${l.stateAsOf ? ` of ${l.stateAsOf}` : ''} (${l.restoredCheckpointId ?? 'the previous one'}); ` +
+        `its suspend${l.suspendedAt ? ` at ${l.suspendedAt}` : ''} was not kept${l.reason ? ` (${l.reason})` : ''}. ` +
+        'Work done between those times is not in the workspace: check the files you changed and run again what you need.');
+}
+/** The notices of a timing (cold boot, lost suspend), joined; undefined when there are none. */
+export function timingNotice(t) {
+    const parts = [processRestartNotice(t), lostSuspendNotice(t)].filter((x) => x !== undefined);
+    return parts.length ? parts.join(' ') : undefined;
+}
 export function okResult(value) {
     if (isObject(value) && value.mime_type === 'image/png' && typeof value.data_base64 === 'string') {
         const { data_base64: data, ...meta } = value;
@@ -554,6 +579,8 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     description: config.template ? `Template slug (default "${config.template}").` : 'Template slug for a new workspace, e.g. "python-node-browser".',
                 },
                 ...capsProps,
+                labels: { type: 'object', additionalProperties: true, description: 'Searchable workspace labels; replaces existing labels when supplied.' },
+                idle_policy: { type: 'string', pattern: '^(adaptive|never|fixed:[0-9]+)$', description: 'Automatic suspend policy.' },
                 lifetime: {
                     type: 'string',
                     enum: ['persistent', 'session'],
@@ -590,6 +617,8 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     ...(caps ? { caps } : {}),
                     ...(lifetime ? { lifetime } : {}),
                     ...(inputs ? { inputs } : {}),
+                    ...(args.labels !== undefined ? { labels: stringMap(args.labels, 'labels') } : {}),
+                    ...(typeof args.idle_policy === 'string' ? { idlePolicy: args.idle_policy } : {}),
                     ...(mode ? { mode } : {}),
                     agentLabel: config.agentLabel,
                     wait: args.wait === false ? false : waitOpts(call),
@@ -605,6 +634,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
             description: 'List the workspaces of this API key’s project (key, state, template, active operation).',
             inputSchema: obj({
                 prefix: { type: 'string', minLength: 1, maxLength: 200, description: 'Only keys starting with this prefix.' },
+                labels: { type: 'object', additionalProperties: true, description: 'Exact label matches; all supplied pairs must match.' },
                 state: { type: 'string', enum: OBSERVED_STATES, description: 'Observed state filter.' },
                 include_deleted: { type: 'boolean', description: 'Include deleted workspaces (and ended sessions).' },
                 lifetime: { type: 'string', enum: ['persistent', 'session', 'any'], description: 'Lifetime filter (default persistent: session workspaces are hidden).' },
@@ -616,6 +646,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
             run: async (args) => {
                 const page = await cloud.workspaces.list({
                     ...(typeof args.prefix === 'string' ? { keyPrefix: args.prefix } : {}),
+                    ...(args.labels !== undefined ? { labels: stringMap(args.labels, 'labels') } : {}),
                     ...(typeof args.state === 'string' ? { state: args.state } : {}),
                     ...(args.include_deleted === true ? { includeDeleted: true } : {}),
                     ...(typeof args.lifetime === 'string' ? { lifetime: args.lifetime } : {}),
@@ -641,10 +672,49 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 return { workspace: summarizeWorkspace(ws.data), recent_operations: ops.data.map(summarizeOperation) };
             },
         },
+        {
+            name: 'workspace_idle', title: 'Inspect idle status', description: 'Read idle policy and activity without waking or recording activity.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned) }, keyRequired),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).idle(call.signal),
+        },
+        {
+            name: 'workspace_keepalive', title: 'Declare ongoing work', description: 'Prevent idle suspension for seconds; never shortens an existing keepalive.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), seconds: { type: 'integer', minimum: 1 } }, [...keyRequired, 'seconds']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).keepalive(args.seconds, call.signal),
+        },
+        {
+            name: 'workspace_set_idle_policy', title: 'Set idle policy', description: 'Set adaptive, never or fixed:<seconds> (60..604800); default restores the inherited policy.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), policy: { type: 'string', description: 'adaptive, never, fixed:<seconds>, or default' } }, [...keyRequired, 'policy']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            run: async (args, call) => summarizeWorkspace((await (await resolve(keyOf(args), { signal: call.signal })).setIdlePolicy(args.policy === 'default' ? null : args.policy)).data),
+        },
+        {
+            name: 'workspace_set_labels', title: 'Replace workspace labels', description: 'Replace all labels; an empty object clears them. Labels are searchable metadata, not secrets.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), labels: { type: 'object', additionalProperties: true } }, [...keyRequired, 'labels']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            run: async (args, call) => summarizeWorkspace((await (await resolve(keyOf(args), { signal: call.signal })).setLabels(stringMap(args.labels, 'labels'))).data),
+        },
+        {
+            name: 'workspace_exec_start', permission: 'exec', title: 'Start background command', description: 'Start a tracked exec session. stdin_open keeps a pipe open for workspace_exec_input. Processful workspaces only.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), argv: { type: 'array', items: { type: 'string' }, minItems: 1 }, session_id: { type: 'string' }, stdin_open: { type: 'boolean' }, cwd: { type: 'string' } }, [...keyRequired, 'argv']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).cell().exec.start({ argv: args.argv,
+                ...(typeof args.session_id === 'string' ? { session_id: args.session_id } : {}), stdin_open: args.stdin_open === true,
+                ...(typeof args.cwd === 'string' ? { cwd: args.cwd } : {}) }, call.signal),
+        },
+        {
+            name: 'workspace_exec_input', permission: 'exec', title: 'Write command stdin', description: 'Write up to 64 KiB at the acknowledged byte offset (0 initially). close sends EOF. A repeated identical last frame cannot duplicate bytes; continue from a partial acknowledgement.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), session_id: { type: 'string' }, data: { type: 'string', maxLength: 65536 }, offset: { type: 'integer', minimum: 0 }, close: { type: 'boolean' } }, [...keyRequired, 'session_id', 'offset']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).cell().exec.input(args.session_id, typeof args.data === 'string' ? args.data : '', { offset: args.offset, close: args.close === true, signal: call.signal }),
+        },
         {
             name: 'workspace_suspend',
             title: 'Suspend workspace',
-            description: 'Suspend a running workspace (durable full-state checkpoint; processes stop, files and state are kept, and the next tool call resumes it). Returns the suspend operation (with wait: once finished, and its timing). ' +
+            description: 'Suspend a running workspace (full-state checkpoint; processes stop, files and state are kept, and the next tool call resumes it). Returns the suspend operation (with wait: once finished, and its timing). ' +
+                'A finished suspend returns as soon as the workspace is sealed on its host (typically a few hundred ms); its durable field turns true when the copy lands in durable storage, typically within a second. Pass durable: true to return only then. ' +
                 'With after_seconds the suspend is deferred instead: the workspace is suspended once it has been idle that long. Use it when you finish your work (the end of your turn), e.g. after_seconds 60, so the workspace stops using RAM soon after instead of waiting for its idle timeout. ' +
                 'Your next tool call on the workspace cancels it; a command still running or a keepalive postpones it until after_seconds after it ends. Returns suspend_request (not_before: the earliest suspend). Not for file-first workspaces (never suspended).',
             inputSchema: obj({
@@ -656,10 +726,14 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     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.' },
+                durable: { type: 'boolean', description: 'Wait until the suspend is in durable storage (result durable: true; implies wait). Not with after_seconds.' },
             }, keyRequired),
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
             run: async (args, call) => {
                 const afterSeconds = typeof args.after_seconds === 'number' ? args.after_seconds : undefined;
+                if (afterSeconds !== undefined && args.durable === true) {
+                    throw new ToolError('invalid_arguments', 'durable does not apply with after_seconds: the suspend happens later, once the workspace has been idle. Omit durable, or omit after_seconds to suspend now.');
+                }
                 if (afterSeconds !== undefined && args.wait === true) {
                     throw new ToolError('invalid_arguments', 'wait does not apply with after_seconds: the suspend happens later, once the workspace has been idle. Omit wait, or omit after_seconds to suspend now.');
                 }
@@ -669,7 +743,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     throw notForMode(ws, 'suspend', 'api', `workspace_suspend is not available for the file-first workspace "${key}": nothing runs between its exec calls, so it is never suspended; its files persist as they are.`);
                 }
                 if (afterSeconds === undefined) {
-                    const op = await cloud.workspaces.suspend(ws.id, lifecycleOpts(args, call));
+                    const op = await cloud.workspaces.suspend(ws.id, args.durable === true ? { ...lifecycleOpts({ ...args, wait: true }, call), durable: true } : lifecycleOpts(args, call));
                     call.operationId = op.id;
                     return { operation: summarizeOperation(op) };
                 }
@@ -716,10 +790,19 @@ export function createShardfluxMcpServer(config, opts = {}) {
         {
             name: 'operation_wait',
             title: 'Wait for operation',
-            description: 'Wait for a lifecycle operation (open, suspend, resume, fork, ...) to finish, up to timeout_ms. Returns the operation and the wait’s timing.',
-            inputSchema: obj({ operation_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Operation id (UUID).' } }, ['operation_id']),
+            description: 'Wait for a lifecycle operation (open, suspend, resume, fork, ...) to finish, up to timeout_ms. Returns the operation and the wait’s timing. With durable (a suspend or fork), also wait until its copy is in durable storage.',
+            inputSchema: obj({
+                operation_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Operation id (UUID).' },
+                durable: { type: 'boolean', description: 'A suspend or fork: also wait until result durable is true.' },
+            }, ['operation_id']),
             annotations: { readOnlyHint: true, openWorldHint: false },
-            run: async (args, call) => ({ operation: summarizeOperation(await wait(call, String(args.operation_id))) }),
+            run: async (args, call) => {
+                if (args.durable !== true)
+                    return { operation: summarizeOperation(await wait(call, String(args.operation_id))) };
+                call.timed = true;
+                call.operationId = String(args.operation_id);
+                return { operation: summarizeOperation(await cloud.workspaces.waitForDurable(String(args.operation_id), waitOpts(call))) };
+            },
         },
         {
             name: 'template_get',
@@ -982,7 +1065,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         if (mode !== undefined)
             listedMode = mode;
         const fileFirst = mode === 'file_first';
-        const mgmt = fileFirst ? management.filter((d) => !VM_ONLY_MANAGEMENT.has(d.name)) : management;
+        const mgmt = management.filter((d) => (!fileFirst || !VM_ONLY_MANAGEMENT.has(d.name)) && (d.permission === undefined || permitted.includes(d.permission)));
         const tools = (fileFirst ? fileFirstDefs : workspaceDefs).filter((d) => d.permission !== undefined && permitted.includes(d.permission));
         return { tools: [...mgmt, ...tools].map(toMcpTool) };
     });
@@ -1015,7 +1098,7 @@ 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 });
-            const notice = call.timed && call.timing ? processRestartNotice(call.timing) : undefined;
+            const notice = call.timed && call.timing ? timingNotice(call.timing) : undefined;
             return okResult(call.timed && call.timing && isObject(value) ? { ...value, timing: compactTiming(call.timing), ...(notice ? { notice } : {}) } : value);
         }
         catch (err) {
@@ -1055,7 +1138,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     ? { feedback: feedbackSuggestion(info) }
                     : {};
             // 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;
+            const notice = call.timed && call.timing ? timingNotice(call.timing) : undefined;
             return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined, { ...siblings, ...(notice ? { notice } : {}) });
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/mcp",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "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.11.1"
+    "@shardflux/sdk": "^0.12.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",