@shardflux/mcp 0.3.1 → 0.4.1

package/dist/server.js

@@ -2,11 +2,14 @@
  * 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);
+ *   - send_feedback (0.4.0): feedback straight to the Shardflux founder; the instructions, its description and
+ *     the `feedback` field of error results ask agents to use it while they work;
  *   - the SDK's workspace tools (`workspaceTools()`: exec, files, processes,
  *     terminal, git, browser), published with the SDK's own JSON Schemas plus
  *     `workspace_key` (and `timeout_ms` where the SDK schema has none).
@@ -14,38 +17,72 @@
  * There is no agent loop and no local workspace directory: every call is one
  * SDK request/wait against the remote workspace. Workspace tools wake a
  * suspended workspace on use (SHARDFLUX_WAKE, bounded by
- * SHARDFLUX_WAKE_TIMEOUT_MS and the call's deadline). Each call has a deadline
+ * SHARDFLUX_WAKE_TIMEOUT_MS and the call's deadline), and each workspace tool
+ * call first sends the wake hint (the SDK tool runner's `workspace.hint()`,
+ * fire-and-forget) so a parked workspace restores while the call is prepared,
+ * except read_file, list_files and search_files, which a sleeping workspace
+ * answers from its disk without waking (contracts §26.4). Each call has a deadline
  * (`timeout_ms`, clamped to SHARDFLUX_MCP_TOOL_TIMEOUT_MS) and MCP cancellation
  * (notifications/cancelled -> `extra.signal`) aborts the underlying SDK
  * request or wait. Failures come back as `isError` tool results carrying the
  * API error code. stdout is the protocol; logs go to stderr. Opens, waits and
  * wakes carry the SDK's lifecycle timing, compacted (`compactTiming`).
+ *
+ * File-first workspaces (0.4.0; contracts §29: `workspace_open` `mode:
+ * "file_first"`) have files and executions only. A pinned server lists the
+ * tools of its workspace's mode (the key's mode once it resolves, else
+ * SHARDFLUX_WORKSPACE_MODE, else processful) and sends
+ * `notifications/tools/list_changed` when the known mode changes what it
+ * listed; an unpinned server lists every tool, and a call of a tool the named
+ * workspace's mode lacks is the SDK's NotSupportedForModeError
+ * (`not_supported_for_mode`) before any request.
+ *
+ * At startup (0.4.0) the server asks GET /v1/client-versions whether
+ * @shardflux/mcp at MCP_SERVER_VERSION is current and logs one `warn` line
+ * when it is not (`checkServerVersion`); the SDK client it builds runs no
+ * check of its own (`versionCheck: false`). Account-level actions are not
+ * tools (the project API key cannot do them): the server instructions point
+ * the agent at the `shard` CLI.
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { resolve as resolvePath } from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { SDK_VERSION, Shardflux, ShardfluxApiError, TemplateBuildTimeoutError, TemplateFileError, validateArgs, workspaceTools } from '@shardflux/sdk';
+import { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, Shardflux, ShardfluxApiError, TemplateBuildTimeoutError, TemplateFileError, checkClientVersion, validateArgs, versionCheckDisabledByEnv, workspaceTools } from '@shardflux/sdk';
 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.3.1';
