@shardflux/mcp 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 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.1 (not yet published; npm `latest` is 0.4.0)
+
+A command that could not start (through `@shardflux/sdk` 0.10.0, `ExecStartError`):
+
+- `exec` on a processful workspace: a command that could not start (a `cwd` that is not a directory, a program not on
+  `PATH`) returns `error: { code: "conflict", message, reason: "exec_failed_to_start" }` with `exit_code: null`, the
+  message carrying the workspace's reason (`The command could not start: working directory "/home/user/app" is not a
+  directory`), as a failed file-first execution does. It returned `exit_code: null` and empty output with no reason.
+- A relative `cwd` is refused by the API before anything runs: an error result with `code` `validation_failed`,
+  `details.reason` `invalid_cwd` and a message naming the absolute path it likely means (`use "/home/user/app"`).
+
+Opt-in overage with a spend cap (through `@shardflux/sdk` 0.10.0):
+
+- `usage_summary` returns the summary's `spend_cap` (overage state, cap, charges, lines per allowance, projected date)
+  and `exhausted_reason`, and allowances past `included` while overage is on have `cap_state: "overage"`. Its
+  description says so and names the 402 reasons.
+- A start refused with 402 `allowance_exhausted` comes back with `reason` `allowance_used`, `overage_paused` or
+  `spend_cap_reached` and `details.spend_cap` (errors already carried `details`).
+
+Suspend when idle (contracts §20.6):
+
+- `workspace_suspend` takes an optional `after_seconds` (30-3600): suspend when idle instead of now. The workspace is
+  suspended once it has been idle that long; the agent's next tool call on it cancels that, and a running command or a
+  keepalive postpones it. The tool description and the server instructions tell an agent to use it when it finishes
+  its work. The result has `suspend_request`, `operation` (a suspend already in progress, else null) and a `message`
+  saying what happens. `after_seconds` with `wait: true` is refused (`invalid_arguments`).
+- Workspace summaries (`workspace_status`, `workspace_list`, `workspace_open`) carry `suspend_request`: the pending
+  request, or null.
+
 ## 0.4.0 (not yet published; npm `latest` is 0.3.1)
 
 Needs `@shardflux/sdk` 0.9.0 (the workspace version).

package/README.md

@@ -227,8 +227,11 @@ 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_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. |
+
 | `usage_summary` | The organization's usage summary for the current period. |
 | `send_feedback` | (0.4.0) Feedback straight to the Shardflux founder: `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. |
@@ -238,7 +241,7 @@ The management tools:
 The SDK's workspace tools come from `workspaceTools()`:
 
 - `exec`
-- `read_file`, `write_file`, `list_files`, `search_files`, `edit_file` (0.3.0+)
+- `read_file`, `write_file`, `list_files`, and `search_files`, `edit_file` (0.4.0+)
 - `list_processes`, `signal_process`
 - `terminal_open`, `terminal_send`, `terminal_read`, `terminal_close`
 - `git_clone`, `git_status`, `git_commit`
@@ -247,7 +250,10 @@ The SDK's workspace tools come from `workspaceTools()`:
 They are published with **the SDK's JSON Schemas verbatim**, plus `workspace_key` and, where the
 SDK schema has none, `timeout_ms`. They are filtered by the key's tool permissions (if the server
 cannot read them, for example because the API is unreachable, it lists every workspace tool and logs
-a warning). `browser_screenshot` returns an MCP image content block. `search_files` is annotated read-only; `edit_file` replaces
+a warning). `exec`'s `cwd` is an absolute path (default `/home/user`): a relative one is an error result with
+`details.reason: invalid_cwd` whose message names the absolute path it likely means, and a command that could not
+start (a `cwd` that is not a directory, a program not on `PATH`) returns `exit_code: null` with `error: { code,
+message, reason: "exec_failed_to_start" }` naming the workspace's reason (0.4.1+). `browser_screenshot` returns an MCP image content block. `search_files` is annotated read-only; `edit_file` replaces
 exact text and, without an `expected_revision`, reads the file's revision first so a concurrent change fails the
 edit (`conflict`, `details.reason: revision_mismatch`) instead of being overwritten.
 
@@ -322,6 +328,11 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
   - A failed operation is `code: operation_failed` with `details.error_code` (and `details.reason` when the
     operation error has one) and, from 0.2.1, `retryable`: the operation error's own flag.
   - An API or cell gateway the server cannot reach is `code: network_error`, `retryable: true`.
