@greppleai/grip 0.0.0-stage → 0.1.3

package/dist/core/tools/operations.js

@@ -0,0 +1,793 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { access as fsAccess, mkdir as fsMkdir, readdir as fsReaddir, readFile as fsReadFile, stat as fsStat, writeFile as fsWriteFile, } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { pipeline } from "node:stream/promises";
+import WebSocket from "ws";
+import { DAEMON_WEBSOCKET_PROTOCOL } from "../../daemon/config.js";
+import { waitForChildProcess } from "../../utils/child-process.js";
+import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
+import { getShellConfig, getShellEnv, killProcessTree, trackDetachedChildPid, untrackDetachedChildPid, } from "../../utils/shell.js";
+import { DEFAULT_REMOTE_WORKSPACE_PROTOCOL_LIMITS, decodeCanonicalBase64, hashRemoteWorkspaceJson, parseRemoteWorkspaceToolResult, } from "../remote-workspace-protocol/contract.js";
+import { GuestSharedClientTransport } from "../remote-workspace-protocol/guest-shared-client.js";
+import { RemoteWorkspaceClientProtocol, RemoteWorkspaceRequestError, } from "../remote-workspace-protocol/session.js";
+export const GRIP_SESSION_ENVIRONMENT_NAMES = Object.freeze([
+    "GRIP_SESSION_ID",
+    "GRIP_SESSION_FILE",
+    "GRIP_PROVIDER",
+    "GRIP_MODEL",
+    "GRIP_REASONING_LEVEL",
+]);
+export function borrowToolOperations(operations) {
+    const boundMethods = new Map();
+    return new Proxy(operations, {
+        get(target, property, receiver) {
+            if (property === "dispose")
+                return undefined;
+            const value = Reflect.get(target, property, receiver);
+            if (typeof value !== "function")
+                return value;
+            let bound = boundMethods.get(property);
+            if (!bound) {
+                bound = value.bind(target);
+                boundMethods.set(property, bound);
+            }
+            return bound;
+        },
+        has(target, property) {
+            return property === "dispose" ? false : Reflect.has(target, property);
+        },
+    });
+}
+function workspaceRootsEqual(left, right, pathFlavor) {
+    if (pathFlavor === "windows")
+        return win32.normalize(left).toLowerCase() === win32.normalize(right).toLowerCase();
+    return posix.normalize(left) === posix.normalize(right);
+}
+function accessModeToFsMode(mode) {
+    switch (mode) {
+        case "read":
+            return constants.R_OK;
+        case "write":
+            return constants.W_OK;
+        case "readwrite":
+            return constants.R_OK | constants.W_OK;
+        case "exists":
+        case undefined:
+            return constants.F_OK;
+    }
+}
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
+function resolveTimeoutMs(timeout) {
+    if (timeout === undefined)
+        return undefined;
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new Error("Invalid timeout: must be a finite number of seconds");
+    }
+    const timeoutMs = timeout * 1000;
+    if (timeoutMs > MAX_TIMEOUT_MS) {
+        throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
+    }
+    return timeoutMs;
+}
+function registerChildProcessAbort(signal, child) {
+    const onAbort = () => {
+        if (child.pid)
+            killProcessTree(child.pid);
+    };
+    if (!signal)
+        return () => undefined;
+    if (signal.aborted)
+        onAbort();
+    else
+        signal.addEventListener("abort", onAbort, { once: true });
+    return () => signal.removeEventListener("abort", onAbort);
+}
+function terminateLingeringProcessGroup(child) {
+    if (!child.pid || process.platform === "win32")
+        return;
+    try {
+        process.kill(-child.pid, 0);
+        killProcessTree(child.pid);
+    }
+    catch { }
+}
+function cleanupChildExecution(child, timeoutHandle, removeAbortListener) {
+    if (child.pid)
+        untrackDetachedChildPid(child.pid);
+    if (timeoutHandle)
+        clearTimeout(timeoutHandle);
+    removeAbortListener();
+}
+async function copyFileStream(sourcePath, destinationPath) {
+    await pipeline(createReadStream(sourcePath), createWriteStream(destinationPath));
+}
+function writeStreamChunk(stream, chunk) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            stream.off("error", onError);
+            reject(error);
+        };
+        stream.once("error", onError);
+        stream.write(chunk, (error) => {
+            stream.off("error", onError);
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function endWriteStream(stream) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            stream.off("error", onError);
+            reject(error);
+        };
+        stream.once("error", onError);
+        stream.end(() => {
+            stream.off("error", onError);
+            resolve();
+        });
+    });
+}
+export class LocalToolOperations {
+    cwd;
+    shellPath;
+    constructor(cwd, options = {}) {
+        this.cwd = cwd;
+        this.shellPath = options.shellPath;
+    }
+    setShellPath(shellPath) {
+        this.shellPath = shellPath;
+    }
+    async exec(command, options) {
+        const timeoutMs = resolveTimeoutMs(options.timeout);
+        const cwd = options.cwd ?? this.cwd;
+        const { shell, args } = getShellConfig(this.shellPath);
+        try {
+            await fsAccess(cwd, constants.F_OK);
+        }
+        catch {
+            throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
+        }
+        if (options.signal?.aborted) {
+            throw new Error("aborted");
+        }
+        return new Promise((resolve, reject) => {
+            const child = spawn(shell, [...args, command], {
+                cwd,
+                detached: process.platform !== "win32",
+                env: options.env ?? getShellEnv(),
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            if (child.pid)
+                trackDetachedChildPid(child.pid);
+            let timedOut = false;
+            let timeoutHandle;
+            if (timeoutMs !== undefined) {
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    if (child.pid)
+                        killProcessTree(child.pid);
+                }, timeoutMs);
+            }
+            child.stdout?.on("data", options.onData);
+            child.stderr?.on("data", options.onData);
+            const removeAbortListener = registerChildProcessAbort(options.signal, child);
+            waitForChildProcess(child)
+                .then((code) => {
+                terminateLingeringProcessGroup(child);
+                cleanupChildExecution(child, timeoutHandle, removeAbortListener);
+                if (options.signal?.aborted) {
+                    reject(new Error("aborted"));
+                    return;
+                }
+                if (timedOut) {
+                    reject(new Error(`timeout:${options.timeout}`));
+                    return;
+                }
+                resolve({ exitCode: code });
+            })
+                .catch((error) => {
+                cleanupChildExecution(child, timeoutHandle, removeAbortListener);
+                reject(error);
+            });
+        });
+    }
+    async access(path, mode) {
+        await fsAccess(path, accessModeToFsMode(mode));
+    }
+    async readFile(path) {
+        return fsReadFile(path);
+    }
+    async writeFile(path, content) {
+        await fsWriteFile(path, content, typeof content === "string" ? "utf-8" : undefined);
+    }
+    async uploadFile(sourcePath, destinationPath) {
+        await copyFileStream(sourcePath, destinationPath);
+    }
+    async downloadFile(sourcePath, destinationPath) {
+        await copyFileStream(sourcePath, destinationPath);
+    }
+    async mkdir(path, options = {}) {
+        await fsMkdir(path, { recursive: options.recursive ?? false });
+    }
+    async stat(path) {
+        return fsStat(path);
+    }
+    async readdir(path) {
+        return fsReaddir(path);
+    }
+    async detectImageMimeType(path) {
+        return detectSupportedImageMimeTypeFromFile(path);
+    }
+    getBackendInfo() {
+        return { type: "local", cwd: this.cwd };
+    }
+}
+export class DeferredRemoteToolOperations {
+    cwd;
+    expectedCwd;
+    operations;
+    remoteCatalogUnsubscribe;
+    catalogListeners = new Set();
+    disposePromise;
+    onDisconnect;
+    constructor(cwd, onDisconnect) {
+        this.cwd = cwd;
+        this.expectedCwd = cwd;
+        this.onDisconnect = onDisconnect;
+    }
+    async configureRemote(url, options = {}) {
+        const next = await createRemoteToolOperations(url, { ...options, onDisconnect: this.onDisconnect });
+        try {
+            const stat = await next.stat(next.cwd);
+            if (!stat.isDirectory())
+                throw new Error(`Remote daemon cwd is not a directory: ${next.cwd}`);
+            const expectedCwd = options.expectedCwd ?? this.expectedCwd;
+            if (!workspaceRootsEqual(next.cwd, expectedCwd, next.workspacePathFlavor)) {
+                throw new Error(`Remote daemon workspace root mismatch: expected ${expectedCwd}, received ${next.cwd}`);
+            }
+        }
+        catch (error) {
+            await next.dispose();
+            throw error;
+        }
+        await this.replaceOperations(next);
+        return this.getBackendInfo();
+    }
+    async clear() {
+        const previous = this.operations;
+        this.remoteCatalogUnsubscribe?.();
+        this.remoteCatalogUnsubscribe = undefined;
+        this.operations = undefined;
+        await previous?.dispose?.();
+    }
+    requireOperations() {
+        if (!this.operations) {
+            throw new Error("Remote backend is not configured. Configure it over RPC or with /sandbox before using tools.");
+        }
+        return this.operations;
+    }
+    async exec(command, options) {
+        return this.requireOperations().exec(command, options);
+    }
+    async access(path, mode) {
+        await this.requireOperations().access(path, mode);
+    }
+    async readFile(path) {
+        return this.requireOperations().readFile(path);
+    }
+    async writeFile(path, content) {
+        await this.requireOperations().writeFile(path, content);
+    }
+    async uploadFile(sourcePath, destinationPath) {
+        const operations = this.requireOperations();
+        if (!operations.uploadFile)
+            throw new Error("Remote backend does not support file upload");
+        await operations.uploadFile(sourcePath, destinationPath);
+    }
+    async downloadFile(sourcePath, destinationPath) {
+        const operations = this.requireOperations();
+        if (!operations.downloadFile)
+            throw new Error("Remote backend does not support file download");
+        await operations.downloadFile(sourcePath, destinationPath);
+    }
+    async mkdir(path, options) {
+        await this.requireOperations().mkdir(path, options);
+    }
+    async stat(path) {
+        return this.requireOperations().stat(path);
+    }
+    async readdir(path) {
+        return this.requireOperations().readdir(path);
+    }
+    async glob(pattern, cwd, options) {
+        return this.requireOperations().glob(pattern, cwd, options);
+    }
+    async grep(options) {
+        return this.requireOperations().grep(options);
+    }
+    async detectImageMimeType(path) {
+        return this.requireOperations().detectImageMimeType(path);
+    }
+    getBackendInfo() {
+        return this.operations?.getBackendInfo() ?? { type: "remote", cwd: this.cwd, configured: false };
+    }
+    isDisconnected() {
+        return this.operations?.isDisconnected() ?? false;
+    }
+    resolveWorkspaceToolExecution(name, parameterSchema) {
+        return this.operations ? this.operations.resolveWorkspaceToolExecution(name, parameterSchema) : "unavailable";
+    }
+    executeWorkspaceTool(name, invocation) {
+        return this.requireOperations().executeWorkspaceTool(name, invocation);
+    }
+    getRemoteLspStatus() {
+        return this.operations?.getRemoteLspStatus() ?? { enabled: false, servers: [] };
+    }
+    onWorkspaceToolCatalogChanged(listener) {
+        this.catalogListeners.add(listener);
+        return () => this.catalogListeners.delete(listener);
+    }
+    dispose() {
+        this.disposePromise ??= (async () => {
+            this.remoteCatalogUnsubscribe?.();
+            this.remoteCatalogUnsubscribe = undefined;
+            const previous = this.operations;
+            this.operations = undefined;
+            await previous?.dispose?.();
+        })();
+        return this.disposePromise;
+    }
+    async replaceOperations(next) {
+        if (this.disposePromise) {
+            await next.dispose?.();
+            throw new Error("Deferred remote backend is disposed");
+        }
+        const previous = this.operations;
+        this.remoteCatalogUnsubscribe?.();
+        this.remoteCatalogUnsubscribe = undefined;
+        this.operations = next;
+        this.cwd = next.cwd;
+        this.remoteCatalogUnsubscribe = next.onWorkspaceToolCatalogChanged(() => Promise.all([...this.catalogListeners].map((listener) => listener())).then(() => undefined));
+        await previous?.dispose?.();
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function requireRecord(value, label) {
+    if (!isRecord(value))
+        throw new Error(`Invalid remote workspace ${label}`);
+    return value;
+}
+function requireString(value, label) {
+    if (typeof value !== "string")
+        throw new Error(`Invalid remote workspace ${label}`);
+    return value;
+}
+function normalizeRemoteUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+        throw new Error(`--remote supports ws:// and wss:// URLs, got ${parsed.protocol}`);
+    }
+    if (parsed.username || parsed.password)
+        throw new Error("Remote workspace URLs must not contain credentials");
+    if (parsed.hash)
+        throw new Error("Remote workspace URLs must not contain fragments");
+    return { url: parsed.toString(), protocol: "ws" };
+}
+function websocketPayload(data) {
+    if (Buffer.isBuffer(data))
+        return Uint8Array.from(data);
+    if (Array.isArray(data))
+        return Uint8Array.from(Buffer.concat(data));
+    return Uint8Array.from(new Uint8Array(data));
+}
+function websocketCloseCode(reason) {
+    switch (reason.code) {
+        case "normal":
+            return 1000;
+        case "protocol_error":
+            return 1002;
+        case "invalid_payload":
+            return 1007;
+        case "policy_violation":
+            return 1008;
+        case "message_too_large":
+            return 1009;
+    }
+}
+export class RemoteToolOperations {
+    url;
+    protocol;
+    cwd;
+    workspacePathFlavor = "posix";
+    workspaceId = "";
+    socket;
+    isShared;
+    client;
+    localToolSchemas = new Map();
+    catalogListeners = new Set();
+    remoteLspStatus = { enabled: false, servers: [] };
+    disconnected = false;
+    disposePromise;
+    constructor(url, protocol, socket, options) {
+        this.url = url;
+        this.protocol = protocol;
+        this.socket = socket;
+        this.isShared = socket instanceof GuestSharedClientTransport;
+        this.cwd = "/";
+        const transport = socket instanceof GuestSharedClientTransport
+            ? socket
+            : {
+                send: (message) => new Promise((resolve, reject) => {
+                    if (socket.readyState !== WebSocket.OPEN) {
+                        reject(new Error("Remote workspace connection is not open"));
+                        return;
+                    }
+                    socket.send(JSON.stringify(message), { binary: false, compress: false }, (error) => {
+                        if (error)
+                            reject(error);
+                        else
+                            resolve();
+                    });
+                }),
+                close: (reason) => {
+                    if (socket.readyState === WebSocket.CLOSED)
+                        return Promise.resolve();
+                    return new Promise((resolve) => {
+                        socket.once("close", () => resolve());
+                        socket.close(websocketCloseCode(reason), reason.message);
+                    });
+                },
+            };
+        this.client = new RemoteWorkspaceClientProtocol(transport, {
+            requiredCapabilities: ["primitive_operations", "tool_updates"],
+            optionalCapabilities: this.isShared
+                ? ["catalog_refresh", "artifacts", "lsp_status"]
+                : ["catalog_refresh", "file_transfer", "artifacts", "lsp_status"],
+            receiveLimits: DEFAULT_REMOTE_WORKSPACE_PROTOCOL_LIMITS,
+            localToolSchemas: this.localToolSchemas,
+            handshakeTimeoutMs: options.handshakeTimeoutMs,
+            onDisconnect: (message) => {
+                this.disconnected = true;
+                options.onDisconnect?.(message);
+            },
+            onCatalogRefreshed: async () => {
+                await this.refreshRemoteLspStatus();
+                await Promise.all([...this.catalogListeners].map((listener) => listener()));
+            },
+        });
+        if (socket instanceof GuestSharedClientTransport) {
+            socket.bind(this.client);
+        }
+        else {
+            socket.on("message", (data, isBinary) => {
+                if (isBinary) {
+                    void this.client.disconnect("Remote workspace sent an unexpected binary frame");
+                    return;
+                }
+                void this.client.receive(websocketPayload(data)).catch(() => undefined);
+            });
+            socket.on("close", () => void this.client.disconnect("Remote workspace connection closed"));
+            socket.on("error", () => void this.client.disconnect("Remote workspace connection failed"));
+        }
+    }
+    static async connect(url, options = {}) {
+        const normalized = normalizeRemoteUrl(url);
+        const token = options.token ?? process.env.GRIP_REMOTE_TOKEN;
+        const socket = await new Promise((resolve, reject) => {
+            const websocket = new WebSocket(normalized.url, DAEMON_WEBSOCKET_PROTOCOL, {
+                perMessageDeflate: false,
+                ...(token ? { headers: { authorization: `Bearer ${token}` } } : {}),
+            });
+            const cleanup = () => {
+                websocket.off("open", onOpen);
+                websocket.off("error", onError);
+            };
+            const onOpen = () => {
+                cleanup();
+                resolve(websocket);
+            };
+            const onError = () => {
+                cleanup();
+                websocket.terminate();
+                reject(new Error(`Failed to connect remote workspace: ${normalized.url}`));
+            };
+            websocket.once("open", onOpen);
+            websocket.once("error", onError);
+        });
+        const operations = new RemoteToolOperations(normalized.url, normalized.protocol, socket, options);
+        try {
+            const handshake = await operations.client.start();
+            operations.cwd = handshake.workspace.root;
+            operations.workspacePathFlavor = handshake.workspace.pathFlavor;
+            operations.workspaceId = handshake.workspace.id;
+            await operations.refreshRemoteLspStatus();
+            return operations;
+        }
+        catch (error) {
+            socket.terminate();
+            throw error;
+        }
+    }
+    static async connectGuestShared(url, root, token, options = {}) {
+        const socket = await GuestSharedClientTransport.attach(url, root, token);
+        const operations = new RemoteToolOperations(url, "ws", socket, options);
+        try {
+            const handshake = await operations.client.start();
+            if (!workspaceRootsEqual(handshake.workspace.root, root, handshake.workspace.pathFlavor)) {
+                throw new Error("Guest shared workspace root differs from daemon handshake");
+            }
+            operations.cwd = handshake.workspace.root;
+            operations.workspacePathFlavor = handshake.workspace.pathFlavor;
+            operations.workspaceId = handshake.workspace.id;
+            await operations.refreshRemoteLspStatus();
+            return operations;
+        }
+        catch (error) {
+            await socket.close({ code: "normal", message: "Shared guest attach failed" });
+            throw error;
+        }
+    }
+    resolveWorkspaceToolExecution(name, parameterSchema) {
+        const schemaHash = hashRemoteWorkspaceJson(parameterSchema);
+        const catalogTool = this.client.handshake?.catalog.tools.find((tool) => tool.name === name);
+        if (!catalogTool)
+            return "unavailable";
+        if (catalogTool.schemaHash !== schemaHash) {
+            throw new Error(`Remote tool schema does not match the local canonical definition: ${name}`);
+        }
+        this.localToolSchemas.set(name, schemaHash);
+        this.client.setLocalToolSchemas(this.localToolSchemas);
+        return "remote";
+    }
+    async executeWorkspaceTool(name, invocation) {
+        const invoke = async () => {
+            await this.client.waitForCatalogRefresh();
+            const handshake = this.client.handshake;
+            if (!handshake)
+                throw new Error("Remote workspace protocol handshake is unavailable");
+            const catalogTool = handshake.catalog.tools.find((tool) => tool.name === name);
+            const schemaHash = this.localToolSchemas.get(name);
+            if (!catalogTool || !schemaHash || catalogTool.schemaHash !== schemaHash) {
+                throw new Error(`Remote tool is unavailable or has schema drift: ${name}`);
+            }
+            const expectedRevision = await this.revisionForTool(name, invocation);
+            const result = requireRecord(await this.client.request("tool.invoke", {
+                generation: handshake.catalog.generation,
+                catalogHash: handshake.catalogHash,
+                toolName: name,
+                schemaHash,
+                argumentsPrepared: true,
+                arguments: invocation.arguments,
+                ...(expectedRevision ? { expectedRevision } : {}),
+                executionOptions: invocation.executionOptions,
+            }, {
+                signal: invocation.signal,
+                onUpdate: invocation.onUpdate
+                    ? (update) => invocation.onUpdate(parseRemoteWorkspaceToolResult(update))
+                    : undefined,
+            }), "tool result");
+            const toolResult = result;
+            if (!Array.isArray(toolResult.content))
+                throw new Error("Invalid remote workspace tool result content");
+            if (name.startsWith("lsp_"))
+                await this.refreshRemoteLspStatus().catch(() => undefined);
+            return {
+                content: toolResult.content,
+                details: toolResult.details,
+                ...(typeof toolResult.terminate === "boolean" ? { terminate: toolResult.terminate } : {}),
+            };
+        };
+        try {
+            return await invoke();
+        }
+        catch (error) {
+            if (error instanceof RemoteWorkspaceRequestError &&
+                error.code === "stale_generation" &&
+                error.executionState === "not_started") {
+                return invoke();
+            }
+            throw error;
+        }
+    }
+    getRemoteLspStatus() {
+        return structuredClone(this.remoteLspStatus);
+    }
+    onWorkspaceToolCatalogChanged(listener) {
+        this.catalogListeners.add(listener);
+        return () => this.catalogListeners.delete(listener);
+    }
+    async refreshRemoteLspStatus() {
+        if (!this.client.handshake?.catalog.operations.includes("lsp.status")) {
+            this.remoteLspStatus = { enabled: false, servers: [] };
+            return;
+        }
+        this.remoteLspStatus = (await this.client.request("lsp.status", {}));
+    }
+    request(method, params) {
+        return this.client.request(method, params);
+    }
+    async revisionForTool(name, invocation) {
+        if (!this.isShared || (name !== "edit" && name !== "write"))
+            return undefined;
+        const path = requireString(requireRecord(invocation.arguments, "shared mutation arguments").path, "shared mutation path");
+        return this.sharedExpectedRevision(path, invocation.signal, name === "write");
+    }
+    /** Observe exact bytes for CAS, or a daemon-confirmed absent target for creation. */
+    async sharedExpectedRevision(path, signal, allowAbsent = true) {
+        let read;
+        try {
+            read = await this.client.request("workspace.read", { path }, { signal });
+        }
+        catch (error) {
+            if (!allowAbsent)
+                throw error;
+            // Do not infer absence from an error message: only a v2 server stat of the
+            // same workspace and path may establish the expected-absent precondition.
+            const stat = requireRecord(await this.client.request("workspace.stat", { path }, { signal }), "shared stat result");
+            if (stat.kind !== "absent")
+                throw error;
+            return { absent: true };
+        }
+        const result = requireRecord(read, "shared read result");
+        const content = decodeCanonicalBase64(requireString(result.contentBase64, "shared read content"), Number.MAX_SAFE_INTEGER);
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        if (result.revision !== sha256)
+            throw new Error("Shared daemon did not confirm the observed file revision");
+        return { sha256 };
+    }
+    async exec(command, options) {
+        const result = requireRecord(await this.client.request("workspace.exec", { command, cwd: options.cwd ?? this.cwd }, {
+            signal: options.signal,
+            timeoutMs: options.timeout === undefined ? undefined : Math.round(options.timeout * 1000),
+            onUpdate: (update) => {
+                const record = requireRecord(update, "exec update");
+                options.onData(decodeCanonicalBase64(requireString(record.dataBase64, "exec update data"), 1024 * 1024));
+            },
+        }), "exec result");
+        return { exitCode: typeof result.exitCode === "number" ? result.exitCode : null };
+    }
+    async access(path, mode) {
+        await this.request("workspace.access", { path, ...(mode ? { mode } : {}) });
+    }
+    async readFile(path) {
+        const result = requireRecord(await this.request("workspace.read", { path }), "read result");
+        return decodeCanonicalBase64(requireString(result.contentBase64, "read content"), Number.MAX_SAFE_INTEGER);
+    }
+    async writeFile(path, content) {
+        const expectedRevision = this.isShared ? await this.sharedExpectedRevision(path) : undefined;
+        await this.request("workspace.write", {
+            path,
+            contentBase64: Buffer.from(content).toString("base64"),
+            ...(expectedRevision ? { expectedRevision } : {}),
+        });
+    }
+    async readResource(path) {
+        if (!this.client.handshake?.catalog.operations.includes("resource.read")) {
+            throw new Error("Remote workspace does not expose resource reads");
+        }
+        const result = requireRecord(await this.request("resource.read", { path }), "resource read result");
+        return decodeCanonicalBase64(requireString(result.contentBase64, "resource read content"), Number.MAX_SAFE_INTEGER);
+    }
+    async uploadFile(sourcePath, destinationPath) {
+        if (this.isShared)
+            throw new Error("Shared guest file transfers are unavailable");
+        const content = await fsReadFile(sourcePath);
+        const sha256 = createHash("sha256").update(content).digest("hex");
+        const handle = this.client.beginRequest("transfer.upload", {
+            path: destinationPath,
+            length: content.byteLength,
+            sha256,
+            overwrite: true,
+        });
+        const chunkBytes = this.client.handshake?.limits.maxTransferChunkBytes ?? 64 * 1024;
+        for (let offset = 0; offset < content.byteLength; offset += chunkBytes) {
+            await handle.sendTransferChunk(content.subarray(offset, Math.min(offset + chunkBytes, content.byteLength)));
+        }
+        await handle.finishTransfer(content.byteLength, sha256);
+        await handle.result;
+    }
+    async downloadFile(sourcePath, destinationPath) {
+        if (this.isShared)
+            throw new Error("Shared guest file transfers are unavailable");
+        const stream = createWriteStream(destinationPath);
+        try {
+            await this.client.request("transfer.download", { path: sourcePath }, {
+                onTransferChunk: (chunk) => writeStreamChunk(stream, chunk),
+            });
+            await endWriteStream(stream);
+        }
+        catch (error) {
+            stream.destroy();
+            throw error;
+        }
+    }
+    async mkdir(path, options = {}) {
+        await this.request("workspace.mkdir", { path, recursive: options.recursive ?? false });
+    }
+    async stat(path) {
+        const result = requireRecord(await this.request("workspace.stat", { path }), "stat result");
+        if (result.kind === "absent")
+            throw new Error(`Remote workspace path does not exist: ${path}`);
+        return {
+            isDirectory: () => result.kind === "directory",
+            isFile: () => result.kind === "file",
+        };
+    }
+    async readdir(path) {
+        const result = requireRecord(await this.request("workspace.readdir", { path }), "readdir result");
+        if (!Array.isArray(result.entries) || !result.entries.every((entry) => typeof entry === "string")) {
+            throw new Error("Invalid remote workspace readdir entries");
+        }
+        return result.entries;
+    }
+    async glob(pattern, cwd, options) {
+        const result = requireRecord(await this.request("workspace.glob", { pattern, cwd, ignore: options.ignore, limit: options.limit }), "glob result");
+        if (!Array.isArray(result.matches) || !result.matches.every((entry) => typeof entry === "string")) {
+            throw new Error("Invalid remote workspace glob matches");
+        }
+        return result.matches;
+    }
+    async grep(options) {
+        const result = requireRecord(await this.request("workspace.grep", options), "grep result");
+        if (!Array.isArray(result.matches))
+            throw new Error("Invalid remote workspace grep matches");
+        return {
+            isDirectory: result.isDirectory === true,
+            matches: result.matches.map((entry) => {
+                const match = requireRecord(entry, "grep match");
+                return {
+                    filePath: requireString(match.filePath, "grep file path"),
+                    lineNumber: typeof match.lineNumber === "number" ? match.lineNumber : 0,
+                    ...(typeof match.lineText === "string" ? { lineText: match.lineText } : {}),
+                };
+            }),
+        };
+    }
+    async detectImageMimeType(path) {
+        const result = requireRecord(await this.request("workspace.detect_image_mime", { path }), "image MIME result");
+        return typeof result.mimeType === "string" ? result.mimeType : null;
+    }
+    getBackendInfo() {
+        return {
+            type: "remote",
+            cwd: this.cwd,
+            url: this.url,
+            protocol: this.protocol,
+            configured: true,
+            workspace: { id: this.workspaceId, root: this.cwd, pathFlavor: this.workspacePathFlavor },
+        };
+    }
+    isDisconnected() {
+        return this.disconnected;
+    }
+    dispose() {
+        this.disposePromise ??= this.client.close().catch(() => {
+            if (this.socket instanceof WebSocket)
+                this.socket.terminate();
+        });
+        return this.disposePromise;
+    }
+}
+export function createRemoteToolOperations(url, options) {
+    if (url.startsWith("grip+ws:")) {
+        const parsed = new URL(url.replace(/^grip\+/, ""));
+        const root = parsed.searchParams.get("root");
+        if (!root || !posix.isAbsolute(root) || parsed.searchParams.size !== 1 || !options?.token) {
+            return Promise.reject(new Error("Invalid guest shared workspace attachment"));
+        }
+        parsed.search = "";
+        return RemoteToolOperations.connectGuestShared(parsed.toString(), root, options.token, options);
+    }
+    return RemoteToolOperations.connect(url, options);
+}
+//# sourceMappingURL=operations.js.map