@shardflux/mcp 0.3.1 → 0.4.1

package/dist/server.d.ts

@@ -1,9 +1,11 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import type { JsonSchema, LifecycleTiming, Operation, TemplateBuild, TemplateDetail, TemplateOwner, ToolName, WorkspaceTool, WorkspaceView } from '@shardflux/sdk';
+import type { ClientVersionStatus, JsonSchema, LifecycleTiming, Operation, TemplateBuild, TemplateDetail, TemplateOwner, ToolName, WorkspaceMode, WorkspaceTool, WorkspaceView } from '@shardflux/sdk';
 import type { McpConfig } from './config.js';
 import type { ToolErrorInfo } from './errors.js';
-export declare const MCP_SERVER_VERSION = "0.3.1";
+export declare const MCP_SERVER_VERSION = "0.4.1";
+/** The package this server is distributed as: its entry in GET /v1/client-versions (contracts §30.4). */
+export declare const MCP_PACKAGE = "@shardflux/mcp";
 export declare const ALL_TOOL_PERMISSIONS: readonly ToolName[];
 export type ObjectSchema = JsonSchema & {
     type: 'object';
@@ -14,16 +16,19 @@ export interface Logger {
     (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
 }
 /**
- * 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 declare function sdkToolDefinitions(tools?: readonly ToolName[], mode?: WorkspaceMode): WorkspaceTool[];
+/**
+ * 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 declare function sdkToolDefinitions(tools?: readonly ToolName[]): WorkspaceTool[];
-/** What tools return for a workspace (no tokens or other credentials). */
 export declare function summarizeWorkspace(v: WorkspaceView): {
-    id: string;
-    key: string;
-    ready: boolean;
     observed_state: "running" | "failed" | "suspended" | "deleted" | "creating" | "starting" | "suspending" | "resuming" | "forking" | "stopping" | "deleting";
     desired_state: "running" | "suspended" | "deleted";
     template: {
@@ -70,8 +75,19 @@ export declare function summarizeWorkspace(v: WorkspaceView): {
         operation_id: string | null;
         at: string | null;
     } | null;
+    /** A pending suspend-when-idle request (workspace_suspend with after_seconds); null when none. */
+    suspend_request: {
+        requested_at: string;
+        after_seconds: number;
+        not_before: string;
+    } | null;
     created_at: string;
     deleted_at: string | null;
+    tree_revision?: number | undefined;
+    id: string;
+    key: string;
+    ready: boolean;
+    mode: "processful" | "file_first";
 };
 /** A template build without the stored recipe (the compiled steps are long): state, version and what the builder refused. */
 export declare function summarizeBuild(b: TemplateBuild): {
@@ -190,15 +206,38 @@ export declare function compactTiming(t: LifecycleTiming): {
     outcome: import("@shardflux/sdk").TimingOutcome;
 };
 export declare function okResult(value: unknown): CallToolResult;
-/** `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. */
-export declare function errorResult(info: ToolErrorInfo, timing?: ReturnType<typeof compactTiming>): CallToolResult;
+/**
+ * `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 declare function errorResult(info: ToolErrorInfo, timing?: ReturnType<typeof compactTiming>, extra?: Record<string, unknown>): CallToolResult;
+/** The `feedback` field of a failed call (0.4.0+): how to report it, with the error's request id and code. */
+export declare function feedbackSuggestion(info: ToolErrorInfo): string;
 export interface ServerOptions {
     log?: Logger;
     /** Replaces the HTTP client entirely (tests); default: the runtime fetch via makeFetch(env). */
     fetch?: typeof fetch;
-    /** Process environment (SHARDFLUX_HTTP_KEEPALIVE). */
+    /**
+     * Process environment: SHARDFLUX_HTTP_KEEPALIVE (read only from here), and the version check's opt-outs
+     * SHARDFLUX_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER (from process.env when `env` is not given).
+     */
     env?: Record<string, string | undefined>;
     /** template_build reads local files only inside this directory (default: the process's working directory). */
     cwd?: string;
+    /**
+     * The startup version check (0.4.0; default true): see `checkServerVersion`. false, SHARDFLUX_NO_UPDATE_CHECK=1 (also
+     * true, yes, on) or NO_UPDATE_NOTIFIER turn it off.
+     */
+    versionCheck?: boolean;
 }
+/**
+ * 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 declare function checkServerVersion(apiUrl: string, f: typeof fetch, log: Logger): Promise<ClientVersionStatus>;
 export declare function createShardfluxMcpServer(config: McpConfig, opts?: ServerOptions): Server;