craftdriver 1.7.0 → 1.8.0

package/dist/cli/mcp/params.d.ts

@@ -0,0 +1,38 @@
+/** Cap on any single string argument, unless a spec narrows it further. */
+export declare const DEFAULT_MAX_STRING = 8192;
+/** Cap on any array argument, unless a spec narrows it further. */
+export declare const DEFAULT_MAX_ITEMS = 50;
+interface Common {
+    description?: string;
+    required?: boolean;
+}
+export type ParamSpec = (Common & {
+    type: 'string';
+    maxLength?: number;
+    /** Allowed values. Anything else is rejected, listing the valid set. */
+    enum?: readonly string[];
+}) | (Common & {
+    type: 'number';
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}) | (Common & {
+    type: 'boolean';
+}) | (Common & {
+    type: 'string[]';
+    maxItems?: number;
+    maxLength?: number;
+});
+export type ParamSpecs = Record<string, ParamSpec>;
+/** JSON Schema for `tools/list`, derived from the same specs validation uses. */
+export declare function toInputSchema(specs: ParamSpecs): Record<string, unknown>;
+/**
+ * Validate and normalize tool arguments.
+ *
+ * Throws `INVALID_ARGUMENT` — which the server maps to JSON-RPC `-32602` —
+ * before anything reaches the dispatcher. Returns only declared keys, so a
+ * field that slipped past cannot ride along into a browser command.
+ */
+export declare function validateArgs(tool: string, specs: ParamSpecs, raw: unknown): Record<string, unknown>;
+export {};
+//# sourceMappingURL=params.d.ts.map

package/dist/cli/mcp/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/params.ts"],"names":[],"mappings":"AAiBA,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,UAAU,MAAM;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,GACjB,CAAC,MAAM,GAAG;IACR,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC,GACF,CAAC,MAAM,GAAG;IACR,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC,GACF,CAAC,MAAM,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GAC9B,CAAC,MAAM,GAAG;IACR,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEP,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEnD,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgDxE;AAQD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqGzB"}

package/dist/cli/mcp/params.js

