@shardflux/mcp 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -3,6 +3,126 @@
 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).
+
+File-first workspaces (contracts §29):
+
+- `workspace_open` takes `mode` (`processful` | `file_first`); `SHARDFLUX_WORKSPACE_MODE` sets the default. Workspace
+  results (`workspace_open`, `workspace_status`, `workspace_list`) carry `mode` and, for file-first workspaces,
+  `tree_revision`.
+- `exec` on a file-first workspace runs an execution (the SDK's file-first tool): the result adds `execution_id`,
+  `state`, `tree_revision` and `changed`. A call whose deadline passes before the execution ended returns an error
+  naming the `execution_id` (it cannot be canceled and continues server side).
+- A pinned server lists only the tools its workspace's mode has (file-first: the files tools and `exec`, no process,
+  terminal, git or browser tools, no `workspace_suspend`, `workspace_resume`, `workspace_fork` or `operation_wait`)
+  and sends `notifications/tools/list_changed` (capability `tools.listChanged`) when the known mode changes what it
+  listed. An unpinned server lists every tool; a tool the named workspace's mode lacks is refused before any request
+  (`conflict`, `reason: not_supported_for_mode`, with a `hint`), and so are suspend, resume and fork of a file-first
+  workspace.
+- Error results carry `reason` (the refusal's `details.reason`) and, for the file-first refusals, a `hint`:
+  `not_supported_for_mode`, `mode_mismatch`, `mode_not_available`, `layout_unsupported`, `tree_revision_mismatch` (with
+  `current_tree_revision`), `outside_tree_root`, `execution_in_progress`, `execution_id_reused`, `no_execution_host`.
+- The server instructions describe file-first workspaces.
+
+Waking a suspended workspace is one request (contracts §22.6, through `@shardflux/sdk` 0.9.0):
+
+- A workspace tool on a suspended workspace wakes it with one held resume that returns the running workspace and this
+  server's tool token (its agent label), then runs the tool; the wake's `timing` is one `request(held)` phase. An API
+  without the held resume works as before.
+- `workspace_resume` with `wait` goes through the server's workspace handle: one held request, after which the handle
+  holds the view and the token, so the next workspace tool starts without a token request.
+
+File tools and the wake hint (contracts §26):
+
+- `search_files` (read-only) and `edit_file` come from the SDK's `workspaceTools()` with its schemas, plus
+  `workspace_key` and `timeout_ms`, filtered by the `files` permission. The server instructions describe them.
+- Every workspace tool call first sends the wake hint through the SDK's tool runner (`workspace.hint()`,
+  fire-and-forget; a suspended workspace starts resuming in the background, bounded like any wake by
+  `SHARDFLUX_WAKE_TIMEOUT_MS` and the call's deadline), except `read_file`, `list_files` and `search_files`.
+- `read_file`, `list_files` and `search_files` of a suspended workspace whose disk a host still holds are answered
+  from that disk without resuming it (contracts §26.4), also as the first call after the suspend: the API now issues
+  tool tokens for suspended workspaces. Every other tool still resumes it. With an older API they resume it as before.
+- A workspace on a host that predates search and patches (contracts §26.7, while the fleet is upgraded):
+  `search_files` and `edit_file` return `conflict`, `reason: host_feature_unavailable` (`details.feature`
+  `file_search` or `file_patch`), `retryable: false`, with a `hint` naming another way (`exec` with `grep`;
+  `read_file` then `write_file`). They work once the workspace runs on an upgraded host. `hostFeatureHint()` is
+  exported next to `modeHint()`.
+- New refusals come back as error results with their `details.reason`: `revision_mismatch` (with
+  `current_revision`), `edit_not_found` / `edit_ambiguous` (with `index`), `host_capacity` (retryable). A read of a
+  sleeping workspace its disk cannot answer (`offline_unavailable`, `offline_budget`) wakes it like any
+  `workspace_not_running`; `offline_changed` (503) is retried.
+
+Version check (contracts §30.4; needs an API that serves `GET /v1/client-versions`):
+
+- Version check at startup: after the configuration is validated, the server asks `GET /v1/client-versions` (through
+  its own fetch, the SDK's `checkClientVersion`: one request, 3 s timeout, never awaited by the protocol) whether
+  `@shardflux/mcp` at its version is current. Outdated or unsupported: one `warn` JSON line on stderr with the notice
+  (`@shardflux/mcp 0.4.0 is outdated: 0.5.0 is available. Update: npm install -g @shardflux/mcp@latest`) and
+  `status`, `package`, `current`, `latest`, `minimum_supported`, `upgrade_command`, `release_notes_url`. Everything
+  else is a `debug` line: current, not listed, `latest: null`, or the request failed. Off with `SHARDFLUX_NO_UPDATE_CHECK=1` (also `true`, `yes`, `on`),
+  `NO_UPDATE_NOTIFIER=1`, or `createShardfluxMcpServer(config, { versionCheck: false })`. `checkServerVersion()` and
+  `MCP_PACKAGE` are exported.
+- The notice is not added to the server instructions: they are fixed when the server is built and the handshake does
+  not wait for the check, so over stdio the client's `initialize` is answered before the check could finish.
+- The SDK client the server builds passes `versionCheck: false`: the SDK ships inside the server, so its own warning
+  (about `@shardflux/sdk`, with an `npm install @shardflux/sdk@latest` hint a server user cannot act on) would be
+  noise, and `process.emitWarning` would put a non-JSON line on stderr.
+- Server instructions: account-level actions (registering, signing in, organizations, projects, API keys, members,
+  billing and plan upgrades, spend alerts, audit export) are done with the `shard` CLI (`npx @shardflux/cli@latest
+  --help`; `shard auth login`, `shard setup`, `shard billing upgrade <plan>`). The server gets no account tools: it
+  authenticates with a project API key, which the API refuses for account actions (403 `forbidden` on the account
+  routes, 401 on the `/v1/auth` session routes); they need a person's session (`sfu_...`), which the CLI signs in.
+
+### send_feedback: feedback straight to the founder (needs an API with POST /v1/feedback)
+
+- New management tool `send_feedback` (`message`, `category`: bug, confusing, missing, idea, praise or other; optional
+  `workspace`, `request_id`, `error_code`, `command`). It calls the SDK's `sendFeedback()` with `client:
+  shardflux-mcp/0.4.0` and, as `agent`, the MCP client's name/version from `initialize` (else a non-default
+  `SHARDFLUX_AGENT_LABEL`); a pinned server fills `workspace` with its key. Result: `{id, received_at, duplicate,
+  note}`. Always listed (any API key may send feedback).
+- The server instructions and the tool description ask the agent to call it actively while it works: the moment a
+  call fails unexpectedly, an error or doc is confusing, something is missing or slow, or it needed a workaround, and
+  when its user is frustrated about Shardflux or asked for something it could not do (paraphrased, without private
+  data; the agent tells its user it sent feedback).
+- Failed calls carry a `feedback` field next to `error`, except the expected flow: `invalid_arguments`,
+  `workspace_pinned`, `unauthenticated`, `validation_failed`, `timeout`, and refusals whose error names the next step
+  (a stale revision, an edit that does not match, a mode the workspace lacks, a reused execution id). The field is a
+  suggestion to call `send_feedback` with category `bug`, the request id and the error code. A failed
+  `send_feedback` carries a `hint` (when to retry after `rate_limited`, or email shardflux@heliosone.fi). Additive:
+  `error` and `timing` are unchanged.
+- `tools/list` has 12 management tools (was 11). `server.json` names 0.4.0.
+
 ## 0.3.1 (2026-09-28)
 
 Needs `@shardflux/sdk` 0.8.0 or later. No tool changes: the server moves to the SDK's 0.8.0 (a types-only release whose

package/README.md

@@ -157,12 +157,15 @@ environment `SHARDFLUX_API_KEY`.
 | `SHARDFLUX_API_URL` | Default `https://api.shardflux.dev`. Plain `http://` is allowed only for loopback hosts. |
 | `SHARDFLUX_WORKSPACE_KEY` | Pins one workspace. `workspace_key` becomes optional on every tool, and a different key is refused with `workspace_pinned`. |
 | `SHARDFLUX_TEMPLATE` | Default template for `workspace_open`. |
+| `SHARDFLUX_WORKSPACE_MODE` | (0.4.0) `processful` or `file_first`: the `mode` `workspace_open` sends when the call names none (unset: the API's default, processful for a new key). A pinned server also lists the tools of this mode until its workspace exists. |
 | `SHARDFLUX_MCP_TOOL_TIMEOUT_MS` | Default **and maximum** deadline per tool call, 1000-3600000 ms. Default 120000. A call's `timeout_ms` can only shorten it. |
 | `SHARDFLUX_WAKE` | `on` (default) or `off`. On: workspace tools resume a suspended workspace and then run (see "Contract"). Off: they return the `workspace_not_running` refusal. |
 | `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`), because on some Node.js releases a request sent on a reused keep-alive connection can stall until the request timeout. |
+| `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. |
 
 Invalid configuration exits with code 2 before serving, with one JSON line on stderr, for example:
 
@@ -173,19 +176,64 @@ Invalid configuration exits with code 2 before serving, with one JSON line on st
 `template_build` reads local files (`file`, and `from` paths in a recipe) only inside the server's
 working directory: the directory your MCP client starts it in.
 
+## Feedback: agents are asked to use `send_feedback` while they work
+
+**(0.4.0+)** The `send_feedback` tool sends a message straight to the Shardflux founder, who reads every one. The
+server instructions and the tool description ask the agent to call it actively during its work, not once at the end:
+the moment a call fails unexpectedly, an error or doc is confusing, something is missing or slow, or it needed a
+workaround; when its user complains or is frustrated about Shardflux or the workflow around it (paraphrased, with what
+they were trying to do); and when its user asked for something Shardflux could not do, or made awkward. Short and
+frequent beats polished, with the `request_id` and error code from the error. The agent tells its user it sent
+feedback, and leaves out private data about the user and secrets or code they did not mean to share (paraphrase, never
+transcripts). Failed calls carry a ready-made suggestion in a `feedback` field (see "Contract").
+
+- Arguments: `message` (1-8000 characters) and `category` (`bug`, `confusing`, `missing`, `idea`, `praise`, `other`),
+  plus optional `workspace` (default: the pinned key), `request_id`, `error_code` and `command`.
+- The server adds `client: shardflux-mcp/<version>` and, as `agent`, the MCP client's name and version from
+  `initialize` (e.g. `claude-code/2.1.0`; without one, `SHARDFLUX_AGENT_LABEL` when it is not the default `mcp`).
+- Result: `{id, received_at, duplicate, note}`. `duplicate: true`: the same message from this key in the last 24 hours;
+  it is not emailed again.
+- Any API key may send it (no tool permission), so it is always listed. It is rate limited per key: `rate_limited`
+  with `details.retry_after_seconds`, and a `hint` naming the wait and the fallback address, shardflux@heliosone.fi.
+
+## Updates (0.4.0+)
+
+At startup, after the configuration is validated, the server asks the API's `GET /v1/client-versions` whether
+`@shardflux/mcp` at its version is current. It sends one request (3 s timeout) in the background: the MCP handshake
+and tool calls never wait for it, and any failure is ignored. When the server is outdated, or below the oldest version
+the API still supports, it logs one `warn` line on stderr:
+
+```json
+{"time":"2026-10-01T09:00:00.000Z","level":"warn","service":"shardflux-mcp","message":"@shardflux/mcp 0.4.0 is outdated: 0.5.0 is available. Update: npm install -g @shardflux/mcp@latest","status":"outdated","package":"@shardflux/mcp","current":"0.4.0","latest":"0.5.0","minimum_supported":"0.1.0","upgrade_command":"npm install -g @shardflux/mcp@latest","release_notes_url":"https://www.npmjs.com/package/@shardflux/mcp?activeTab=versions"}
+```
+
+- An unsupported server says `... is no longer supported by the Shardflux API (minimum <version>). Update: ...`
+  (`"status":"unsupported"`). It keeps running.
+- Otherwise it stays silent (one `debug` line), also when the API does not answer.
+- The server instructions do not carry the notice: they are fixed when the server is built, and the handshake does not
+  wait for the check.
+- `SHARDFLUX_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` turns the check off; `createShardfluxMcpServer(config,
+  { versionCheck: false })` does too.
+- The `@shardflux/sdk` client inside the server runs no check of its own (`versionCheck: false`). The SDK ships inside
+  the server, so the update to install is the server's.
+
 ## Tools
 
 The management tools:
 
 | Tool | Does |
 | --- | --- |
-| `workspace_open` | Open by key: create on first use, reconnect or resume afterwards, never reset. Waits until the workspace is ready (its template's start commands and services included) unless `wait: false`. `lifetime: "session"` opens a workspace that is discarded after its idle timeout. `inputs` (0.3.0) passes the template's text inputs, `{"NAME": "value"}`. |
+| `workspace_open` | Open by key: create on first use, reconnect or resume afterwards, never reset. Waits until the workspace is ready (its template's start commands and services included) unless `wait: false`. `lifetime: "session"` opens a workspace that is discarded after its idle timeout. `inputs` (0.3.0) passes the template's text inputs, `{"NAME": "value"}`. `mode` (0.4.0): `processful` or `file_first` (see "File-first workspaces"). |
 | `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. |
 | `template_languages` | (0.3.0) The languages and versions a base (`<slug>@<version>`) offers `build.languages`. |
 | `template_build` | (0.3.0) Build a version of an organization template from a recipe v2: `recipe` (the document) or `file` (a template.yaml or .json path). File entries may name local `from` paths, uploaded first (folders as a tar). **Every local path must resolve inside the server's working directory**; others are refused before any request. Unpublished unless `publish: true`; `wait: true` follows the build within the call's deadline. |
@@ -193,7 +241,7 @@ The management tools:
 The SDK's workspace tools come from `workspaceTools()`:
 
 - `exec`
-- `read_file`, `write_file`, `list_files`
+- `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`
@@ -202,16 +250,73 @@ 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.
+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.
+
+Each workspace tool call first sends the wake hint (`POST /wake-hint`, without waiting for it): a workspace its host
+has parked starts restoring while the call is prepared, and a suspended one starts resuming. `read_file`,
+`list_files` and `search_files` send none (0.4.0+): a suspended workspace whose disk its host still holds is read,
+listed and searched there without resuming it (the state at suspension).
+
+While the fleet is being upgraded a workspace may run on a host that predates `search_files` and `edit_file`: they
+fail with `conflict`, `reason: host_feature_unavailable` (`details.feature` `file_search` or `file_patch`),
+`retryable: false` and a `hint` naming another way (`exec` with `grep`; `read_file` then `write_file`). It lasts
+until the workspace runs on an upgraded host.
 
 Deleting a workspace is deliberately not exposed to agents; use the
 [CLI](https://www.npmjs.com/package/@shardflux/cli) or the console.
 
+Account-level actions are not tools either: registering, signing in, organizations, projects, API keys, members,
+invitations, billing and plan upgrades, spend alerts and the audit export. The server authenticates with a project API
+key, and the API refuses a project API key for them: 403 `forbidden` ("API keys cannot perform this action.") on the
+account routes, 401 on the `/v1/auth` session routes. They need a person's session. From 0.4.0 the server instructions tell the agent to use the `shard` CLI for them
+(`npx @shardflux/cli@latest --help`; for example `shard auth login`, `shard setup`, `shard billing upgrade <plan>`),
+which signs a person in with a CLI session.
+
 Every tool finds its workspace by exact key across every lifetime and purpose, so sessions, template drafts and test
 instances resolve too. The live workspace wins over tombstones that ended sessions left with the same key. Workspace
 results include `lifetime`, `purpose`, `disk_layout`, `idle_timeout_seconds`, `ended_reason` and (0.3.0) `startup`:
 the state of the template's start commands and services (`failed` names the step, its exit code and output tail).
 
+### File-first workspaces (0.4.0)
+
+`workspace_open` with `mode: "file_first"` (or `SHARDFLUX_WORKSPACE_MODE=file_first`) opens a file-first workspace
+(contracts §29): a versioned file tree under /home/user with no VM between calls. It is ready at once and never
+suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_revision`.
+
+- `exec` runs each command as an execution: a fresh VM on the workspace's files. Only files under /home/user persist
+  between calls. The result adds `execution_id`, `state`, `tree_revision` and `changed` (the paths the command added,
+  modified or deleted, up to 200, with `changed_truncated`). An execution cannot be canceled: when the call's
+  deadline passes first, the error carries its `execution_id` and the execution continues server side.
+- The files tools work as on a processful workspace. Each change publishes the next tree revision.
+- The process, terminal, git and browser tools and `workspace_suspend`, `workspace_resume`, `workspace_fork` and
+  `operation_wait` do not apply. A **pinned** server lists only the tools of its workspace's mode: the mode of the
+  pinned key once it is known, else `SHARDFLUX_WORKSPACE_MODE`, else processful. When the known mode changes what it
+  listed (for example the pinned key is opened file-first after the first `tools/list`), it sends
+  `notifications/tools/list_changed`. An unpinned server lists every tool; calling one the named workspace's mode
+  lacks returns an error with `reason: "not_supported_for_mode"` and a `hint`, before any request.
+- Errors of file-first workspaces carry `reason` and a `hint`: `not_supported_for_mode`, `mode_mismatch` (a key's
+  mode never changes), `mode_not_available` (the deployment does not offer file-first workspaces), `layout_unsupported`
+  (a legacy template), `tree_revision_mismatch` (with `current_tree_revision`), `outside_tree_root`,
+  `execution_in_progress` (another execution holds the workspace), `execution_id_reused` and `no_execution_host` (no
+  host had room, also after the SDK's retries with the same execution id; nothing ran).
+
+```json
+{
+  "mcpServers": {
+    "shardflux": {
+      "command": "node",
+      "args": ["/path/to/packages/mcp/src/bin.ts"],
+      "env": { "SHARDFLUX_API_KEY": "sfk_...", "SHARDFLUX_WORKSPACE_KEY": "me/agent-files", "SHARDFLUX_TEMPLATE": "python-node-browser", "SHARDFLUX_WORKSPACE_MODE": "file_first" }
+    }
+  }
+}
+```
+
 ## Contract
 
 - **Arguments.** They are validated against the published schema with the SDK's `validateArgs`
@@ -223,6 +328,15 @@ the state of the template's start commands and services (`failed` names the step
   - 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
+    email address).
 - **Starts wait for capacity for at most 15 minutes (0.2.1+).** An open, resume or fork that no host can admit waits
   in `capacity_pending`; a wait that ends first returns `code: timeout`, and its message names when the start gives
   up. A start still pending then fails: `operation_failed`, `details.error_code: capacity_unavailable`,
@@ -259,10 +373,13 @@ the state of the template's start commands and services (`failed` names the step
   HTTP requests to the API and to the cell gateway, and backoff sleeps. No response is sent, and
   the server stays up. The lifecycle operation itself is not canceled.
 - **Workspace tools wake suspended workspaces, but do not open new ones.** A workspace that was
-  never opened is `not_found`: call `workspace_open` first.
+  never opened is `not_found`: call `workspace_open` first. Reads (`read_file`, `list_files`,
+  `search_files`) of a suspended workspace whose disk a host still holds are answered from that disk
+  without waking it.
   - A suspended workspace is resumed (or the resume or open already running is joined), and the
     call runs once it is running. A call made during a suspend or resume waits for it to finish.
-    The call never runs twice: the refused attempt did nothing.
+    The call never runs twice: the refused attempt did nothing. The resume is one request held until
+    the workspace runs, answered with this server's tool token (0.4.0+, an API with the held resume).
   - The wait is bounded by `SHARDFLUX_WAKE_TIMEOUT_MS` and the call's deadline. Past it the
     result is `code: timeout` with the `operation_id` and `last_state` of the resume or open. That
     operation continues server side: `operation_wait` keeps waiting. A resume or open that fails

package/dist/config.d.ts

@@ -2,6 +2,7 @@
  * Environment configuration of the local MCP server (README "Configuration").
  * The API key is validated for shape only here; it is never logged or echoed.
  */
+import type { WorkspaceMode } from '@shardflux/sdk';
 export interface McpConfig {
     apiKey: string;
     apiUrl: string;
@@ -9,6 +10,11 @@ export interface McpConfig {
     workspaceKey: string | undefined;
     /** Template used by workspace_open when the call names none. */
     template: string | undefined;
+    /**
+     * SHARDFLUX_WORKSPACE_MODE (0.4.0): the mode workspace_open sends when the call names none (unset: none, the API's
+     * default), and the mode tools/list assumes for a pinned key that does not exist yet. Optional for embedders.
+     */
+    workspaceMode?: WorkspaceMode | undefined;
     /** Default and maximum per-call deadline (ms). */
     toolTimeoutMs: number;
     /** Workspace tools resume a suspended workspace on use (SHARDFLUX_WAKE, default on). */

package/dist/config.js

@@ -1,7 +1,3 @@
-/**
- * Environment configuration of the local MCP server (README "Configuration").
- * The API key is validated for shape only here; it is never logged or echoed.
- */
 export class ConfigError extends Error {
     name = 'ConfigError';
 }
@@ -42,6 +38,10 @@ export function loadConfig(env) {
     const template = env.SHARDFLUX_TEMPLATE?.trim() || undefined;
     if (template !== undefined && !SLUG.test(template))
         throw new ConfigError('SHARDFLUX_TEMPLATE must be a template slug (lowercase letters, digits, . _ -)');
+    const modeText = env.SHARDFLUX_WORKSPACE_MODE?.trim().toLowerCase() || undefined;
+    if (modeText !== undefined && modeText !== 'processful' && modeText !== 'file_first')
+        throw new ConfigError('SHARDFLUX_WORKSPACE_MODE must be processful or file_first');
+    const workspaceMode = modeText;
     let toolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS;
     const t = env.SHARDFLUX_MCP_TOOL_TIMEOUT_MS?.trim();
     if (t) {
@@ -71,5 +71,5 @@ export function loadConfig(env) {
     const level = (env.SHARDFLUX_MCP_LOG_LEVEL?.trim() || 'info');
     if (!['debug', 'info', 'warn', 'error'].includes(level))
         throw new ConfigError('SHARDFLUX_MCP_LOG_LEVEL must be debug, info, warn or error');
-    return { apiKey, apiUrl: apiUrlFrom(env.SHARDFLUX_API_URL), workspaceKey, template, toolTimeoutMs, wake: wakeText === 'on', wakeTimeoutMs, agentLabel, logLevel: level };
+    return { apiKey, apiUrl: apiUrlFrom(env.SHARDFLUX_API_URL), workspaceKey, template, workspaceMode, toolTimeoutMs, wake: wakeText === 'on', wakeTimeoutMs, agentLabel, logLevel: level };
 }

package/dist/errors.d.ts

@@ -8,17 +8,41 @@ export declare class ToolError extends Error {
 export interface ToolErrorInfo {
     code: string;
     message: string;
+    /** details.reason of an API or cell refusal (0.3.0). */
+    reason?: string;
     status?: number;
     request_id?: string;
     retryable?: boolean;
     operation_id?: string;
+    /** A file-first exec whose call ended before its execution did: the execution continues server side (0.4.0). */
+    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';
     details?: Record<string, unknown>;
     issues?: string[];
     last_state?: string;
+    /** What to do instead (0.4.0): refusals that concern a workspace's mode (contracts §29) or a host that predates a tool (§26.7). */
+    hint?: string;
 }
 export declare function redact(text: string, key?: string): string;
-export declare function describeToolError(err: unknown, context?: {
+/**
+ * What the model can do about a refusal that concerns a workspace's mode (contracts §29.7, §29.8), from its
+ * details.reason and details; undefined for every other refusal.
+ */
+export declare function modeHint(reason: string | undefined, details?: Record<string, unknown>): string | undefined;
+/**
+ * 409 conflict host_feature_unavailable (contracts §26.7; 0.4.0): the workspace runs on a host that predates the tool,
+ * until it runs on an upgraded host (minutes to hours). Not retryable, so the hint names another way to do it now.
+ */
+export declare function hostFeatureHint(reason: string | undefined, details?: Record<string, unknown>): string | undefined;
+export interface DescribeContext {
     operationId?: string | undefined;
     timeoutMs?: number;
-}): ToolErrorInfo;
+    /**
+     * The execution id a file-first exec call sent (the SDK's onExecution). Named in deadline, network and protocol
+     * errors, after which the execution may be running server side; an API refusal leaves the id unused and omits it.
+     */
+    executionId?: string | undefined;
+}
+export declare function describeToolError(err: unknown, context?: DescribeContext): ToolErrorInfo;

package/dist/errors.js

@@ -2,8 +2,12 @@
  * Tool errors are returned as MCP tool results (`isError: true`) whose
  * content is `{ "error": { code, message, ... } }` with the API's closed error
  * code, never as protocol failures, so the calling model can react to them.
+ * API and cell refusals add `reason` (their details.reason) and, for refusals
+ * that concern a workspace's mode (file-first workspaces, contracts §29) or a
+ * host that predates a tool (host_feature_unavailable, contracts §26.7), a
+ * `hint` saying what to do instead.
  */
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateUploadError, ToolArgumentError } from '@shardflux/sdk';
+import { 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';
@@ -23,17 +27,84 @@ export function redact(text, key) {
     return out;
 }
 const named = (err, name) => typeof err === 'object' && err !== null && err.name === name;
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+/** The tools a file-first workspace has, for hints. */
+const FILE_FIRST_TOOLS_TEXT = 'Run commands with exec and use read_file, write_file, list_files, search_files and edit_file for files; only files under /home/user persist between exec calls.';
+/**
+ * What the model can do about a refusal that concerns a workspace's mode (contracts §29.7, §29.8), from its
+ * details.reason and details; undefined for every other refusal.
+ */
+export function modeHint(reason, details = {}) {
+    const mode = str(details.mode);
+    switch (reason) {
+        case 'not_supported_for_mode':
+            if (mode === 'processful')
+                return 'This workspace is processful: exec runs commands in its own VM, where files, packages and processes persist; executions and tree revisions exist only for file-first workspaces.';
+            if (details.field === 'lifetime')
+                return 'A file-first workspace is persistent: open it without lifetime "session", or use mode "processful" for a session workspace.';
+            if (details.field === 'idle_policy')
+                return 'A file-first workspace is never suspended, so it has no idle policy: open it without one.';
+            return `This workspace is file-first: it has no VM between exec calls, so processes, terminals, version control sessions and browsers do not outlive one exec call, and it is never suspended, resumed or forked. ${FILE_FIRST_TOOLS_TEXT} Start servers, run git or a headless browser within the exec command that needs them.`;
+        case 'mode_mismatch': {
+            const requested = str(details.requested_mode);
+            return mode
+                ? `A workspace's mode never changes: this key belongs to a ${mode} workspace. Open it with mode "${mode}"${requested ? `, or use another key for a ${requested} workspace` : ''}.`
+                : "A workspace's mode never changes: open this key with the mode it was created with, or use another key.";
+        }
+        case 'mode_not_available':
+            return 'This deployment does not offer file-first workspaces yet: open the workspace with mode "processful" (or without mode).';
+        case 'layout_unsupported':
+            return mode === 'file_first'
+                ? 'File-first workspaces run on layered template versions and this one is not: pick another template (template_get lists its versions and disk_layouts) or open with mode "processful".'
+                : 'This template version needs a disk layout this deployment does not offer: pick another template version (template_get lists them with their disk_layouts).';
+        case 'tree_revision_mismatch':
+            return `The workspace's files changed since that tree revision${typeof details.current_tree_revision === 'number' ? ` (the tree is at revision ${details.current_tree_revision})` : ''}: read the files again, then retry.`;
+        case 'outside_tree_root':
+            return `Only paths under ${str(details.tree_root) ?? '/home/user'} exist in a file-first workspace (/ and /home cannot change): use a path under it.`;
+        case 'execution_in_progress':
+            return `Another exec${str(details.execution_id) ? ` (execution ${str(details.execution_id)})` : ''} is running on this file-first workspace; file changes and further exec calls wait until it ended. Retry then.`;
+        case 'execution_id_reused':
+            return 'That execution id was already used for a different command; call exec again (each call uses a new execution id).';
+        case 'no_execution_host':
+            return 'No host has room to run the command now and nothing ran; retry in a few seconds.';
+        default:
+            return undefined;
+    }
+}
+/**
+ * 409 conflict host_feature_unavailable (contracts §26.7; 0.4.0): the workspace runs on a host that predates the tool,
+ * until it runs on an upgraded host (minutes to hours). Not retryable, so the hint names another way to do it now.
+ */
+export function hostFeatureHint(reason, details = {}) {
+    if (reason !== 'host_feature_unavailable')
+        return undefined;
+    const later = 'It will work once the workspace runs on an upgraded host; retrying now does not help.';
+    switch (details.feature) {
+        case 'file_search':
+            return `This workspace's host does not support search_files yet. Search with exec instead, e.g. grep -rn -- PATTERN PATH (add -i to ignore case, -E for a regular expression). ${later}`;
+        case 'file_patch':
+            return `This workspace's host does not support edit_file yet. Use read_file, change the text, then write_file with the whole new content. ${later}`;
+        default:
+            return `This workspace's host does not support this tool yet. ${later}`;
+    }
+}
 export function describeToolError(err, context = {}) {
     if (err instanceof ShardfluxApiError) {
+        const hint = modeHint(err.reason, err.details ?? {}) ?? hostFeatureHint(err.reason, err.details ?? {});
         return {
             code: err.code,
             message: err.message,
+            ...(err.reason ? { reason: err.reason } : {}),
             status: err.status,
-            request_id: err.requestId,
+            // A refusal the SDK made itself (NotSupportedForModeError.local: no request) has no request id.
+            ...(err.requestId ? { request_id: err.requestId } : {}),
             retryable: err.retryable,
             source: err.source,
             ...(err.operationId ? { operation_id: err.operationId } : {}),
+            // No execution_id: a refusal answers before anything ran, and the execution id stays unused (contracts §29.8).
+            ...(err instanceof TreeRevisionMismatchError && err.currentTreeRevision !== null ? { current_tree_revision: err.currentTreeRevision } : {}),
             ...(err.details ? { details: err.details } : {}),
+            ...(hint ? { hint } : {}),
         };
     }
     if (err instanceof ToolArgumentError)
@@ -53,20 +124,32 @@ export function describeToolError(err, context = {}) {
         return { code: 'operation_failed', message: `${err.message}${hint}`, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}) };
     }
     if (named(err, 'TimeoutError')) {
+        // A file-first execution cannot be canceled: it runs to its end server side and then publishes what it changed.
+        const continues = context.executionId
+            ? `; execution ${context.executionId} continues server side (a file-first execution cannot be canceled): the files it changes are published when it ends, and the next exec or file change on this workspace waits for it`
+            : context.operationId
+                ? '; the operation continues server side (use operation_wait)'
+                : '';
         return {
             code: 'timeout',
-            message: `The tool call did not finish within ${context.timeoutMs ?? 'its'} ms${context.operationId ? '; the operation continues server side (use operation_wait)' : ''}.`,
+            message: `The tool call did not finish within ${context.timeoutMs ?? 'its'} ms${continues}.`,
             retryable: true,
-            ...(context.operationId ? { operation_id: context.operationId } : {}),
+            ...(context.operationId && !context.executionId ? { operation_id: context.operationId } : {}),
+            ...(context.executionId ? { execution_id: context.executionId } : {}),
         };
     }
     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 };
