summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/file-read.d.ts

@@ -0,0 +1,64 @@
+/**
+ * file-read — ONE implementation of `summer_read_file` for both faces
+ * (src/mcp/tools/file-tools.ts and tool-dispatch.ts).
+ *
+ * The engine's state:read-file returns the first maxBytes of a file plus a
+ * sha256 over the WHOLE file; it has no offset (StateProvider::read_file_state).
+ * Paging and JSON filtering therefore happen here: the engine reads up to its
+ * 1 MB window once, and this module returns only the requested part — a line
+ * or byte window, or the entries of a .json picked by json_path / keys — so an
+ * agent can read one entry of a large JSON file without the host refusing
+ * the result. The sha256 stays the full-file receipt, so a guarded overwrite
+ * still works after a windowed read.
+ */
+import { z } from "zod";
+/** The engine's own read cap (and the most this module ever asks for). */
+export declare const FILE_READ_WINDOW_BYTES = 1000000;
+export declare const DEFAULT_READ_MAX_BYTES = 200000;
+export declare const readFileInputShape: {
+    path: z.ZodString;
+    max_bytes: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodEnum<["lines", "bytes"]>>;
+    json_path: z.ZodOptional<z.ZodString>;
+    keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    keys_only: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const readFileInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    max_bytes: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodEnum<["lines", "bytes"]>>;
+    json_path: z.ZodOptional<z.ZodString>;
+    keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    keys_only: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    max_bytes: number;
+    keys?: string[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    unit?: "bytes" | "lines" | undefined;
+    json_path?: string | undefined;
+    keys_only?: boolean | undefined;
+}, {
+    path: string;
+    keys?: string[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    max_bytes?: number | undefined;
+    unit?: "bytes" | "lines" | undefined;
+    json_path?: string | undefined;
+    keys_only?: boolean | undefined;
+}>;
+export type ReadFileArgs = z.infer<typeof readFileInputSchema>;
+export interface ReadFileClient {
+    readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
+}
+type JsonSegment = string | number;
+/** Parse `a.b[0]["c d"]['e']` (optionally `$`-prefixed) into segments. */
+export declare function parseJsonPath(path: string): JsonSegment[];
+export declare function readProjectFileWindow(client: ReadFileClient, args: ReadFileArgs): Promise<unknown>;
+export {};

package/dist/core/capabilities/file-read.js

@@ -0,0 +1,325 @@
+/**
+ * file-read — ONE implementation of `summer_read_file` for both faces
+ * (src/mcp/tools/file-tools.ts and tool-dispatch.ts).
+ *
+ * The engine's state:read-file returns the first maxBytes of a file plus a
+ * sha256 over the WHOLE file; it has no offset (StateProvider::read_file_state).
+ * Paging and JSON filtering therefore happen here: the engine reads up to its
+ * 1 MB window once, and this module returns only the requested part — a line
+ * or byte window, or the entries of a .json picked by json_path / keys — so an
+ * agent can read one entry of a large JSON file without the host refusing
+ * the result. The sha256 stays the full-file receipt, so a guarded overwrite
+ * still works after a windowed read.
+ */
+import { z } from "zod";
+import { ToolInputError } from "../tool-errors.js";
+import { asRecord } from "../util/json.js";
+import { safeProjectPath } from "./engine-ops.js";
+/** The engine's own read cap (and the most this module ever asks for). */
+export const FILE_READ_WINDOW_BYTES = 1_000_000;
+export const DEFAULT_READ_MAX_BYTES = 200_000;
+// Mirrors library/tools/read-file/resource.yaml input_schema (parity-tested).
+export const readFileInputShape = {
+    path: z.string().describe("Project path, e.g. res://scripts/player.gd"),
+    max_bytes: z
+        .number()
+        .int()
+        .positive()
+        .max(FILE_READ_WINDOW_BYTES)
+        .default(DEFAULT_READ_MAX_BYTES)
+        .describe("Most bytes of content to return (UTF-8). Default 200000. A window or JSON selection is cut at this size too."),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Skip this many units (lines by default, see unit) before returning content. 0 = from the start."),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Return at most this many units (lines by default). The result's window.next_offset continues the read."),
+    unit: z
+        .enum(["lines", "bytes"])
+        .optional()
+        .describe("What offset/limit count: 'lines' (default) or 'bytes' (cut on UTF-8 character boundaries)."),
+    json_path: z
+        .string()
+        .optional()
+        .describe("For a JSON file: return only this value, e.g. 'pieces.wall_a', 'pieces[\"a b\"]', 'items[3].size_m'."),
+    keys: z
+        .array(z.string())
+        .max(64)
+        .optional()
+        .describe("For a JSON object (the file root or the json_path value): keep only these keys; * and ? wildcards, e.g. ['wall_*']."),
+    keys_only: z
+        .boolean()
+        .optional()
+        .describe("For a JSON object: return only its key names (after the keys filter), not the values — a cheap table of contents."),
+};
+export const readFileInputSchema = z.object(readFileInputShape).strict();
+function failure(failure_reason, error, extra = {}) {
+    return { ok: false, failure_reason, error, ...extra };
+}
+/** Parse `a.b[0]["c d"]['e']` (optionally `$`-prefixed) into segments. */
+export function parseJsonPath(path) {
+    let rest = path.trim();
+    if (rest.startsWith("$"))
+        rest = rest.slice(1);
+    const segments = [];
+    while (rest.length > 0) {
+        if (rest.startsWith(".")) {
+            rest = rest.slice(1);
+            continue;
+        }
+        if (rest.startsWith("[")) {
+            const match = /^\[\s*(?:(-?\d+)|"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\s*\]/.exec(rest);
+            if (!match) {
+                throw new ToolInputError(`Invalid json_path near "${rest.slice(0, 40)}": use dots and brackets, e.g. pieces.wall_01, pieces["a b"], items[3].`);
+            }
+            if (match[1] !== undefined)
+                segments.push(Number(match[1]));
+            else
+                segments.push((match[2] ?? match[3] ?? "").replace(/\\(.)/g, "$1"));
+            rest = rest.slice(match[0].length);
+            continue;
+        }
+        const match = /^[^.[\]]+/.exec(rest);
+        segments.push(match[0]);
+        rest = rest.slice(match[0].length);
+    }
+    return segments;
+}
+function globToRegExp(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+}
+function describeJsonType(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (value === null)
+        return "null";
+    return typeof value;
+}
+function keysPreview(value) {
+    if (Array.isArray(value))
+        return { type: "array", length: value.length };
+    const record = asRecord(value);
+    if (record) {
+        const keys = Object.keys(record);
+        return { type: "object", total_keys: keys.length, keys: keys.slice(0, 60), ...(keys.length > 60 ? { keys_truncated: true } : {}) };
+    }
+    return { type: describeJsonType(value) };
+}
+function selectJson(root, args) {
+    let current = root;
+    const resolved = [];
+    for (const segment of args.json_path !== undefined ? parseJsonPath(args.json_path) : []) {
+        let next;
+        let found = false;
+        if (Array.isArray(current)) {
+            const index = typeof segment === "number" ? segment : /^-?\d+$/.test(segment) ? Number(segment) : Number.NaN;
+            const at = index < 0 ? current.length + index : index;
+            if (Number.isInteger(at) && at >= 0 && at < current.length) {
+                next = current[at];
+                found = true;
+            }
+        }
+        else {
+            const record = asRecord(current);
+            const key = String(segment);
+            if (record && Object.prototype.hasOwnProperty.call(record, key)) {
+                next = record[key];
+                found = true;
+            }
+        }
+        if (!found) {
+            const at = resolved.length > 0 ? resolved.map(String).join(".") : "(root)";
+            return failure("json_path_not_found", `json_path ${args.json_path}: "${String(segment)}" does not exist under ${at}.`, { resolved: at, here: keysPreview(current) });
+        }
+        current = next;
+        resolved.push(segment);
+    }
+    const meta = { ...(args.json_path !== undefined ? { json_path: args.json_path } : {}), type: describeJsonType(current) };
+    const wantsKeys = args.keys !== undefined || args.keys_only === true;
+    if (!wantsKeys) {
+        if (Array.isArray(current))
+            meta.length = current.length;
+        else if (asRecord(current))
+            meta.total_keys = Object.keys(current).length;
+        return { value: current, meta };
+    }
+    const record = asRecord(current);
+    if (!record) {
+        return failure("not_an_object", `keys/keys_only apply to a JSON object, but ${args.json_path ?? "the file root"} is ${Array.isArray(current) ? `an array of ${current.length} items — select one with json_path, e.g. [0]` : `a ${describeJsonType(current)}`}.`);
+    }
+    const allKeys = Object.keys(record);
+    const patterns = (args.keys ?? []).map(globToRegExp);
+    const matched = patterns.length > 0 ? allKeys.filter((key) => patterns.some((pattern) => pattern.test(key))) : allKeys;
+    meta.total_keys = allKeys.length;
+    meta.matched_keys = matched.length;
+    if (args.keys !== undefined)
+        meta.keys = args.keys;
+    if (args.keys_only === true)
+        return { value: matched, meta: { ...meta, keys_only: true } };
+    const picked = {};
+    for (const key of matched)
+        picked[key] = record[key];
+    return { value: picked, meta };
+}
+// ---------------------------------------------------------------------------
+// Windows
+// ---------------------------------------------------------------------------
+function utf8Length(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function lineWindow(text, offset, limit, maxBytes, sourceCut) {
+    const lines = text.split("\n");
+    // A trailing newline ends the last line; it does not start another one.
+    if (lines.length > 1 && lines[lines.length - 1] === "")
+        lines.pop();
+    const total = lines.length;
+    const wanted = lines.slice(offset, limit !== undefined ? offset + limit : undefined);
+    const kept = [];
+    let bytes = 0;
+    let cutByMaxBytes = false;
+    for (const line of wanted) {
+        const cost = utf8Length(line) + 1;
+        if (bytes + cost > maxBytes && kept.length > 0) {
+            cutByMaxBytes = true;
+            break;
+        }
+        if (bytes + cost > maxBytes) {
+            // One line alone is bigger than max_bytes: return its head.
+            const buffer = Buffer.from(line, "utf8");
+            let end = maxBytes;
+            while (end > 0 && (buffer[end] & 0xc0) === 0x80)
+                end--;
+            kept.push(buffer.subarray(0, end).toString("utf8"));
+            cutByMaxBytes = true;
+            break;
+        }
+        kept.push(line);
+        bytes += cost;
+    }
+    const returned = kept.length;
+    const nextOffset = offset + returned;
+    const eof = !sourceCut && !cutByMaxBytes && nextOffset >= total;
+    return {
+        content: kept.join("\n"),
+        complete: offset === 0 && eof,
+        meta: {
+            unit: "lines",
+            offset,
+            ...(limit !== undefined ? { limit } : {}),
+            returned,
+            start_line: returned > 0 ? offset + 1 : null,
+            end_line: returned > 0 ? offset + returned : null,
+            total_lines: total,
+            ...(sourceCut ? { total_lines_is_lower_bound: true } : {}),
+            next_offset: eof ? null : nextOffset,
+            eof,
+            ...(cutByMaxBytes ? { cut_by_max_bytes: true } : {}),
+        },
+    };
+}
+function byteWindow(text, offset, limit, maxBytes, totalBytes, sourceCut) {
+    const buffer = Buffer.from(text, "utf8");
+    if (offset > 0 && offset >= buffer.length && sourceCut) {
+        return failure("offset_beyond_read_window", `offset ${offset} is past the engine's 1 MB read window for this file (${totalBytes} bytes). Only the first 1 MB can be read.`);
+    }
+    let start = Math.min(offset, buffer.length);
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
+        start++;
+    const span = Math.min(limit ?? maxBytes, maxBytes);
+    let end = Math.min(buffer.length, start + span);
+    while (end > start && end < buffer.length && (buffer[end] & 0xc0) === 0x80)
+        end--;
+    const cutByMaxBytes = limit !== undefined && limit > maxBytes && end < buffer.length;
+    const eof = end >= buffer.length && !sourceCut;
+    return {
+        content: buffer.subarray(start, end).toString("utf8"),
+        complete: start === 0 && eof,
+        meta: {
+            unit: "bytes",
+            offset,
+            ...(limit !== undefined ? { limit } : {}),
+            start_byte: start,
+            end_byte: end,
+            returned: end - start,
+            total_bytes: totalBytes,
+            next_offset: eof ? null : end,
+            eof,
+            ...(cutByMaxBytes ? { cut_by_max_bytes: true } : {}),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function readProjectFileWindow(client, args) {
+    const path = safeProjectPath(args.path);
+    const maxBytes = args.max_bytes ?? DEFAULT_READ_MAX_BYTES;
+    const windowed = args.offset !== undefined || args.limit !== undefined || args.unit !== undefined;
+    const jsonMode = args.json_path !== undefined || args.keys !== undefined || args.keys_only === true;
+    if (args.json_path !== undefined)
+        parseJsonPath(args.json_path); // validate before reading
+    if (!windowed && !jsonMode)
+        return client.readProjectFile(path, maxBytes);
+    const unit = args.unit ?? "lines";
+    const offset = args.offset ?? 0;
+    // A byte window from the start of the file needs only that many bytes.
+    const engineBytes = !jsonMode && unit === "bytes" && args.limit !== undefined
+        ? Math.min(FILE_READ_WINDOW_BYTES, offset + Math.min(args.limit, maxBytes) + 4)
+        : FILE_READ_WINDOW_BYTES;
+    const read = await client.readProjectFile(path, engineBytes);
+    const root = asRecord(read);
+    const data = asRecord(root?.data);
+    if (!root || root.ok === false || !data)
+        return read;
+    if (data.encoding === "binary" || typeof data.content !== "string") {
+        return failure("binary_file", `${path} is not a text file; offset/limit and json_path apply to text only.`);
+    }
+    const totalBytes = typeof data.size === "number" ? data.size : utf8Length(data.content);
+    const sourceCut = data.truncated === true;
+    let text = data.content;
+    let json;
+    if (jsonMode) {
+        if (sourceCut) {
+            return failure("file_too_large_for_json", `${path} is ${totalBytes} bytes, over the 1 MB read window, so it cannot be parsed as a whole. Page it with offset/limit instead.`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            return failure("not_json", `${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}); json_path/keys apply to JSON files only.`);
+        }
+        const selected = selectJson(parsed, args);
+        if ("ok" in selected && selected.ok === false)
+            return selected;
+        const { value, meta } = selected;
+        text = JSON.stringify(value, null, 2) ?? "null";
+        json = meta;
+    }
+    const window = unit === "bytes"
+        ? byteWindow(text, offset, args.limit, maxBytes, jsonMode ? utf8Length(text) : totalBytes, sourceCut && !jsonMode)
+        : lineWindow(text, offset, args.limit, maxBytes, sourceCut && !jsonMode);
+    if ("ok" in window && window.ok === false)
+        return window;
+    const { content, complete, meta } = window;
+    const { content: _full, ...rest } = data;
+    void _full;
+    return {
+        ...root,
+        data: {
+            ...rest,
+            content,
+            // truncated: the returned content is not the whole file (or selection).
+            truncated: !complete,
+            window: meta,
+            ...(json ? { json } : {}),
+        },
+    };
+}

package/dist/core/capabilities/game-task-plan.js

@@ -291,8 +291,10 @@ function inferSkills(mode, target, goal) {
         addSkill(routes, "gdscript-patterns", "Typed signal and state patterns for UI code.", 150);
     }
     if (target === "multiplayer") {
-        addSkill(routes, "setup-multiplayer", "Choose networking model before implementation.", 270);
-        addSkill(routes, "host-authoritative-state", "Server-authoritative state model.", 220);
+        addSkill(routes, "multiplayer", "How Summer multiplayer works and which skill builds each piece.", 270);
+        addSkill(routes, "multiplayer-project", "Client and authority scenes, World, queue and Local Play.", 240);
+        addSkill(routes, "multiplayer-movement", "Client-side player movement checked by the authority.", 220);
+        addSkill(routes, "multiplayer-state", "Authority-owned state, Commands and Events.", 210);
     }
     if (includesAny(text, ["player controller", "fps", "first person", "wasd", "camera"])) {
         addSkill(routes, "fps-controller", "Player controller, camera, collision, and input bindings.", 240);

package/dist/core/capabilities/grep.d.ts

@@ -0,0 +1,60 @@
+/**
+ * grep — ONE implementation of `summer_grep` for both faces
+ * (src/mcp/tools/file-tools.ts and tool-dispatch.ts), over the engine's
+ * ripgrep-backed Grep op (modules/1summer_engine/editor/ops/search_ops.cpp).
+ *
+ * The engine op returns {file, line, content} per match and parses only
+ * ripgrep's "match" events, so its contextLines flag adds nothing to the
+ * result. Context lines are therefore cut here, from the matched files read
+ * back through state:read-file, under a file and size budget. Every line is
+ * clipped to max_line_chars so a minified file cannot flood the reply.
+ */
+import { z } from "zod";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+export declare const GREP_DEFAULT_MAX_RESULTS = 50;
+export declare const GREP_MAX_RESULTS = 500;
+export declare const GREP_DEFAULT_LINE_CHARS = 240;
+export declare const grepInputShape: {
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+    case_sensitive: z.ZodOptional<z.ZodBoolean>;
+    context_lines: z.ZodOptional<z.ZodNumber>;
+    max_results: z.ZodOptional<z.ZodNumber>;
+    max_line_chars: z.ZodOptional<z.ZodNumber>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const grepInputSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+    case_sensitive: z.ZodOptional<z.ZodBoolean>;
+    context_lines: z.ZodOptional<z.ZodNumber>;
+    max_results: z.ZodOptional<z.ZodNumber>;
+    max_line_chars: z.ZodOptional<z.ZodNumber>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    pattern: string;
+    path?: string | undefined;
+    glob?: string | undefined;
+    case_sensitive?: boolean | undefined;
+    context_lines?: number | undefined;
+    max_results?: number | undefined;
+    max_line_chars?: number | undefined;
+    multiline?: boolean | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+    glob?: string | undefined;
+    case_sensitive?: boolean | undefined;
+    context_lines?: number | undefined;
+    max_results?: number | undefined;
+    max_line_chars?: number | undefined;
+    multiline?: boolean | undefined;
+}>;
+export type GrepArgs = z.infer<typeof grepInputSchema>;
+export interface GrepClient extends CapabilityAdvertisingClient {
+    executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
+}
+export declare function grepProject(client: GrepClient, args: GrepArgs): Promise<unknown>;

package/dist/core/capabilities/grep.js

@@ -0,0 +1,190 @@
+/**
+ * grep — ONE implementation of `summer_grep` for both faces
+ * (src/mcp/tools/file-tools.ts and tool-dispatch.ts), over the engine's
+ * ripgrep-backed Grep op (modules/1summer_engine/editor/ops/search_ops.cpp).
+ *
+ * The engine op returns {file, line, content} per match and parses only
+ * ripgrep's "match" events, so its contextLines flag adds nothing to the
+ * result. Context lines are therefore cut here, from the matched files read
+ * back through state:read-file, under a file and size budget. Every line is
+ * clipped to max_line_chars so a minified file cannot flood the reply.
+ */
+import { z } from "zod";
+import { missingEngineOpResult } from "../capability-skew.js";
+import { asRecord } from "../util/json.js";
+import { safeProjectPath } from "./engine-ops.js";
+import { extractOpError, withOldEngineHint } from "./engine-receipt.js";
+import { GREP_FALLBACK } from "./engine-fallbacks.js";
+export const GREP_DEFAULT_MAX_RESULTS = 50;
+export const GREP_MAX_RESULTS = 500;
+export const GREP_DEFAULT_LINE_CHARS = 240;
+/** Distinct files read back for context lines. */
+const CONTEXT_MAX_FILES = 25;
+/** Soft cap on the whole reply's context text. */
+const CONTEXT_BUDGET_CHARS = 60_000;
+// Mirrors library/tools/grep/resource.yaml input_schema (parity-tested).
+export const grepInputShape = {
+    pattern: z.string().min(1).describe("Ripgrep regular expression, e.g. '\"fits_into\"' or 'func _on_.*_pressed'"),
+    path: z
+        .string()
+        .optional()
+        .describe("Search scope: a res:// directory or file, e.g. 'res://kit/' or 'res://kit/kit_manifest.json'. Default: the whole project."),
+    glob: z
+        .string()
+        .optional()
+        .describe("File filter passed to ripgrep --glob, e.g. '*.gd', '**/*.json', '!addons/**'. A glob also reaches files .gitignore would skip."),
+    case_sensitive: z.boolean().optional().describe("Match case exactly (default false: case-insensitive)."),
+    context_lines: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .describe("Lines of context before and after each match (0-10, default 0)."),
+    max_results: z
+        .number()
+        .int()
+        .positive()
+        .max(GREP_MAX_RESULTS)
+        .optional()
+        .describe(`Most matches to return (default ${GREP_DEFAULT_MAX_RESULTS}, max ${GREP_MAX_RESULTS}). truncated:true means there were more.`),
+    max_line_chars: z
+        .number()
+        .int()
+        .min(40)
+        .max(2000)
+        .optional()
+        .describe(`Clip every returned line to this many characters (default ${GREP_DEFAULT_LINE_CHARS}).`),
+    multiline: z.boolean().optional().describe("Let the pattern span lines (ripgrep -U --multiline-dotall)."),
+};
+export const grepInputSchema = z.object(grepInputShape).strict();
+function clip(line, max) {
+    return line.length > max ? `${line.slice(0, max)}…[+${line.length - max} chars]` : line;
+}
+function grepPayload(result) {
+    const root = asRecord(result);
+    if (!root)
+        return null;
+    if (Array.isArray(root.matches))
+        return root;
+    const results = Array.isArray(root.results) ? root.results : [];
+    return asRecord(results.find((entry) => asRecord(entry)?.op === "Grep") ?? results[0]) ?? null;
+}
+/** Turn the engine's raw ripgrep failures into a classified result. */
+function classifyGrepFailure(result, path) {
+    const message = extractOpError(result);
+    if (!message)
+        return result;
+    const lower = message.toLowerCase();
+    if (lower.includes("no such file") || lower.includes("os error 2") || lower.includes("cannot find the path")) {
+        return {
+            ok: false,
+            failure_reason: "path_not_found",
+            error: `summer_grep: ${path ?? "the search path"} does not exist in the project. Check the res:// path (or drop path to search the whole project).`,
+        };
+    }
+    if (lower.includes("ripgrep") && (lower.includes("unavailable") || lower.includes("not found") || lower.includes("failed to start"))) {
+        return {
+            ok: false,
+            failure_reason: "ripgrep_unavailable",
+            error: `summer_grep: this engine build has no usable ripgrep (${message}). ${GREP_FALLBACK}; or send the slower SearchInFiles op through summer_batch.`,
+        };
+    }
+    return result;
+}
+export async function grepProject(client, args) {
+    const path = args.path !== undefined && args.path.trim() !== "" ? safeProjectPath(args.path) : undefined;
+    const maxResults = args.max_results ?? GREP_DEFAULT_MAX_RESULTS;
+    const lineChars = args.max_line_chars ?? GREP_DEFAULT_LINE_CHARS;
+    const contextLines = args.context_lines ?? 0;
+    const missing = missingEngineOpResult(client, "Grep", GREP_FALLBACK);
+    if (missing)
+        return { ...missing };
+    const op = { op: "Grep", pattern: args.pattern, maxResults };
+    if (path)
+        op.path = path;
+    if (args.glob)
+        op.glob = args.glob;
+    if (args.case_sensitive)
+        op.caseSensitive = true;
+    if (args.multiline)
+        op.multiline = true;
+    const result = withOldEngineHint(await client.executeOps([op]), "Grep", GREP_FALLBACK);
+    if (extractOpError(result))
+        return classifyGrepFailure(result, path);
+    const payload = grepPayload(result);
+    if (!payload || !Array.isArray(payload.matches))
+        return result;
+    const rawMatches = payload.matches
+        .map((m) => asRecord(m))
+        .filter((m) => !!m && typeof m.file === "string");
+    const matches = rawMatches.slice(0, maxResults).map((m) => ({
+        file: m.file,
+        line: typeof m.line === "number" ? m.line : Number(m.line ?? 0),
+        text: clip(String(m.content ?? ""), lineChars),
+    }));
+    const notes = [];
+    let contextTruncated = false;
+    if (contextLines > 0 && matches.length > 0) {
+        const files = [...new Set(matches.map((m) => String(m.file)))];
+        const readable = files.filter((f) => f.startsWith("res://")).slice(0, CONTEXT_MAX_FILES);
+        if (readable.length < files.length)
+            contextTruncated = true;
+        const linesByFile = new Map();
+        for (const file of readable) {
+            try {
+                const read = asRecord(await client.readProjectFile(file, 1_000_000));
+                const content = asRecord(read?.data)?.content;
+                if (read?.ok !== false && typeof content === "string")
+                    linesByFile.set(file, content.replace(/\r\n?/g, "\n").split("\n"));
+            }
+            catch {
+                // A file that cannot be read back keeps its match without context.
+            }
+        }
+        let budget = CONTEXT_BUDGET_CHARS;
+        for (const match of matches) {
+            const lines = linesByFile.get(String(match.file));
+            const line = Number(match.line);
+            if (!lines || !Number.isInteger(line) || line < 1 || line > lines.length)
+                continue;
+            if (budget <= 0) {
+                contextTruncated = true;
+                break;
+            }
+            const before = lines.slice(Math.max(0, line - 1 - contextLines), line - 1).map((l) => clip(l, lineChars));
+            const after = lines.slice(line, line + contextLines).map((l) => clip(l, lineChars));
+            match.text = clip(lines[line - 1], lineChars);
+            if (before.length)
+                match.before = before;
+            if (after.length)
+                match.after = after;
+            budget -= [...before, ...after].reduce((sum, l) => sum + l.length + 1, 0);
+        }
+        if (contextTruncated) {
+            notes.push(`context lines were added for the first matches only (budget ${CONTEXT_MAX_FILES} files / ${CONTEXT_BUDGET_CHARS} chars); narrow path/glob for more`);
+        }
+    }
+    const engineTruncated = payload.truncated === true || rawMatches.length > maxResults;
+    if (matches.length === 0 && !args.glob) {
+        notes.push("no matches: ripgrep skips files ignored by .gitignore/.ignore — pass a glob (e.g. '*.json') to search those too");
+    }
+    if (engineTruncated) {
+        notes.push(`stopped at ${maxResults} matches; narrow the pattern/path/glob or raise max_results`);
+    }
+    return {
+        ok: true,
+        pattern: args.pattern,
+        ...(path ? { path } : {}),
+        ...(args.glob ? { glob: args.glob } : {}),
+        returned: matches.length,
+        // ripgrep stops early once max_results is reached, so this counts what it saw.
+        matches_seen: typeof payload.totalMatches === "number" ? payload.totalMatches : rawMatches.length,
+        files_with_matches: new Set(rawMatches.map((m) => String(m.file))).size,
+        truncated: engineTruncated,
+        ...(contextLines > 0 ? { context_lines: contextLines } : {}),
+        ...(contextTruncated ? { context_truncated: true } : {}),
+        matches,
+        ...(notes.length ? { notes } : {}),
+    };
+}