@@ -0,0 +1,174 @@
+/**
+ * Tool argument descriptors: one declaration, two consumers.
+ *
+ * A tool's `inputSchema` tells the model what to send; runtime validation
+ * decides what actually reaches the dispatcher. Written separately they drift,
+ * and the drift is invisible — the schema keeps promising a constraint nobody
+ * enforces. Here both are derived from the same `ParamSpec`, so a tool cannot
+ * advertise one contract and accept another.
+ *
+ * Deliberately not a JSON Schema engine. Tool arguments on this surface are
+ * flat — strings, numbers, booleans, and string arrays — and a general
+ * validator would be a large dependency-shaped thing to maintain for a shape
+ * this narrow. Anything needing more expressiveness than this is a sign the
+ * tool should be split, not that the descriptor should grow.
+ */
+import { CraftdriverError, ErrorCode } from '../../lib/errors.js';
+/** Cap on any single string argument, unless a spec narrows it further. */
+export const DEFAULT_MAX_STRING = 8192;
+/** Cap on any array argument, unless a spec narrows it further. */
+export const DEFAULT_MAX_ITEMS = 50;
+/** JSON Schema for `tools/list`, derived from the same specs validation uses. */
+export function toInputSchema(specs) {
+    const properties = {};
+    const required = [];
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.required)
+            required.push(name);
+        const base = {};
+        if (spec.description)
+            base.description = spec.description;
+        switch (spec.type) {
+            case 'string':
+                properties[name] = {
+                    type: 'string',
+                    ...base,
+                    maxLength: spec.maxLength ?? DEFAULT_MAX_STRING,
+                    ...(spec.enum ? { enum: [...spec.enum] } : {}),
+                };
+                break;
+            case 'number':
+                properties[name] = {
+                    type: spec.integer ? 'integer' : 'number',
+                    ...base,
+                    ...(spec.min !== undefined ? { minimum: spec.min } : {}),
+                    ...(spec.max !== undefined ? { maximum: spec.max } : {}),
+                };
+                break;
+            case 'boolean':
+                properties[name] = { type: 'boolean', ...base };
+                break;
+            case 'string[]':
+                properties[name] = {
+                    type: 'array',
+                    ...base,
+                    items: { type: 'string', maxLength: spec.maxLength ?? DEFAULT_MAX_STRING },
+                    maxItems: spec.maxItems ?? DEFAULT_MAX_ITEMS,
+                };
+                break;
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        // Advertised as well as enforced: a model that sends an extra field should
+        // be able to learn from the schema that it will be refused.
+        additionalProperties: false,
+    };
+}
+function invalid(tool, message, detail) {
+    return new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `${tool}: ${message}`, {
+        ...(detail ? { detail } : {}),
+    });
+}
+/**
+ * Validate and normalize tool arguments.
+ *
+ * Throws `INVALID_ARGUMENT` — which the server maps to JSON-RPC `-32602` —
+ * before anything reaches the dispatcher. Returns only declared keys, so a
+ * field that slipped past cannot ride along into a browser command.
+ */
+export function validateArgs(tool, specs, raw) {
+    if (raw === undefined || raw === null)
+        raw = {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw invalid(tool, 'arguments must be an object');
+    }
+    const args = raw;
+    // Unknown fields are refused rather than ignored: silently dropping one
+    // means a model that misspelled a required argument sees a successful call
+    // that did something other than what it asked for.
+    const known = new Set(Object.keys(specs));
+    const unknown = Object.keys(args).filter((key) => !known.has(key));
+    if (unknown.length > 0) {
+        throw invalid(tool, `unknown argument "${unknown[0]}"`, {
+            unknown,
+            allowed: [...known],
+        });
+    }
+    const out = {};
+    for (const [name, spec] of Object.entries(specs)) {
+        const value = args[name];
+        if (value === undefined || value === null) {
+            if (spec.required)
+                throw invalid(tool, `missing required argument "${name}"`);
+            continue;
+        }
+        switch (spec.type) {
+            case 'string': {
+                if (typeof value !== 'string') {
+                    throw invalid(tool, `"${name}" must be a string, got ${typeof value}`);
+                }
+                const max = spec.maxLength ?? DEFAULT_MAX_STRING;
+                if (value.length > max) {
+                    throw invalid(tool, `"${name}" is too long (${value.length} chars; max ${max})`);
+                }
+                if (spec.enum && !spec.enum.includes(value)) {
+                    throw invalid(tool, `"${name}" must be one of: ${spec.enum.join(', ')}`, {
+                        allowed: [...spec.enum],
+                    });
+                }
+                out[name] = value;
+                break;
+            }
+            case 'number': {
+                if (typeof value !== 'number' || !Number.isFinite(value)) {
+                    // NaN and Infinity are `typeof number` but serialize to null and
+                    // break every downstream range check, so they are rejected here.
+                    throw invalid(tool, `"${name}" must be a finite number`);
+                }
+                if (spec.integer && !Number.isInteger(value)) {
+                    throw invalid(tool, `"${name}" must be an integer`);
+                }
+                if (spec.min !== undefined && value < spec.min) {
+                    throw invalid(tool, `"${name}" must be >= ${spec.min}`);
+                }
+                if (spec.max !== undefined && value > spec.max) {
+                    throw invalid(tool, `"${name}" must be <= ${spec.max}`);
+                }
+                out[name] = value;
+                break;
+            }
+            case 'boolean': {
+                if (typeof value !== 'boolean') {
+                    throw invalid(tool, `"${name}" must be a boolean, got ${typeof value}`);
+                }
+                out[name] = value;
+                break;
+            }
+            case 'string[]': {
+                if (!Array.isArray(value)) {
+                    throw invalid(tool, `"${name}" must be an array of strings`);
+                }
+                const maxItems = spec.maxItems ?? DEFAULT_MAX_ITEMS;
+                if (value.length > maxItems) {
+                    throw invalid(tool, `"${name}" has too many items (${value.length}; max ${maxItems})`);
+                }
+                const maxLength = spec.maxLength ?? DEFAULT_MAX_STRING;
+                value.forEach((item, index) => {
+                    if (typeof item !== 'string') {
+                        throw invalid(tool, `"${name}[${index}]" must be a string, got ${typeof item}`);
+                    }
+                    if (item.length > maxLength) {
+                        throw invalid(tool, `"${name}[${index}]" is too long (${item.length} chars; max ${maxLength})`);
+                    }
+                });
+                out[name] = [...value];
+                break;
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=params.js.map

package/dist/cli/mcp/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../src/cli/mcp/params.ts"],"names":[],"mappings":"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"}

package/dist/cli/mcp/server.d.ts

@@ -1,22 +1,53 @@
+import type { LaunchOptions } from '../../lib/browser.js';
+import { type AgentSessionRunner } from '../agentSession.js';
+import { type ToolDef } from './tools.js';
+import { ArtifactStore } from './artifacts.js';
 /**
- * MCP server — JSON-RPC 2.0 over stdio.
+ * Choose the protocol version to answer with.
  *
- * Hand-rolled because the spec we use (initialize / tools/list /
- * tools/call) is ~6 methods, and pulling `@modelcontextprotocol/sdk`
- * would multiply our runtime-dep footprint. If the spec grows we can
- * swap in the SDK without changing tool definitions in `tools.ts`.
- *
- * Protocol version we advertise: 2024-11-05. If the client offers a
- * newer one we just echo theirs back — the methods we implement are
- * stable across versions to date.
- *
- * Lifecycle:
- *   client → initialize         → server returns capabilities + info
- *   client → notifications/initialized   (no response)
- *   client ⇆ tools/list, tools/call, ...
- *   stdin EOF (or SIGINT/SIGTERM)        → close browser, exit 0
+ * A client asking for a version we support gets it. Anything else — unknown,
+ * malformed, or missing — gets our default, which the spec allows and which
+ * is honest about what this server actually implements.
  */
-import { type LaunchOptions } from '../../lib/browser.js';
+export declare function negotiateProtocolVersion(requested: unknown): string;
+/** Maximum UTF-8 payload for one MCP JSON line. Shared with the daemon. */
+export declare const MCP_MAX_FRAME_BYTES: number;
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: number | string | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcSuccess {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result: unknown;
+}
+export interface JsonRpcError {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcError;
+interface ContentBlock {
+    type: 'text' | 'image';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+export interface ToolCallResult {
+    content: ContentBlock[];
+    isError?: boolean;
+    structuredContent?: unknown;
+}
+export interface McpSignalSource {
+    once(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    off(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
 export interface McpServerOptions {
     launch: LaunchOptions;
     /** Stream for incoming messages; defaults to process.stdin. */
@@ -29,6 +60,53 @@ export interface McpServerOptions {
     artifactsDir?: string;
     /** Override the spill threshold in bytes (default 2048; env: $CRAFTDRIVER_MCP_SPILL_BYTES). */
     spillBytes?: number;
+    /** Override the envelope cap (default 32 KiB; env: $CRAFTDRIVER_MCP_MAX_RESPONSE_BYTES). */
+    maxResponseBytes?: number;
+    /** Internal injection point for protocol and lifecycle tests. */
+    sessionFactory?: () => AgentSessionRunner;
+    /** Internal injection point for SIGINT/SIGTERM lifecycle tests. */
+    signalSource?: McpSignalSource;
+}
+export interface ClassifiedJsonRpcMessage {
+    kind: 'request' | 'notification';
+    message: JsonRpcRequest;
+}
+/** Decode exactly one JSON value after newline framing has completed. */
+export declare function decodeJsonLine(line: string): unknown;
+/** Classify by presence of an `id`; validation remains a separate concern. */
+export declare function classifyJsonRpcMessage(value: unknown): ClassifiedJsonRpcMessage;
+export declare function serializeJsonRpcResponse(response: JsonRpcResponse): string;
+export declare function sendJsonRpcResponse(output: NodeJS.WritableStream, response: JsonRpcResponse): void;
+interface SnapshotState {
+    snapshotsOn: boolean;
+    artifacts: ArtifactStore;
+    spillBytes: number;
+    /** Envelope cap, applied to failures as well as successes. */
+    maxResponseBytes: number;
+}
+interface RouterContext {
+    session: AgentSessionRunner;
+    snapshotState: SnapshotState;
 }
 export declare function runMcpServer(opts: McpServerOptions): Promise<void>;
+export declare function routeJsonRpcMethod(classified: ClassifiedJsonRpcMessage, ctx: RouterContext): Promise<JsonRpcResponse | null>;
+interface ToolResultContext {
+    artifacts: ArtifactStore;
+    spillBytes: number;
+    delta?: string;
+    /** Cap on the complete serialized result; defaults from the environment. */
+    maxResponseBytes?: number;
+}
+/** Render an already-computed tool value without invoking browser work. */
+export declare function serializeToolSuccess(tool: ToolDef, value: unknown, ctx: ToolResultContext): Promise<ToolCallResult>;
+/**
+ * Render a tool failure without requiring a session or transport.
+ *
+ * Bounded like a success. An error carries page-derived text — an assertion
+ * message quoting a whole element, a driver error echoing a selector — so
+ * leaving the failure path unbounded left the envelope cap trivially
+ * bypassable by whatever the page put in the message.
+ */
+export declare function serializeToolFailure(error: unknown, maxResponseBytes?: number): ToolCallResult;
+export {};
 //# sourceMappingURL=server.d.ts.map

package/dist/cli/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAkDnE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwHxE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/server.ts"],"names":[],"mappings":"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"}