+  - A start refused because an allowance is used up is `code: allowance_exhausted` (402) with `reason` (0.4.1+):
+    `allowance_used` (upgrade, or turn on overage), `overage_paused` (a plan payment is past due) or
+    `spend_cap_reached` (raise the spend cap or upgrade), and `details.spend_cap`. An owner or billing member acts
+    on it in the console; retrying does not help.
+
   - **(0.4.0+)** A failed call has a `feedback` field next to `error`: a one-sentence suggestion to call
     `send_feedback` with category `bug`, the `request_id` and the error code. Not for `invalid_arguments`,
     `workspace_pinned` or `unauthenticated`. A failed `send_feedback` carries a `hint` instead (when to retry, or the

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.0";
+export declare const MCP_SERVER_VERSION = "0.4.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[];
@@ -75,6 +75,12 @@ export declare function summarizeWorkspace(v: WorkspaceView): {
         operation_id: string | null;
         at: string | null;
     } | null;
+    /** A pending suspend-when-idle request (workspace_suspend with after_seconds); null when none. */
+    suspend_request: {
+        requested_at: string;
+        after_seconds: number;
+        not_before: string;
+    } | null;
     created_at: string;
     deleted_at: string | null;
     tree_revision?: number | undefined;

package/dist/server.js

@@ -2,8 +2,9 @@
  * Local stdio MCP server for Shardflux workspaces. It translates MCP tool
  * calls into @shardflux/sdk calls made with the supplied scoped API key:
  *
- *   - workspace management: workspace_open / _list / _status / _suspend /
- *     _resume / _fork, operation_wait, usage_summary;
+ *   - workspace management: workspace_open / _list / _status / _suspend
+ *     (now, or with after_seconds once idle: suspend-when-idle) / _resume /
+ *     _fork, operation_wait, usage_summary;
  *   - templates (0.3.0): template_get (versions, settings, a version's recipe), template_languages and
  *     template_build (a recipe v2 object or a template.yaml path inside the
  *     server's working directory; local `from` paths are uploaded by the SDK);
@@ -52,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.0';
+export const MCP_SERVER_VERSION = '0.4.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}`;
@@ -134,6 +135,8 @@ export function summarizeWorkspace(v) {
         ended_reason: v.ended_reason,
         /** Start commands and services of the template version; null when it has none. */
         startup: v.startup ?? null,
+        /** A pending suspend-when-idle request (workspace_suspend with after_seconds); null when none. */
+        suspend_request: v.idle?.suspend_request ?? null,
         created_at: v.created_at,
         deleted_at: v.deleted_at,
     };
@@ -278,6 +281,7 @@ const INSTRUCTIONS = [
     'Shardflux persistent remote workspaces (Linux computers that keep files, packages and processes between sessions).',
     'Call workspace_open first (it creates the workspace on first use and reconnects afterwards, never resetting it), then use exec, read_file, write_file and the other workspace tools with the same workspace_key.',
     'Lifecycle calls return operations; operation_wait keeps waiting. Workspace tools resume a suspended workspace on use (read_file, list_files and search_files read its disk without resuming it when they can); if that takes too long the error (code timeout) names the operation to pass to operation_wait. Errors are tool results with error.code from the Shardflux API.',
+    '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.',
     '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).',
@@ -616,7 +620,51 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 return { workspace: summarizeWorkspace(ws.data), recent_operations: ops.data.map(summarizeOperation) };
             },
         },
-        lifecycleTool('workspace_suspend', 'Suspend workspace', 'Suspend a running workspace (durable full-state checkpoint; processes stop). Returns the suspend operation (with wait: once finished, and its timing). Not for file-first workspaces (never suspended).', 'suspend', (ws, o) => cloud.workspaces.suspend(ws.id, o)),
+        {
+            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). ' +
+                '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({
+                workspace_key: workspaceKeyProp(pinned),
+                after_seconds: {
+                    type: 'integer',
+                    minimum: 30,
+                    maximum: 3600,
+                    description: 'Suspend once the workspace has been idle this many seconds (30-3600) instead of now. Omit to suspend now.',
+                },
+                wait: { type: 'boolean', description: 'Wait until the suspend finishes (default false). 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.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.');
+                }
+                const key = keyOf(args);
+                const ws = await resolve(key, { signal: call.signal });
+                if (ws.mode === 'file_first') {
+                    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));
+                    call.operationId = op.id;
+                    return { operation: summarizeOperation(op) };
+                }
+                const r = await ws.suspendWhenIdle({ afterSeconds });
+                if (r.operation)
+                    call.operationId = r.operation.id;
+                return {
+                    suspend_request: r.suspendRequest,
+                    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.`
+                        : `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', 
         // 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.
@@ -728,7 +776,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         {
             name: 'usage_summary',
             title: 'Usage summary',
-            description: 'Usage of the organization in the current billing period: each meter’s raw, billable and included quantity and cap state.',
+            description: 'Usage of the organization in the current billing period: each meter’s raw and billable quantity; each allowance’s included, used and remaining amount and cap_state (overage: past the allowance while opt-in overage is on, charged under the spend cap); allowance_exhausted with exhausted_reason; and spend_cap (opt-in overage: state, cap_minor, effective_cap_minor, charges_minor, remaining_minor, lines per allowance, projected_reached_at; amounts in cents). While an allowance is used up, opens and resumes fail with code allowance_exhausted and reason allowance_used (upgrade, or turn on overage), overage_paused (a plan payment is past due) or spend_cap_reached (raise the cap or upgrade): an owner or billing member acts in the console, and retrying does not help.',
             inputSchema: obj({ organization_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Organization id (default: the API key’s organization).' } }),
             annotations: { readOnlyHint: true, openWorldHint: false },
             run: async (args, call) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/mcp",
-  "version": "0.4.0",
+  "version": "0.4.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.",
@@ -42,7 +42,7 @@
     "@modelcontextprotocol/sdk": "1.30.0",
     "yaml": "2.9.1",
     "zod": "4.6.5",
-    "@shardflux/sdk": "^0.9.0"
+    "@shardflux/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",