+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}`;
 export const ALL_TOOL_PERMISSIONS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 const OBSERVED_STATES = ['creating', 'starting', 'running', 'suspending', 'suspended', 'resuming', 'forking', 'stopping', 'failed', 'deleting', 'deleted'];
 /**
- * The SDK's workspace tool definitions without a workspace. `workspaceTools()`
- * only touches the workspace inside `execute`, which is never called on these:
- * the proxy throws on any access, so a change in the SDK that did would fail loudly.
+ * The SDK's workspace tool definitions for a workspace mode, without a workspace. Given `tools` and `mode`,
+ * `workspaceTools()` only touches the workspace inside `execute`, which is never called on these: the proxy throws on
+ * any access, so a change in the SDK that did would fail loudly. `file_first` (0.4.0): the SDK offers only the exec
+ * and files tools, and exec is its file-first definition (executions: the result adds execution_id, state,
+ * tree_revision and changed).
  */
-export function sdkToolDefinitions(tools = ALL_TOOL_PERMISSIONS) {
+export function sdkToolDefinitions(tools = ALL_TOOL_PERMISSIONS, mode = 'processful') {
     const noWorkspace = new Proxy({}, {
         get(_t, prop) {
             throw new Error(`workspace tool definitions must not access workspace.${String(prop)}`);
         },
     });
-    return workspaceTools(noWorkspace, { tools: [...tools] });
+    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']);
+/** 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.',
+    pty: 'Use exec instead: each call runs one command to its end (pass input through its stdin argument).',
+    git: 'Run git inside exec instead, e.g. exec "git clone <url> /home/user/repo"; only files under /home/user persist.',
+    browser: 'Run a headless browser within one exec command instead, printing what you need or saving it under /home/user.',
+};
 function timeoutProp(ceiling) {
     return { type: 'integer', minimum: 1, maximum: 3_600_000, description: `Deadline for this call in milliseconds (default and maximum ${ceiling}; larger values are clamped).` };
 }
@@ -69,12 +106,19 @@ function capsFrom(args) {
         c.disk_gib = args.disk_gib;
     return Object.keys(c).length ? c : undefined;
 }
-/** What tools return for a workspace (no tokens or other credentials). */
+/**
+ * What tools return for a workspace (no tokens or other credentials). `mode` (0.4.0) is `processful` or `file_first`
+ * (a view without it, from an older API, is processful); `tree_revision`, the latest revision of the file tree, only
+ * for file-first workspaces (the API reports 0 for every processful one).
+ */
 export function summarizeWorkspace(v) {
+    const mode = v.mode ?? 'processful';
     return {
         id: v.id,
         key: v.workspace_key,
         ready: v.observed_state === 'running' && v.desired_state === 'running' && v.deleted_at === null,
+        mode,
+        ...(mode === 'file_first' ? { tree_revision: v.tree_revision } : {}),
         observed_state: v.observed_state,
         desired_state: v.desired_state,
         template: { slug: v.template.slug, version: v.template.version },
@@ -91,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,
     };
@@ -189,19 +235,85 @@ export function okResult(value) {
     }
     return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: isObject(value) ? value : { result: value } };
 }
-/** `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. */
-export function errorResult(info, timing) {
-    const body = timing ? { error: info, timing } : { error: info };
+/**
+ * `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. `extra` (0.4.0): more sibling
+ * fields, e.g. `feedback` (how to report the failure with send_feedback) or `hint`.
+ */
+export function errorResult(info, timing, extra = {}) {
+    const body = { error: info, ...(timing ? { timing } : {}), ...extra };
     return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body, isError: true };
 }
+const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
+/**
+ * When to use send_feedback, for the agent: the same words as `shard feedback --help`, in the server instructions and
+ * the tool description. It has to make an agent actually call it while it works.
+ */
+const FEEDBACK_USE = 'Call it actively while you work, not once at the end. Send a short note the moment: something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround; your user complains or is frustrated about Shardflux or the workflow around it (slowness, cost or limits, confusing setup, a missing feature, a workaround): paraphrase it, with what they were trying to do; your user asked for something Shardflux could not do, or made awkward. Short and frequent beats polished; include the request_id and error code (failed calls carry a ready-made "feedback" field). No need to ask first, but tell your user you sent it. Leave out private data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.';
+/**
+ * No send_feedback suggestion for the expected flow: argument, configuration or credential problems of the call itself,
+ * a wait that gave up while the work continues, and refusals whose error names the exact next step (the same list as
+ * the CLI's `feedback:` line).
+ */
+const NO_FEEDBACK_CODES = new Set(['invalid_arguments', 'workspace_pinned', 'unauthenticated', 'validation_failed', 'timeout']);
+const NO_FEEDBACK_REASONS = new Set([
+    'revision_mismatch',
+    'tree_revision_mismatch',
+    'edit_not_found',
+    'edit_ambiguous',
+    'edit_not_text',
+    'execution_id_reused',
+    'execution_in_progress',
+    'exec_failed_to_start',
+    'mode_mismatch',
+    'not_supported_for_mode',
+    'outside_tree_root',
+    'layout_unsupported',
+    'host_feature_unavailable',
+]);
+const suggestsFeedback = (info) => !NO_FEEDBACK_CODES.has(info.code) && !(info.reason !== undefined && NO_FEEDBACK_REASONS.has(info.reason));
+/** The `feedback` field of a failed call (0.4.0+): how to report it, with the error's request id and code. */
+export function feedbackSuggestion(info) {
+    const code = (info.code === 'operation_failed' || info.code === 'execution_failed') && typeof info.details?.error_code === 'string' ? info.details.error_code : info.code;
+    const args = [`category "bug"`, ...(info.request_id ? [`request_id "${info.request_id}"`] : []), `error_code "${code}"`];
+    return `Unexpected or unclear? Call send_feedback with ${args.join(', ')} and a short message saying what you expected.`;
+}
 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; 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.',
+    '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).',
+    'search_files finds text in files under a directory; edit_file replaces exact text in a file (each old_text must occur once) and returns the new revision, which you can pass as expected_revision to the next edit_file of that file so a change made by someone else is detected.',
+    'File-first workspaces (workspace_open mode "file_first"; results show mode and tree_revision) keep only files: there is no VM between calls, each exec runs in a fresh VM, and only files under /home/user persist between exec calls (install dependencies there, e.g. a virtualenv, and start servers within the command that needs them).',
+    'An exec result on a file-first workspace carries the paths it changed (changed) and the new tree_revision; an execution cannot be canceled. Process, terminal, git and browser tools and workspace_suspend, workspace_resume and workspace_fork do not apply to them (error reason not_supported_for_mode).',
+    'Account-level actions are not tools of this server: it works inside one project with a project API key, which the API refuses for them. Registering, signing in, organizations, projects, API keys, members, billing and plan upgrades, spend alerts and audit export are done with the shard CLI: `npx @shardflux/cli@latest --help` (for example `shard auth login`, `shard setup`, `shard billing upgrade <plan>`). A person still opens the verification email and pays on the Checkout page the CLI prints.',
+    `Feedback: send_feedback goes straight to the Shardflux founder, who reads every message. ${FEEDBACK_USE}`,
 ].join(' ');