+        return { code: 'protocol_error', message: err.message, status: err.status, ...(context.executionId ? { execution_id: context.executionId } : {}) };
     if (err instanceof TypeError && err.message === 'fetch failed') {
         const cause = err.cause;
-        return { code: 'network_error', message: `Cannot reach the Shardflux API or cell gateway (${cause?.code ?? cause?.message ?? 'network error'}).`, retryable: true };
+        return {
+            code: 'network_error',
+            message: `Cannot reach the Shardflux API or cell gateway (${cause?.code ?? cause?.message ?? 'network error'}).${context.executionId ? ` Execution ${context.executionId} may still be running server side; the next exec on this workspace waits for it.` : ''}`,
+            retryable: true,
+            ...(context.executionId ? { execution_id: context.executionId } : {}),
+        };
     }
     return { code: 'internal_error', message: err instanceof Error ? err.message : String(err) };
 }

package/dist/index.d.ts

@@ -4,10 +4,10 @@
  * `shardflux-mcp` (bin.ts); `createShardfluxMcpServer()` builds the same server for any
  * MCP transport.
  */
-export { ALL_TOOL_PERMISSIONS, MCP_SERVER_VERSION, compactTiming, createShardfluxMcpServer, errorResult, okResult, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from './server.js';
+export { ALL_TOOL_PERMISSIONS, MCP_PACKAGE, MCP_SERVER_VERSION, checkServerVersion, compactTiming, createShardfluxMcpServer, errorResult, feedbackSuggestion, okResult, 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';
-export { ToolError, describeToolError, redact } from './errors.js';
-export type { ToolErrorInfo } from './errors.js';
+export { ToolError, describeToolError, hostFeatureHint, modeHint, redact } from './errors.js';
+export type { DescribeContext, ToolErrorInfo } from './errors.js';
 export { main, stderrLogger } from './main.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_SERVER_VERSION, compactTiming, createShardfluxMcpServer, errorResult, okResult, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from "./server.js";
+export { ALL_TOOL_PERMISSIONS, MCP_PACKAGE, MCP_SERVER_VERSION, checkServerVersion, compactTiming, createShardfluxMcpServer, errorResult, feedbackSuggestion, okResult, 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, redact } from "./errors.js";
+export { ToolError, describeToolError, hostFeatureHint, modeHint, redact } from "./errors.js";
 export { main, stderrLogger } from "./main.js";

package/dist/main.js

@@ -2,6 +2,8 @@
  * Process wiring for the stdio MCP server: configuration from the
  * environment, a stderr logger (stdout carries the protocol), the stdio
  * transport, and shutdown when the client closes stdin or on SIGINT/SIGTERM.
+ * The server's startup version check (0.4.0) reads its opt-outs
+ * (SHARDFLUX_NO_UPDATE_CHECK, NO_UPDATE_NOTIFIER) from the same environment.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ConfigError, loadConfig } from "./config.js";
@@ -51,6 +53,7 @@ export async function main(env = process.env) {
         api_url: config.apiUrl,
         pinned_workspace_key: config.workspaceKey ?? null,
         default_template: config.template ?? null,
+        workspace_mode: config.workspaceMode ?? null,
         agent_label: config.agentLabel,
         tool_timeout_ms: config.toolTimeoutMs,
         wake: config.wake,