@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/relay-transport.js

@@ -0,0 +1,481 @@
+/// <reference lib="dom" />
+import { EventEmitter } from "node:events";
+import { WebSocket } from "ws";
+import { createDaemonChannel, } from "@camerontaylor/paseo-relay/e2ee";
+import { buildRelayWebSocketUrl } from "@camerontaylor/paseo-protocol/daemon-endpoints";
+import { createEncryptedRelaySocket } from "./websocket/encrypted-relay-socket.js";
+const CONTROL_PING_INTERVAL_MS = 10000;
+const CONTROL_STALE_TIMEOUT_MS = 30000;
+const CONTROL_READY_TIMEOUT_MS = 8000;
+const RELAY_WEBSOCKET_OPTIONS = { handshakeTimeout: 10000, perMessageDeflate: false };
+function createDefaultRelayWebSocket(url) {
+    return new WebSocket(url, RELAY_WEBSOCKET_OPTIONS);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function tryParseControlMessage(raw) {
+    try {
+        let text;
+        if (typeof raw === "string") {
+            text = raw;
+        }
+        else if (Buffer.isBuffer(raw)) {
+            text = raw.toString("utf8");
+        }
+        else {
+            text = String(raw);
+        }
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed))
+            return null;
+        if (parsed.type === "ping")
+            return { type: "ping" };
+        if (parsed.type === "pong")
+            return { type: "pong" };
+        if (parsed.type === "sync" && Array.isArray(parsed.connectionIds)) {
+            const connectionIds = parsed.connectionIds.filter((id) => typeof id === "string" && id.trim().length > 0);
+            return { type: "sync", connectionIds };
+        }
+        if (parsed.type === "connected" &&
+            typeof parsed.connectionId === "string" &&
+            parsed.connectionId.trim()) {
+            return { type: "connected", connectionId: parsed.connectionId.trim() };
+        }
+        if (parsed.type === "disconnected" &&
+            typeof parsed.connectionId === "string" &&
+            parsed.connectionId.trim()) {
+            return { type: "disconnected", connectionId: parsed.connectionId.trim() };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function startRelayTransport({ logger, attachSocket, relayEndpoint, relayUseTls, serverId, daemonKeyPair, createWebSocket = createDefaultRelayWebSocket, }) {
+    const relayLogger = logger.child({ module: "relay-transport" });
+    let stopped = false;
+    let controlWs = null;
+    let reconnectTimeout = null;
+    let reconnectAttempt = 0;
+    const dataSockets = new Map(); // connectionId -> ws
+    let controlKeepaliveInterval = null;
+    let controlReadyTimeout = null;
+    let controlLastSeenAt = 0;
+    let controlConnectionSeq = 0;
+    const stop = async () => {
+        stopped = true;
+        if (reconnectTimeout) {
+            clearTimeout(reconnectTimeout);
+            reconnectTimeout = null;
+        }
+        if (controlKeepaliveInterval) {
+            clearInterval(controlKeepaliveInterval);
+            controlKeepaliveInterval = null;
+        }
+        if (controlReadyTimeout) {
+            clearTimeout(controlReadyTimeout);
+            controlReadyTimeout = null;
+        }
+        if (controlWs) {
+            try {
+                controlWs.close();
+            }
+            catch {
+                // ignore
+            }
+            controlWs = null;
+        }
+        for (const ws of dataSockets.values()) {
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        dataSockets.clear();
+    };
+    const connectControl = () => {
+        if (stopped)
+            return;
+        const connectionId = ++controlConnectionSeq;
+        const url = buildRelayWebSocketUrl({
+            endpoint: relayEndpoint,
+            useTls: relayUseTls,
+            serverId,
+            role: "server",
+        });
+        const socket = createWebSocket(url);
+        controlWs = socket;
+        let controlConnected = false;
+        const markControlReady = () => {
+            if (controlWs !== socket)
+                return;
+            if (controlConnected)
+                return;
+            controlConnected = true;
+            reconnectAttempt = 0;
+            if (controlReadyTimeout) {
+                clearTimeout(controlReadyTimeout);
+                controlReadyTimeout = null;
+            }
+            relayLogger.info({ connectionId }, "relay_control_connected");
+        };
+        socket.on("open", () => {
+            if (controlWs !== socket)
+                return;
+            controlLastSeenAt = Date.now();
+            if (controlKeepaliveInterval) {
+                clearInterval(controlKeepaliveInterval);
+                controlKeepaliveInterval = null;
+            }
+            if (controlReadyTimeout) {
+                clearTimeout(controlReadyTimeout);
+                controlReadyTimeout = null;
+            }
+            controlReadyTimeout = setTimeout(() => {
+                if (stopped)
+                    return;
+                if (controlWs !== socket)
+                    return;
+                if (controlConnected)
+                    return;
+                relayLogger.warn({ url, connectionId, waitedMs: CONTROL_READY_TIMEOUT_MS }, "relay_control_ready_timeout_terminating");
+                try {
+                    socket.terminate();
+                }
+                catch {
+                    // ignore
+                }
+            }, CONTROL_READY_TIMEOUT_MS);
+            controlKeepaliveInterval = setInterval(() => {
+                if (stopped)
+                    return;
+                if (controlWs !== socket)
+                    return;
+                if (socket.readyState !== WebSocket.OPEN)
+                    return;
+                const now = Date.now();
+                const staleForMs = now - controlLastSeenAt;
+                // If the control socket is half-open or silently dropped, ws may never emit "close".
+                // Use a WebSocket protocol ping to detect staleness and force a reconnect.
+                // Cloudflare's runtime auto-responds to protocol pings at the edge without waking the
+                // hibernated relay Durable Object, so this keepalive does not incur DO CPU billing.
+                if (staleForMs > CONTROL_STALE_TIMEOUT_MS) {
+                    relayLogger.warn({ url, staleForMs, connectionId, staleTimeoutMs: CONTROL_STALE_TIMEOUT_MS }, "relay_control_stale_terminating");
+                    try {
+                        socket.terminate();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    return;
+                }
+                try {
+                    socket.ping();
+                }
+                catch (error) {
+                    relayLogger.warn({ err: error, connectionId }, "relay_control_ping_send_failed");
+                    try {
+                        socket.terminate();
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }, CONTROL_PING_INTERVAL_MS);
+            try {
+                socket.ping();
+            }
+            catch (error) {
+                relayLogger.warn({ err: error, connectionId }, "relay_control_ping_send_failed");
+                try {
+                    socket.terminate();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            relayLogger.debug({ connectionId }, "relay_control_open_waiting_for_ready");
+        });
+        socket.on("close", (code, reason) => {
+            if (controlWs !== socket)
+                return;
+            relayLogger.warn({ code, reason: reason?.toString?.(), url, connectionId }, "relay_control_disconnected");
+            controlWs = null;
+            if (controlKeepaliveInterval) {
+                clearInterval(controlKeepaliveInterval);
+                controlKeepaliveInterval = null;
+            }
+            if (controlReadyTimeout) {
+                clearTimeout(controlReadyTimeout);
+                controlReadyTimeout = null;
+            }
+            scheduleReconnect();
+        });
+        socket.on("error", (err) => {
+            if (controlWs !== socket)
+                return;
+            relayLogger.warn({ err, connectionId }, "relay_error");
+            // close event will schedule reconnect
+        });
+        socket.on("pong", () => {
+            if (controlWs !== socket)
+                return;
+            controlLastSeenAt = Date.now();
+            relayLogger.debug({ connectionId }, "relay_control_pong_received");
+        });
+        socket.on("message", (data) => {
+            if (controlWs !== socket)
+                return;
+            controlLastSeenAt = Date.now();
+            const msg = tryParseControlMessage(data);
+            if (msg) {
+                markControlReady();
+            }
+            if (!msg)
+                return;
+            if (msg.type === "ping") {
+                try {
+                    socket.send(JSON.stringify({ type: "pong", ts: Date.now() }));
+                }
+                catch {
+                    // ignore
+                }
+                return;
+            }
+            if (msg.type === "pong")
+                return;
+            if (msg.type === "sync") {
+                for (const clientConnectionId of msg.connectionIds) {
+                    ensureClientDataSocket(clientConnectionId);
+                }
+                return;
+            }
+            if (msg.type === "connected") {
+                ensureClientDataSocket(msg.connectionId);
+                return;
+            }
+            if (msg.type === "disconnected") {
+                const existing = dataSockets.get(msg.connectionId);
+                if (existing) {
+                    try {
+                        existing.close(1001, "Client disconnected");
+                    }
+                    catch {
+                        // ignore
+                    }
+                    dataSockets.delete(msg.connectionId);
+                }
+            }
+        });
+    };
+    const scheduleReconnect = () => {
+        if (stopped)
+            return;
+        if (reconnectTimeout)
+            return;
+        reconnectAttempt += 1;
+        const delayMs = Math.min(30000, 1000 * reconnectAttempt);
+        reconnectTimeout = setTimeout(() => {
+            reconnectTimeout = null;
+            connectControl();
+        }, delayMs);
+    };
+    const ensureClientDataSocket = (connectionId) => {
+        if (stopped)
+            return;
+        if (!connectionId)
+            return;
+        if (dataSockets.has(connectionId))
+            return;
+        const url = buildRelayWebSocketUrl({
+            endpoint: relayEndpoint,
+            useTls: relayUseTls,
+            serverId,
+            role: "server",
+            connectionId,
+        });
+        const socket = createWebSocket(url);
+        dataSockets.set(connectionId, socket);
+        let attached = false;
+        const openTimeout = setTimeout(() => {
+            if (stopped)
+                return;
+            if (socket.readyState === WebSocket.OPEN)
+                return;
+            relayLogger.warn({ connectionId }, "relay_data_open_timeout_terminating");
+            try {
+                socket.terminate();
+            }
+            catch {
+                // ignore
+            }
+        }, 15000);
+        socket.on("open", () => {
+            clearTimeout(openTimeout);
+            relayLogger.info({ connectionId }, "relay_data_connected");
+            if (attached)
+                return;
+            attached = true;
+            const externalMetadata = {
+                transport: "relay",
+                externalSessionKey: `session:${connectionId}`,
+                relayConnectionId: connectionId,
+            };
+            if (daemonKeyPair) {
+                void attachEncryptedSocket(socket, daemonKeyPair, relayLogger.child({ connectionId }), attachSocket, externalMetadata);
+            }
+            else {
+                void attachSocket(socket, externalMetadata);
+            }
+        });
+        socket.on("close", (code, reason) => {
+            clearTimeout(openTimeout);
+            relayLogger.warn({ code, reason: reason?.toString?.(), url, connectionId }, "relay_data_disconnected");
+            if (dataSockets.get(connectionId) === socket) {
+                dataSockets.delete(connectionId);
+            }
+        });
+        socket.on("error", (err) => {
+            relayLogger.warn({ err, connectionId }, "relay_data_error");
+        });
+    };
+    connectControl();
+    return { stop };
+}
+async function attachEncryptedSocket(socket, daemonKeyPair, logger, attachSocket, metadata) {
+    try {
+        const relayTransport = createRelayTransportAdapter(socket, logger);
+        const emitter = new EventEmitter();
+        const pendingMessages = [];
+        let attached = false;
+        const emitMessage = (data) => {
+            if (attached) {
+                emitter.emit("message", data);
+                return;
+            }
+            pendingMessages.push(data);
+        };
+        const channel = await createDaemonChannel(relayTransport, daemonKeyPair, {
+            onmessage: emitMessage,
+            onclose: (code, reason) => emitter.emit("close", code, reason),
+            onerror: (error) => {
+                logger.warn({ err: error }, "relay_e2ee_error");
+                emitter.emit("error", error);
+            },
+        });
+        const encryptedSocket = createEncryptedRelaySocket({
+            channel,
+            emitter,
+            getTransportBufferedAmount: () => socket.bufferedAmount,
+            terminateTransport: () => socket.terminate(),
+        });
+        await attachSocket(encryptedSocket, metadata);
+        attached = true;
+        for (const message of pendingMessages) {
+            emitter.emit("message", message);
+        }
+        pendingMessages.length = 0;
+    }
+    catch (error) {
+        logger.warn({ err: error }, "relay_e2ee_handshake_failed");
+        try {
+            socket.close(1011, "E2EE handshake failed");
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+function createRelayTransportAdapter(socket, logger) {
+    const relayTransport = {
+        send: (data) => new Promise((resolve, reject) => {
+            try {
+                socket.send(data, (error) => {
+                    if (!error) {
+                        resolve();
+                        return;
+                    }
+                    logger.warn({ err: error }, "relay_socket_send_failed");
+                    reject(error);
+                });
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger.warn({ err }, "relay_socket_send_failed");
+                reject(err);
+            }
+        }),
+        close: (code, reason) => socket.close(code, reason),
+        onmessage: null,
+        onclose: null,
+        onerror: null,
+    };
+    socket.on("message", (data, isBinary) => {
+        const binary = isBinary === true;
+        relayTransport.onmessage?.({ data: normalizeMessageData(data, binary), isBinary: binary });
+    });
+    socket.on("close", (code, reason) => {
+        const closeCode = typeof code === "number" ? code : 1006;
+        relayTransport.onclose?.(closeCode, String(reason ?? ""));
+    });
+    socket.on("error", (err) => {
+        relayTransport.onerror?.(err instanceof Error ? err : new Error(String(err)));
+    });
+    return relayTransport;
+}
+function normalizeMessageData(data, isBinary) {
+    if (!isBinary) {
+        if (typeof data === "string")
+            return data;
+        const buffer = bufferFromWsData(data);
+        if (buffer)
+            return buffer.toString("utf8");
+        return String(data);
+    }
+    if (data instanceof ArrayBuffer)
+        return data;
+    const buffer = bufferFromWsData(data);
+    if (buffer) {
+        const view = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+        const out = new Uint8Array(view.byteLength);
+        out.set(view);
+        return out.buffer;
+    }
+    return String(data);
+}
+function bufferFromWsData(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (Array.isArray(data)) {
+        const buffers = [];
+        for (const part of data) {
+            if (Buffer.isBuffer(part)) {
+                buffers.push(part);
+            }
+            else if (part instanceof ArrayBuffer) {
+                buffers.push(Buffer.from(part));
+            }
+            else if (ArrayBuffer.isView(part)) {
+                buffers.push(Buffer.from(part.buffer, part.byteOffset, part.byteLength));
+            }
+            else if (typeof part === "string") {
+                buffers.push(Buffer.from(part, "utf8"));
+            }
+            else {
+                return null;
+            }
+        }
+        return Buffer.concat(buffers);
+    }
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    if (ArrayBuffer.isView(data)) {
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return null;
+}
+//# sourceMappingURL=relay-transport.js.map

package/dist/server/server/request-receipts/index.d.ts

@@ -0,0 +1,33 @@
+interface CreateAgentInput {
+    key: string;
+    request: unknown;
+    findAgent: (agentId: string) => Promise<boolean>;
+    create: (agentId: string) => Promise<void>;
+}
+interface CreateWorkspaceInput {
+    key: string;
+    request: unknown;
+    workspaceId: string;
+    findWorkspace: (workspaceId: string) => Promise<boolean>;
+    create: (workspaceId: string) => Promise<void>;
+}
+interface SendMessageInput {
+    agentId: string;
+    messageId: string;
+    request: unknown;
+    send: () => Promise<void>;
+    prepare?: () => Promise<void>;
+}
+/** One daemon-owned request journal, shared by all of its socket sessions. */
+export declare class RequestReceipts {
+    private readonly directory;
+    private readonly pending;
+    constructor(directory: string);
+    createAgent(input: CreateAgentInput): Promise<string>;
+    createWorkspace(input: CreateWorkspaceInput): Promise<string>;
+    sendMessage(input: SendMessageInput): Promise<void>;
+    private execute;
+    private executeOnce;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/server/server/request-receipts/index.js

@@ -0,0 +1,131 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeJsonFileAtomic } from "../atomic-file.js";
+const ReceiptStateSchema = z.object({
+    fingerprint: z.string(),
+    state: z.enum(["pending", "completed"]),
+});
+// Preserve existing agent receipt files while giving workspaces their own identity.
+const ReceiptSchema = z.union([
+    ReceiptStateSchema.extend({ agentId: z.string() }),
+    ReceiptStateSchema.extend({ workspaceId: z.string() }),
+]);
+/** One daemon-owned request journal, shared by all of its socket sessions. */
+export class RequestReceipts {
+    constructor(directory) {
+        this.directory = directory;
+        this.pending = new Map();
+    }
+    createAgent(input) {
+        return this.execute(["create", input.key], input.request, {
+            resource: { kind: "agent", id: randomUUID() },
+            recover: input.findAgent,
+            run: input.create,
+            retrySafe: async (agentId) => !(await input.findAgent(agentId)),
+        });
+    }
+    createWorkspace(input) {
+        return this.execute(["create-workspace", input.key], input.request, {
+            resource: { kind: "workspace", id: input.workspaceId },
+            // A registry entry can survive failed provisioning and checkout rollback.
+            // Only a completed receipt proves that the entire operation succeeded.
+            recover: async () => false,
+            run: input.create,
+            retrySafe: async (workspaceId) => !(await input.findWorkspace(workspaceId)),
+        });
+    }
+    async sendMessage(input) {
+        await this.execute(["send", input.agentId, input.messageId], input.request, {
+            resource: { kind: "agent", id: input.agentId },
+            // A provider call can take effect before the daemon records its outcome.
+            // Never repeat that call merely because a process died in this window.
+            recover: async () => false,
+            run: input.send,
+            prepare: input.prepare,
+        });
+    }
+    execute(identity, request, operation) {
+        const key = digest(identity);
+        const fingerprint = digest(request);
+        const previous = this.pending.get(key);
+        // Serialize even conflicting requests: each caller validates its own fingerprint.
+        const result = (previous ? previous.catch(() => undefined) : Promise.resolve()).then(() => this.executeOnce(key, fingerprint, operation));
+        this.pending.set(key, result);
+        void result
+            .finally(() => {
+            if (this.pending.get(key) === result)
+                this.pending.delete(key);
+        })
+            .catch(() => undefined);
+        return result;
+    }
+    async executeOnce(key, fingerprint, operation) {
+        const file = path.join(this.directory, `${key}.json`);
+        const existing = await readReceipt(file);
+        if (existing) {
+            if (existing.fingerprint !== fingerprint)
+                throw new Error(`${operation.resource.kind}_request_key_conflict`);
+            if (existing.state === "completed")
+                return existing.resource.id;
+            if (!(await operation.recover(existing.resource.id))) {
+                throw new Error(`${operation.resource.kind}_request_outcome_unknown`);
+            }
+            await writeReceipt(file, { ...existing, state: "completed" });
+            return existing.resource.id;
+        }
+        await operation.prepare?.();
+        const receipt = { fingerprint, resource: operation.resource, state: "pending" };
+        await writeReceipt(file, receipt);
+        try {
+            await operation.run(receipt.resource.id);
+        }
+        catch (error) {
+            // Once creation cleanup finished, absence of its persisted resource
+            // confirms that retrying cannot duplicate it.
+            if (await operation.retrySafe?.(receipt.resource.id))
+                await rm(file, { force: true });
+            throw error;
+        }
+        await writeReceipt(file, { ...receipt, state: "completed" });
+        return receipt.resource.id;
+    }
+}
+async function readReceipt(file) {
+    try {
+        const stored = ReceiptSchema.parse(JSON.parse(await readFile(file, "utf8")));
+        return {
+            fingerprint: stored.fingerprint,
+            state: stored.state,
+            resource: "agentId" in stored
+                ? { kind: "agent", id: stored.agentId }
+                : { kind: "workspace", id: stored.workspaceId },
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeReceipt(file, receipt) {
+    await writeJsonFileAtomic(file, {
+        fingerprint: receipt.fingerprint,
+        state: receipt.state,
+        ...(receipt.resource.kind === "agent"
+            ? { agentId: receipt.resource.id }
+            : { workspaceId: receipt.resource.id }),
+    });
+}
+function digest(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(value, (_key, candidate) => {
+        if (candidate !== null && typeof candidate === "object" && !Array.isArray(candidate)) {
+            return Object.fromEntries(Object.entries(candidate).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return candidate;
+    }))
+        .digest("hex");
+}
+//# sourceMappingURL=index.js.map

package/dist/server/server/resolve-workspace-id-for-path.d.ts

@@ -0,0 +1,3 @@
+import type { PersistedWorkspaceRecord } from "./workspace-registry.js";
+export declare function resolveWorkspaceIdForPath(cwd: string, workspaces: Iterable<PersistedWorkspaceRecord>): string | null;
+//# sourceMappingURL=resolve-workspace-id-for-path.d.ts.map

package/dist/server/server/resolve-workspace-id-for-path.js

@@ -0,0 +1,41 @@
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+// external path→workspace adapter, not ownership.
+//
+// Resolves a raw filesystem path to a single workspace id ONLY at the boundary
+// where a client hands the daemon a bare worktree path with no id:
+// archive-by-path (old client / CLI), auto-archive-after-merge, and the MCP
+// `archive_worktree` tool. It is NEVER used to attribute agent status or place
+// agents under a workspace — those are keyed by `workspaceId`, and git facts
+// derive from a workspace's OWN cwd (id → cwd).
+//
+// Resolution: an exact directory match wins; otherwise the deepest enclosing
+// workspace directory, never the home directory; null when nothing encloses it.
+export function resolveWorkspaceIdForPath(cwd, workspaces) {
+    const workspaceRecords = Array.from(workspaces);
+    const resolvedCwd = resolve(cwd);
+    const exactMatch = workspaceRecords.find((workspace) => resolve(workspace.cwd) === resolvedCwd);
+    if (exactMatch) {
+        return exactMatch.workspaceId;
+    }
+    const userHome = resolve(homedir());
+    let bestMatchLength = 0;
+    let bestMatch = null;
+    for (const workspace of workspaceRecords) {
+        if (workspace.archivedAt)
+            continue;
+        const workspaceCwd = resolve(workspace.cwd);
+        if (workspaceCwd === userHome)
+            continue;
+        const prefix = workspaceCwd.endsWith(sep) ? workspaceCwd : `${workspaceCwd}${sep}`;
+        if (!resolvedCwd.startsWith(prefix)) {
+            continue;
+        }
+        if (workspaceCwd.length > bestMatchLength) {
+            bestMatchLength = workspaceCwd.length;
+            bestMatch = workspace;
+        }
+    }
+    return bestMatch?.workspaceId ?? null;
+}
+//# sourceMappingURL=resolve-workspace-id-for-path.js.map