+/**
+ * The startup version check (0.4.0; contracts §30.4): one GET <api>/v1/client-versions through the server's fetch
+ * (the SDK's checkClientVersion: 3 s timeout, never throws) for @shardflux/mcp at MCP_SERVER_VERSION. Outdated or
+ * unsupported: one `warn` line whose message is the notice (`@shardflux/mcp 0.4.0 is outdated: 0.5.0 is available.
+ * Update: <upgrade command>`) plus the status fields. Anything else (current; unknown: not listed, `latest` null while
+ * the package is not distributed, or the request failed) is a `debug` line only. createShardfluxMcpServer runs it in
+ * the background and never awaits it: the handshake and every tool call proceed without it. Resolves to the status;
+ * never rejects (a logger that throws is ignored).
+ */
+export async function checkServerVersion(apiUrl, f, log) {
+    const s = await checkClientVersion({ baseUrl: apiUrl, fetch: f, package: MCP_PACKAGE, version: MCP_SERVER_VERSION, ecosystem: 'npm', userAgent: USER_AGENT });
+    const fields = { status: s.status, package: s.package, current: s.current, latest: s.latest, minimum_supported: s.minimumSupported, upgrade_command: s.upgradeCommand };
+    try {
+        if ((s.status === 'outdated' || s.status === 'unsupported') && s.message)
+            log('warn', s.message, { ...fields, release_notes_url: s.releaseNotesUrl });
+        else
+            log('debug', 'version check', fields);
+    }
+    catch {
+        // The check never fails the server.
+    }
+    return s;
+}
 /** POST <cell>/v1/workspaces/{id}/exec/{session}/cancel: the cleanup request the SDK sends when a call is aborted. */
 function isExecCancel(input, init) {
     const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
@@ -269,25 +381,34 @@ export function createShardfluxMcpServer(config, opts = {}) {
     const cloud = new Shardflux({
         apiKey: config.apiKey,
         baseUrl: config.apiUrl,
-        userAgent: `shardflux-mcp/${MCP_SERVER_VERSION} shardflux-sdk-ts/${SDK_VERSION}`,
+        userAgent: USER_AGENT,
         fetch: callFetch,
         sleep: callSleep,
         onProgress,
+        // The server checks its own package at startup (below). The SDK's check would name @shardflux/sdk, which a
+        // server user cannot update on its own (it ships inside the server), and process.emitWarning would print a
+        // non-JSON line on stderr.
+        versionCheck: false,
     });
+    // In the background: the handshake and tool calls never wait for it (an unhandled rejection would end the process).
+    if (opts.versionCheck !== false && !versionCheckDisabledByEnv(opts.env))
+        checkServerVersion(config.apiUrl, baseFetch, log).catch(() => undefined);
     const pinned = config.workspaceKey;
     const ceiling = config.toolTimeoutMs;
     const wakeTimeoutMs = Math.min(config.wakeTimeoutMs ?? DEFAULT_WAKE_TIMEOUT_MS, ceiling);
     /**
      * Wake on use for a workspace's tools: `workspace.wake()` within the SDK's transition budget (SHARDFLUX_WAKE_TIMEOUT_MS)
      * and 250 ms short of the call's deadline, so a wake that runs out reports the operation (OperationTimeoutError) rather
-     * than a bare deadline. null when SHARDFLUX_WAKE=off: the refusal (workspace_not_running) comes back instead.
+     * than a bare deadline. null when SHARDFLUX_WAKE=off: the refusal (workspace_not_running) comes back instead. The
+     * wake's held resume (contracts §22.6) returns the token of this server's tools (its agent label), so the woken call
+     * runs at once with it.
      */
     const wakeFor = (ws) => config.wake === false
         ? null
         : (timeoutMs, signal) => {
             const deadline = ambient.getStore()?.deadline;
             const left = deadline === undefined ? timeoutMs : Math.min(timeoutMs, deadline - Date.now() - 250);
-            return ws.wake({ timeoutMs: Math.max(1, left), ...(signal ? { signal } : {}) });
+            return ws.wake({ timeoutMs: Math.max(1, left), ...(signal ? { signal } : {}), agentLabel: config.agentLabel });
         };
     // ---- principal and workspace resolution ----------------------------------------------------
     let meCache;
@@ -311,25 +432,71 @@ export function createShardfluxMcpServer(config, opts = {}) {
             throw new ToolError('invalid_arguments', 'workspace_key is required.');
         return given;
     };
+    // ---- the pinned workspace's mode (0.4.0) -----------------------------------------------------
+    /** The mode of the pinned key's live workspace, once a lookup, open or tool call has seen it. */
+    let pinnedMode;
+    /** The mode the last tools/list answer of a pinned server was built for (undefined before the first). */
+    let listedMode;
+    /**
+     * Records the mode of a live workspace. For the pinned key, a mode other than the one the client's tool list was
+     * built for sends notifications/tools/list_changed (once per change), so the client lists the tools again.
+     */
+    const noteMode = (key, ws) => {
+        if (pinned === undefined || key !== pinned || ws.data.deleted_at !== null)
+            return;
+        pinnedMode = ws.mode;
+        if (listedMode === undefined || listedMode === ws.mode)
+            return;
+        log('info', 'tool list changed', { pinned_workspace_key: pinned, listed_mode: listedMode, mode: ws.mode });
+        listedMode = ws.mode;
+        server.sendToolListChanged().catch((err) => log('warn', 'could not send notifications/tools/list_changed', { error: err instanceof Error ? err.message : String(err) }));
+    };
+    const forget = (key) => {
+        handles.delete(key);
+        if (key === pinned)
+            pinnedMode = undefined;
+    };
     /**
      * The workspace a key names, across every lifetime and purpose (sessions, drafts and test instances are hidden from
      * the default list), preferring the live workspace over tombstones: an ended session leaves a tombstone with the same
-     * key, and the key then opens a new workspace.
+     * key, and the key then opens a new workspace (contracts §19.11). Null when the key names none.
      */
-    const resolve = async (key, opts2) => {
+    const lookup = async (key, opts2) => {
         const cached = handles.get(key);
         if (cached)
             return cached;
         const w = await cloud.workspaces.findByKey(key, { includeDeleted: opts2.includeDeleted === true, signal: opts2.signal });
         if (opts2.signal.aborted)
             throw opts2.signal.reason;
-        if (w) {
-            if (w.data.deleted_at === null)
-                handles.set(key, w);
-            return w;
+        if (w && w.data.deleted_at === null) {
+            handles.set(key, w);
+            noteMode(key, w);
         }
+        return w;
+    };
+    const resolve = async (key, opts2) => {
+        const w = await lookup(key, opts2);
+        if (w)
+            return w;
         throw new ToolError('not_found', `No workspace with key "${key}" in this project. Create or reconnect it with workspace_open.`);
     };
+    /**
+     * The mode a pinned server lists tools for: its workspace's (looked up when not known yet), else
+     * SHARDFLUX_WORKSPACE_MODE (what workspace_open will create), else processful (the API's default for a new key).
+     */
+    const pinnedListMode = async (key, signal) => {
+        if (pinnedMode === undefined) {
+            try {
+                await lookup(key, { signal });
+            }
+            catch (err) {
+                log('warn', 'could not look up the pinned workspace’s mode; listing the tools of the configured mode', { error: describeToolError(err), mode: config.workspaceMode ?? 'processful' });
+            }
+        }
+        return pinnedMode ?? config.workspaceMode ?? 'processful';
+    };
+    /** The SDK's own refusal of a call the workspace's mode does not have (no request is made). */
+    const notForMode = (ws, operation, source, message) => NotSupportedForModeError.local(ws.mode, operation, source, message);
     /** The SDK's wait options for a call: its own timeout fires just before the call deadline, so the result names the operation. */
     const waitOpts = (call) => ({ timeoutMs: Math.max(1, call.timeoutMs - 250), signal: call.signal });
     const wait = async (call, operationId) => {
@@ -356,7 +523,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         {
             name: 'workspace_open',
             title: 'Open workspace',
-            description: 'Open a persistent workspace by key: creates it from the template on first use, reconnects (or resumes) it afterwards, never resets it. Waits until it is ready unless wait is false; on timeout the start continues server side (operation_wait), for at most 15 minutes while it waits for capacity. The result’s timing says where the time went.',
+            description: 'Open a persistent workspace by key: creates it from the template on first use, reconnects (or resumes) it afterwards, never resets it. Waits until it is ready unless wait is false; on timeout the start continues server side (operation_wait), for at most 15 minutes while it waits for capacity. The result’s timing says where the time went. mode "file_first" opens a file-first workspace (files only, ready at once; see mode).',
             inputSchema: obj({
                 workspace_key: workspaceKeyProp(pinned),
                 template: {
@@ -377,6 +544,11 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     description: 'Text inputs the template declares, {"NAME": "value"} (template_get shows a version’s settings.inputs): put into the environment of every command, start command and service. Replaces the inputs of an existing workspace; omitted leaves them unchanged. Secret inputs are stored secrets, never passed here.',
                 },
                 wait: { type: 'boolean', description: 'Wait until the workspace is ready, its start commands and services included (default true).' },
+                mode: {
+                    type: 'string',
+                    enum: ['processful', 'file_first'],
+                    description: `processful: one VM keeps files, installed packages and processes between calls (suspended when idle, resumable, forkable). file_first: the workspace is a versioned file tree with no VM between calls: each exec runs in a fresh VM and only files under /home/user persist; it is ready at once, never suspended, persistent, and needs a layered template version. A workspace's mode never changes (reopening a key with another mode is refused with mode_mismatch). ${config.workspaceMode ? `Default "${config.workspaceMode}" (this server's SHARDFLUX_WORKSPACE_MODE).` : 'Default: processful for a new key, the stored mode for an existing one.'}`,
+                },
             }, [...keyRequired, ...(config.template ? [] : ['template'])]),
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
             run: async (args, call) => {
@@ -387,11 +559,22 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 const caps = capsFrom(args);
                 const lifetime = args.lifetime === 'session' || args.lifetime === 'persistent' ? args.lifetime : undefined;
                 const inputs = stringMap(args.inputs, 'inputs');
+                const mode = args.mode === 'processful' || args.mode === 'file_first' ? args.mode : config.workspaceMode;
                 call.timed = true;
                 // The SDK's waited open: held by the server until ready (Prefer: wait), then polled; the handle it returns
-                // carries the first tool token, so the next tool call starts at once.
-                const ws = await cloud.workspaces.open({ key, template, ...(caps ? { caps } : {}), ...(lifetime ? { lifetime } : {}), ...(inputs ? { inputs } : {}), agentLabel: config.agentLabel, wait: args.wait === false ? false : waitOpts(call) });
+                // carries the first tool token, so the next tool call starts at once. A file-first open is ready at once.
+                const ws = await cloud.workspaces.open({
+                    key,
+                    template,
+                    ...(caps ? { caps } : {}),
+                    ...(lifetime ? { lifetime } : {}),
+                    ...(inputs ? { inputs } : {}),
+                    ...(mode ? { mode } : {}),
+                    agentLabel: config.agentLabel,
+                    wait: args.wait === false ? false : waitOpts(call),
+                });
                 handles.set(key, ws);
+                noteMode(key, ws);
                 return { workspace: summarizeWorkspace(ws.data), ready: ws.ready, ...(ws.ready ? {} : { next: ws.activeOperation ? `operation ${ws.activeOperation.id} is ${ws.activeOperation.state}; call operation_wait or workspace_open again` : 'the workspace is not running' }) };
             },
         },
@@ -425,22 +608,71 @@ export function createShardfluxMcpServer(config, opts = {}) {
         {
             name: 'workspace_status',
             title: 'Workspace status',
-            description: 'Current state of one workspace (ready, observed/desired state, grants, pending reason) and its most recent operations.',
+            description: 'Current state of one workspace (ready, mode, observed/desired state, grants, pending reason; tree_revision for a file-first workspace) and its most recent operations.',
             inputSchema: obj({ workspace_key: workspaceKeyProp(pinned) }, keyRequired),
             annotations: { readOnlyHint: true, openWorldHint: false },
             run: async (args, call) => {
-                const ws = await resolve(keyOf(args), { includeDeleted: true, signal: call.signal });
+                const key = keyOf(args);
+                const ws = await resolve(key, { includeDeleted: true, signal: call.signal });
                 await ws.refresh();
+                noteMode(key, ws);
                 const ops = await cloud.workspaces.operations(ws.id, { limit: 5 });
                 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).', (id, o) => cloud.workspaces.suspend(id, o)),
-        lifecycleTool('workspace_resume', 'Resume workspace', 'Resume a suspended workspace. Returns the resume operation (with wait: once finished, and its timing).', (id, o) => cloud.workspaces.resume(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.
+        (ws, o) => ws.resume({ ...o, agentLabel: config.agentLabel })),
         {
             name: 'workspace_fork',
             title: 'Fork workspace',
-            description: 'Fork a running or suspended workspace into a new key (an independent copy of its committed state). Returns the fork operation and the new workspace (with wait: once finished, and its timing).',
+            description: 'Fork a running or suspended workspace into a new key (an independent copy of its committed state). Returns the fork operation and the new workspace (with wait: once finished, and its timing). Not for file-first workspaces.',
             inputSchema: obj({
                 workspace_key: workspaceKeyProp(pinned),
                 new_key: { type: 'string', minLength: 1, maxLength: 200, description: 'Key of the new workspace.' },
@@ -449,7 +681,11 @@ export function createShardfluxMcpServer(config, opts = {}) {
             }, [...keyRequired, 'new_key']),
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
             run: async (args, call) => {
-                const source = await resolve(keyOf(args), { signal: call.signal });
+                const key = keyOf(args);
+                const source = await resolve(key, { signal: call.signal });
+                if (source.mode === 'file_first') {
+                    throw notForMode(source, 'fork', 'api', `workspace_fork is not available for the file-first workspace "${key}": file-first workspaces cannot be forked. To copy its files, open a new file-first workspace and write them there.`);
+                }
                 const caps = capsFrom(args);
                 const res = await cloud.workspaces.fork(source.id, { key: String(args.new_key), ...(caps ? { caps } : {}) }, lifecycleOpts(args, call));
                 call.operationId = res.operation.id;
@@ -540,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) => {
@@ -551,7 +787,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
             },
         },
     ];
-    function lifecycleTool(name, title, description, start) {
+    function lifecycleTool(name, title, description, operation, start) {
         return {
             name,
             title,
@@ -559,16 +795,80 @@ export function createShardfluxMcpServer(config, opts = {}) {
             inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), wait: { type: 'boolean', description: 'Wait until the operation finishes (default false).' } }, keyRequired),
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
             run: async (args, call) => {
-                const ws = await resolve(keyOf(args), { signal: call.signal });
-                const op = await start(ws.id, lifecycleOpts(args, call));
+                const key = keyOf(args);
+                const ws = await resolve(key, { signal: call.signal });
+                if (ws.mode === 'file_first') {
+                    throw notForMode(ws, operation, 'api', `${name} is not available for the file-first workspace "${key}": nothing runs between its exec calls, so it is never suspended and never needs resuming; its files persist as they are.`);
+                }
+                const op = await start(ws, lifecycleOpts(args, call));
                 call.operationId = op.id;
                 return { operation: summarizeOperation(op) };
             },
         };
     }
+    // ---- feedback (0.4.0) --------------------------------------------------------------------------
+    /** Who is reporting: the MCP client's name/version from initialize, else a non-default agent label. */
+    const reportingAgent = () => {
+        const c = server.getClientVersion();
+        if (c?.name)
+            return (c.version ? `${c.name}/${c.version}` : c.name).slice(0, 100);
+        return config.agentLabel !== 'mcp' ? config.agentLabel : undefined;
+    };
+    management.push({
+        name: 'send_feedback',
+        title: 'Send feedback',
+        description: `Send feedback straight to the Shardflux founder, who reads every message. ${FEEDBACK_USE} Categories: bug (something failed or behaved wrongly), confusing (an error, doc, name or output was unclear or misleading), missing (a capability, option or template you needed does not exist), idea, praise (something worked well), other. Rate limited per API key (rate_limited with details.retry_after_seconds); the same message within 24 hours is recorded once (duplicate: true).`,
+        inputSchema: obj({
+            message: { type: 'string', minLength: 1, maxLength: FEEDBACK_MESSAGE_MAX_LENGTH, description: 'What you did, what happened and what you expected (1-8000 characters). Leave secrets out.' },
+            category: { type: 'string', enum: [...FEEDBACK_CATEGORIES], description: 'bug, confusing, missing, idea, praise or other.' },
+            workspace: { type: 'string', minLength: 1, maxLength: 200, description: pinned ? `Workspace key or id it is about (default "${pinned}").` : 'Workspace key or id it is about.' },
+            request_id: { type: 'string', minLength: 1, maxLength: 200, description: 'request_id from the error, so the founder can find the logs.' },
+            error_code: { type: 'string', minLength: 1, maxLength: 100, description: 'The error code seen (error.code, or details.error_code of a failed operation), e.g. capacity_unavailable.' },
+            command: { type: 'string', minLength: 1, maxLength: 2000, description: 'The tool call (name and arguments) or command that led to it.' },
+        }, ['message', 'category']),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        run: async (args) => {
+            const message = String(args.message).trim();
+            if (message.length === 0)
+                throw new ToolError('invalid_arguments', 'message is empty: say what happened and what you expected.');
+            const context = { client: `shardflux-mcp/${MCP_SERVER_VERSION}` };
+            const agent = reportingAgent();
+            if (agent)
+                context.agent = agent;
+            const workspace = typeof args.workspace === 'string' ? args.workspace : pinned;
+            if (workspace !== undefined)
+                context.workspace = workspace;
+            if (typeof args.request_id === 'string')
+                context.requestId = args.request_id;
+            if (typeof args.error_code === 'string')
+                context.errorCode = args.error_code;
+            if (typeof args.command === 'string')
+                context.command = args.command;
+            const r = await cloud.sendFeedback({ message, category: args.category, context });
+            return {
+                id: r.id,
+                received_at: r.receivedAt,
+                duplicate: r.duplicate,
+                note: r.duplicate ? 'The same message was already received in the last 24 hours; it was not emailed again.' : 'Delivered to the Shardflux founder. Keep sending feedback as you work.',
+            };
+        },
+    });
     // ---- the SDK's workspace tools -------------------------------------------------------------
-    const readOnly = new Set(['read_file', 'list_files', 'list_processes', 'terminal_read', 'git_status', 'browser_screenshot', 'browser_content']);
-    const workspaceDefs = sdkToolDefinitions().map((sdk) => {
+    const readOnly = new Set(['read_file', 'list_files', 'search_files', 'list_processes', 'terminal_read', 'git_status', 'browser_screenshot', 'browser_content']);
+    const execDeadline = ` Here timeout_ms defaults to, and is capped by, this server's per-call deadline (${ceiling} ms) minus 2 s.`;
+    /**
+     * exec's description as listed: the SDK's for the workspace's mode (pinned servers), or the processful one plus
+     * what differs on a file-first workspace (unpinned servers: every call names its workspace).
+     */
+    const execDescription = (sdkDescription, listing) => {
+        if (listing === 'file_first')
+            return `${sdkDescription}${execDeadline} An execution cannot be canceled: if the deadline passes first it continues server side (the error names its execution_id) and the next exec waits for it.`;
+        if (listing === 'processful')
+            return `${sdkDescription}${execDeadline}`;
+        return `${sdkDescription} On a file-first workspace (workspace_open mode "file_first") each call instead runs in a fresh VM on the workspace’s files: only files under /home/user persist between calls, and the result adds execution_id, state, tree_revision and changed (the paths the command added, modified or deleted).${execDeadline}`;
+    };
+    /** A workspace tool: the SDK's definition, `workspace_key` (and `timeout_ms`), run through the SDK tool of the workspace's mode. */
+    const workspaceDef = (sdk, description) => {
         const own = sdk.parameters.properties ?? {};
         const hasTimeout = 'timeout_ms' in own;
         const inputSchema = {
@@ -579,7 +879,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         return {
             name: sdk.name,
             title: sdk.name.replace(/_/g, ' '),
-            description: sdk.name === 'exec' ? `${sdk.description} Here timeout_ms defaults to, and is capped by, this server's per-call deadline (${ceiling} ms) minus 2 s.` : sdk.description,
+            description,
             inputSchema,
             permission: sdk.permission,
             annotations: {
@@ -599,23 +899,42 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     sdkArgs.timeout_ms = Math.max(1000, cmdTimeout - 2000);
                 }
                 const ws = await resolve(key, { signal: call.signal });
+                // The SDK's tools for the workspace's mode: a file-first workspace has exec (as executions) and the file tools.
+                // A file-first execution cannot be canceled; its id is kept so a deadline error can name it.
+                const tool = workspaceTools(ws, {
+                    agentLabel: config.agentLabel,
+                    tools: [...ALL_TOOL_PERMISSIONS],
+                    wake: wakeFor(ws),
+                    transitionTimeoutMs: wakeTimeoutMs,
+                    onExecution: (id) => {
+                        call.executionId = id;
+                    },
+                }).find((t) => t.name === sdk.name);
+                if (!tool) {
+                    // A tool the workspace's mode does not have: refused like the SDK refuses such a call, before any request.
+                    if (ws.mode === 'file_first') {
+                        throw notForMode(ws, sdk.name, 'cell', `${sdk.name} is not available for the file-first workspace "${key}": it has no VM between exec calls. ${FILE_FIRST_INSTEAD[sdk.permission] ?? 'Use exec and the file tools.'}`);
+                    }
+                    throw new ToolError('internal_error', `SDK tool ${sdk.name} is missing`);
+                }
                 // A wake during the call (the workspace was suspended) is timed; a call without one has no timing.
                 call.timed = true;
-                const tool = workspaceTools(ws, { agentLabel: config.agentLabel, tools: [...ALL_TOOL_PERMISSIONS], wake: wakeFor(ws), transitionTimeoutMs: wakeTimeoutMs }).find((t) => t.name === sdk.name);
-                if (!tool)
-                    throw new ToolError('internal_error', `SDK tool ${sdk.name} is missing`);
                 try {
                     return await tool.execute(sdkArgs, { signal: call.signal });
                 }
                 catch (err) {
                     // A deleted or foreign workspace: forget the handle so the next call resolves the key again.
                     if (err instanceof ShardfluxApiError && err.source === 'api' && err.status === 404)
-                        handles.delete(key);
+                        forget(key);
                     throw err;
                 }
             },
         };
-    });
+    };
+    // Every call runs through these (the processful definitions: every tool; exec's parameters are the same in both
+    // modes); a pinned file-first server lists the file-first definitions instead.
+    const workspaceDefs = sdkToolDefinitions(ALL_TOOL_PERMISSIONS, 'processful').map((sdk) => workspaceDef(sdk, sdk.name === 'exec' ? execDescription(sdk.description, pinned === undefined ? 'any' : 'processful') : sdk.description));
+    const fileFirstDefs = sdkToolDefinitions(ALL_TOOL_PERMISSIONS, 'file_first').map((sdk) => workspaceDef(sdk, sdk.name === 'exec' ? execDescription(sdk.description, 'file_first') : sdk.description));
     const registry = new Map([...management, ...workspaceDefs].map((d) => [d.name, d]));
     const toMcpTool = (d) => ({
         name: d.name,
@@ -625,16 +944,26 @@ export function createShardfluxMcpServer(config, opts = {}) {
         annotations: { title: d.title, ...d.annotations },
     });
     // ---- protocol handlers ---------------------------------------------------------------------
-    const server = new Server({ name: 'shardflux', title: 'Shardflux workspaces', version: MCP_SERVER_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-        let permitted = ALL_TOOL_PERMISSIONS;
+    // listChanged: a pinned server's list follows its workspace's mode (notifications/tools/list_changed).
+    const server = new Server({ name: 'shardflux', title: 'Shardflux workspaces', version: MCP_SERVER_VERSION }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
+    const permittedTools = async () => {
         try {
-            permitted = (await principal()).api_key?.tool_permissions ?? [];
+            return (await principal()).api_key?.tool_permissions ?? [];
         }
         catch (err) {
             log('warn', 'could not read the API key’s tool permissions; listing every workspace tool', { error: describeToolError(err) });
+            return ALL_TOOL_PERMISSIONS;
         }
-        return { tools: [...management, ...workspaceDefs.filter((d) => d.permission !== undefined && permitted.includes(d.permission))].map(toMcpTool) };
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
+        // Unpinned: every tool (each call names its workspace; a tool its mode lacks is refused). Pinned: its mode's tools.
+        const [permitted, mode] = await Promise.all([permittedTools(), pinned === undefined ? undefined : pinnedListMode(pinned, AbortSignal.any([extra.signal, AbortSignal.timeout(ceiling)]))]);
+        if (mode !== undefined)
+            listedMode = mode;
+        const fileFirst = mode === 'file_first';
+        const mgmt = fileFirst ? management.filter((d) => !VM_ONLY_MANAGEMENT.has(d.name)) : management;
+        const tools = (fileFirst ? fileFirstDefs : workspaceDefs).filter((d) => d.permission !== undefined && permitted.includes(d.permission));
+        return { tools: [...mgmt, ...tools].map(toMcpTool) };
     });
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const name = request.params.name;
@@ -669,18 +998,41 @@ export function createShardfluxMcpServer(config, opts = {}) {
         }
         catch (err) {
             if (extra.signal.aborted) {
-                // The client canceled: the SDK request/wait was aborted; no response is sent for a canceled request.
-                log('info', 'tool call canceled by the client', { tool: name, outcome: 'canceled', ms: Date.now() - started, ...(call.operationId ? { operation_id: call.operationId } : {}) });
+                // The client canceled: the SDK request/wait was aborted; no response is sent for a canceled request. A
+                // file-first execution is not canceled with it (it cannot be): the log names it.
+                log('info', 'tool call canceled by the client', {
+                    tool: name,
+                    outcome: 'canceled',
+                    ms: Date.now() - started,
+                    ...(call.operationId ? { operation_id: call.operationId } : {}),
+                    ...(call.executionId ? { execution_id: call.executionId } : {}),
+                });
                 throw new McpError(ErrorCode.RequestTimeout, 'canceled');
             }
             // A structured error (API refusal, the SDK's own wait timeout) wins; a bare abort after the deadline is a timeout.
             const abortish = !(err instanceof Error) || err.name === 'TimeoutError' || err.name === 'AbortError';
-            const info = describeToolError(deadline.aborted && abortish ? new DOMException('deadline', 'TimeoutError') : err, { operationId: call.operationId, timeoutMs });
+            const info = describeToolError(deadline.aborted && abortish ? new DOMException('deadline', 'TimeoutError') : err, { operationId: call.operationId, timeoutMs, executionId: call.executionId });
             info.message = redact(info.message, config.apiKey);
             if (info.code === 'internal_error')
                 log('error', 'tool call failed unexpectedly', { tool: name, error: redact(err instanceof Error ? (err.stack ?? err.message) : String(err), config.apiKey) });
-            log('info', 'tool call', { tool: name, outcome: info.code, ms: Date.now() - started, ...(info.request_id ? { request_id: info.request_id } : {}) });
-            return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined);
+            log('info', 'tool call', {
+                tool: name,
+                outcome: info.code,
+                ms: Date.now() - started,
+                ...(info.reason ? { reason: info.reason } : {}),
+                ...(info.request_id ? { request_id: info.request_id } : {}),
+                ...(info.execution_id ? { execution_id: info.execution_id } : {}),
+            });
+            // A failure suggests send_feedback; a failed send_feedback says how to still reach the founder.
+            const s = info.details?.retry_after_seconds;
+            const siblings = name === 'send_feedback'
+                ? info.code === 'invalid_arguments'
+                    ? {}
+                    : { hint: `The feedback was not sent; ${info.code === 'rate_limited' ? `retry ${typeof s === 'number' ? `in ${s} s` : 'later'}, or ` : ''}email it to ${FEEDBACK_EMAIL}.` }
+                : suggestsFeedback(info)
+                    ? { feedback: feedbackSuggestion(info) }
+                    : {};
+            return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined, siblings);
         }
     });
     return server;