@camerontaylor/paseo-client 0.8.0-fork.1

package/dist/index.js

@@ -0,0 +1,407 @@
+import { DaemonClient } from "./daemon-client.js";
+import { createTerminalActions, } from "./terminals/index.js";
+/**
+ * Coding turns routinely run for minutes, so the handle waits far longer than
+ * the transport's own conservative default.
+ */
+const DEFAULT_WAIT_FOR_FINISH_MS = 10 * 60000;
+export function createPaseoClient(config) {
+    const daemonClient = new DaemonClient({
+        ...config,
+        clientId: config.clientId ?? createGeneratedClientId(),
+        clientType: "cli",
+    });
+    return {
+        ...createPaseoApi(daemonClient),
+        connect: () => daemonClient.connect(),
+        close: () => daemonClient.close(),
+        ensureConnected: () => daemonClient.ensureConnected(),
+        getConnectionState: () => daemonClient.getConnectionState(),
+    };
+}
+function toDaemonAgentCreateOptions(options, placement) {
+    const { config: agentConfig, cwd, parent, title, prompt, ...requestOptions } = options;
+    const { provider: providerModel, options: providerOptions, ...runtimeConfig } = agentConfig;
+    const { provider, model } = parseProviderModel(providerModel);
+    return {
+        ...requestOptions,
+        config: {
+            ...runtimeConfig,
+            provider,
+            model,
+            cwd: placement?.cwd ?? cwd,
+            ...(title !== undefined ? { title } : {}),
+            ...(providerOptions !== undefined ? { providerOptions } : {}),
+        },
+        ...(placement ? { workspaceId: placement.workspaceId } : {}),
+        ...(parent ? { callerAgentId: resolveAgentId(parent) } : {}),
+        ...(prompt !== undefined ? { initialPrompt: prompt } : {}),
+    };
+}
+export function createPaseoApi(daemonClient) {
+    const createAgentHandle = createAgentHandleFactory(daemonClient);
+    const createAgent = async (options, placement) => {
+        const agent = await daemonClient.createAgent(toDaemonAgentCreateOptions(options, placement));
+        return createAgentHandle(agent);
+    };
+    const terminals = createTerminalActions(daemonClient, async (workspaceId) => {
+        const workspace = await createWorkspaceHandle(workspaceId).refresh();
+        if (!workspace?.workspaceDirectory) {
+            throw new Error(`Workspace ${workspaceId} is not active or has no available directory`);
+        }
+        return workspace.workspaceDirectory;
+    });
+    const createWorkspaceHandle = createWorkspaceHandleFactory(daemonClient, createAgent, terminals);
+    return {
+        terminals,
+        projects: {
+            list: (options) => daemonClient.listProjects(options),
+            subscribe: (handler) => daemonClient.on("project.update", (message) => {
+                handler(message.payload);
+            }),
+        },
+        workspaces: {
+            list: (options) => daemonClient.fetchWorkspaces(options),
+            ref: (workspace) => createWorkspaceHandle(workspace),
+            open: (input, requestId) => openWorkspace(daemonClient, createWorkspaceHandle, input, requestId),
+            create: async ({ requestId, agent, ...options }) => {
+                const result = await daemonClient.createWorkspace({ ...options, ...(agent ? { agent: toDaemonAgentCreateOptions(agent) } : {}) }, requestId);
+                if (result.error || !result.workspace) {
+                    throw new Error(result.error ?? "The daemon did not create a workspace");
+                }
+                return createWorkspaceHandle(result.workspace);
+            },
+            archive: (workspace, requestId) => daemonClient.archiveWorkspace(resolveWorkspaceId(workspace), requestId),
+            subscribe: (handler) => daemonClient.on("workspace_update", (message) => {
+                handler(message.payload);
+            }),
+        },
+        agents: {
+            list: (options) => daemonClient.fetchAgents(options),
+            ref: (agent) => createAgentHandle(agent),
+            create: (options) => createAgent(options),
+            subscribe: (handler) => daemonClient.on("agent_update", (message) => {
+                handler(message.payload);
+            }),
+        },
+        providers: {
+            listModels: (provider, options) => daemonClient.listProviderModels(provider, options),
+            listModes: (provider, options) => daemonClient.listProviderModes(provider, options),
+            listFeatures: ({ provider: providerModel, ...draftConfig }, options) => {
+                const { provider, model } = parseProviderModel(providerModel);
+                return daemonClient.listProviderFeatures({ ...draftConfig, provider, model }, options);
+            },
+            listAvailable: (options) => daemonClient.listAvailableProviders(options),
+            snapshot: (options) => daemonClient.getProvidersSnapshot(options),
+            waitForReady: (options) => waitForProvidersReady(daemonClient, options),
+            refresh: (options) => daemonClient.refreshProvidersSnapshot(options),
+            diagnostic: (provider, options) => daemonClient.getProviderDiagnostic(provider, options),
+            listUsage: (options) => listProviderUsage(daemonClient, options),
+            subscribe: (handler) => daemonClient.on("providers_snapshot_update", (message) => {
+                handler(message.payload);
+            }),
+        },
+        config: {
+            get: (requestId) => daemonClient.getDaemonConfig(requestId),
+            patch: (patch, requestId) => daemonClient.patchDaemonConfig(patch, requestId),
+        },
+    };
+}
+function createWorkspaceHandleFactory(daemonClient, createAgent, terminals) {
+    return (workspace) => {
+        const id = typeof workspace === "string" ? workspace : workspace.id;
+        let current = typeof workspace === "string" ? null : workspace;
+        const refresh = async (options) => {
+            let cursor;
+            let requestId = options?.requestId;
+            do {
+                const result = await daemonClient.fetchWorkspaces({
+                    requestId,
+                    page: { limit: 200, ...(cursor ? { cursor } : {}) },
+                });
+                const match = result.entries.find((entry) => entry.id === id);
+                if (match) {
+                    current = match;
+                    return current;
+                }
+                cursor = result.pageInfo.nextCursor ?? undefined;
+                requestId = undefined;
+            } while (cursor);
+            current = null;
+            return current;
+        };
+        return {
+            id,
+            get projectId() {
+                return current?.projectId ?? null;
+            },
+            get directory() {
+                return current?.workspaceDirectory ?? null;
+            },
+            get name() {
+                return current?.name ?? null;
+            },
+            get status() {
+                return current?.status ?? null;
+            },
+            agents: {
+                create: async (options) => {
+                    const snapshot = current ?? (await refresh());
+                    if (!snapshot?.workspaceDirectory) {
+                        throw new Error(`Workspace ${id} has no available directory`);
+                    }
+                    return createAgent({ ...options, cwd: snapshot.workspaceDirectory }, { workspaceId: id, cwd: snapshot.workspaceDirectory });
+                },
+            },
+            terminals: {
+                create: (options) => terminals.create({ ...options, workspaceId: id }),
+                list: (options) => terminals.list({ ...options, workspaceId: id }),
+            },
+            current: () => current,
+            refresh,
+            setTitle: (title, requestId) => daemonClient.setWorkspaceTitle(id, title, requestId),
+            archive: async (requestId) => {
+                const result = await daemonClient.archiveWorkspace(id, requestId);
+                if (current) {
+                    current = { ...current, archivingAt: result.archivedAt };
+                }
+                return result;
+            },
+            subscribe: (handler) => daemonClient.on("workspace_update", (message) => {
+                const update = message.payload;
+                if (update.kind === "upsert" && update.workspace.id === id) {
+                    current = update.workspace;
+                    handler(update);
+                }
+                if (update.kind === "remove" && update.id === id) {
+                    current = null;
+                    handler(update);
+                }
+            }),
+        };
+    };
+}
+function createAgentHandleFactory(daemonClient) {
+    return (agent) => {
+        const id = typeof agent === "string" ? agent : agent.id;
+        let current = typeof agent === "string" ? null : agent;
+        const handle = {
+            id,
+            timeline: {
+                append: (item) => daemonClient.appendAgentTimelineItem(id, item),
+                refetch: async (options) => {
+                    const result = await daemonClient.fetchAgentTimeline(id, options);
+                    if (result.agent) {
+                        current = result.agent;
+                    }
+                    return result;
+                },
+                subscribe: (handler) => daemonClient.subscribeAgentTimeline(id, (message) => {
+                    handler(message.type === "agent_stream"
+                        ? message.payload
+                        : {
+                            agentId: message.payload.agentId,
+                            event: { type: "replacement", epoch: message.payload.epoch },
+                        });
+                }),
+            },
+            get workspaceId() {
+                return current?.workspaceId ?? null;
+            },
+            get cwd() {
+                return current?.cwd ?? null;
+            },
+            get status() {
+                return current?.status ?? null;
+            },
+            get capabilities() {
+                return current?.capabilities ?? null;
+            },
+            get availableModes() {
+                return current?.availableModes ?? null;
+            },
+            get pendingPermissions() {
+                return current?.pendingPermissions ?? null;
+            },
+            get activeTurn() {
+                return current?.activeTurn ?? null;
+            },
+            get lastUsage() {
+                return current?.lastUsage ?? null;
+            },
+            get lastError() {
+                return current?.lastError ?? null;
+            },
+            get features() {
+                return current?.features ?? null;
+            },
+            get runtimeInfo() {
+                return current?.runtimeInfo ?? null;
+            },
+            get archivedAt() {
+                return current?.archivedAt ?? null;
+            },
+            current: () => current,
+            refresh: async (requestId) => {
+                const result = await daemonClient.fetchAgent({ agentId: id, requestId });
+                current = result?.agent ?? null;
+                return result;
+            },
+            send: async (text, options) => {
+                await daemonClient.sendAgentMessage(id, text, options);
+            },
+            respondToPermission: async ({ requestId, response }) => {
+                await daemonClient.respondToPermission(id, requestId, response);
+            },
+            run: async (text, options) => {
+                const { timeoutMs, ...sendOptions } = options ?? {};
+                await daemonClient.sendAgentMessage(id, text, sendOptions);
+                const result = await daemonClient.waitForFinish(id, timeoutMs ?? DEFAULT_WAIT_FOR_FINISH_MS);
+                if (result.final) {
+                    current = result.final;
+                }
+                return result;
+            },
+            waitForFinish: async (timeoutMs) => {
+                const result = await daemonClient.waitForFinish(id, timeoutMs ?? DEFAULT_WAIT_FOR_FINISH_MS);
+                if (result.final) {
+                    current = result.final;
+                }
+                return result;
+            },
+            commands: (options) => daemonClient.listCommands({ agentId: id, ...options }),
+            archive: async () => {
+                const result = await daemonClient.archiveAgent(id);
+                if (current) {
+                    current = { ...current, archivedAt: result.archivedAt };
+                }
+                return result;
+            },
+            detach: async () => {
+                await daemonClient.detachAgent(id);
+            },
+            subscribe: (handler) => daemonClient.on("agent_update", (message) => {
+                const update = message.payload;
+                if (update.kind === "upsert" && update.agent.id === id) {
+                    current = update.agent;
+                    handler(update);
+                }
+                if (update.kind === "remove" && update.agentId === id) {
+                    current = null;
+                    handler(update);
+                }
+            }),
+        };
+        return handle;
+    };
+}
+async function openWorkspace(daemonClient, createWorkspaceHandle, input, requestId) {
+    const options = typeof input === "string" ? { cwd: input, requestId } : input;
+    const result = await daemonClient.openProject(options.cwd, options.requestId);
+    if (result.error || !result.workspace) {
+        throw new Error(result.error ?? `The daemon did not open a workspace for ${options.cwd}`);
+    }
+    return createWorkspaceHandle(result.workspace);
+}
+function resolveWorkspaceId(workspace) {
+    return typeof workspace === "string" ? workspace : workspace.id;
+}
+function resolveAgentId(agent) {
+    return typeof agent === "string" ? agent : agent.id;
+}
+function parseProviderModel(selection) {
+    const separator = selection.indexOf("/");
+    if (separator <= 0 || separator === selection.length - 1) {
+        throw new Error('Expected config.provider in "provider/model" format');
+    }
+    return {
+        provider: selection.slice(0, separator),
+        model: selection.slice(separator + 1),
+    };
+}
+function listProviderUsage(daemonClient, options) {
+    // COMPAT(providerUsageList): added in v0.1.98, remove after 2027-02-28 once daemon floor >= v0.1.98.
+    if (daemonClient.getLastServerInfoMessage()?.features?.providerUsageList !== true) {
+        return Promise.reject(new Error("Update the host to list provider usage."));
+    }
+    return daemonClient.listProviderUsage(options);
+}
+function waitForProvidersReady(daemonClient, options = {}) {
+    // COMPAT(providersSnapshotCwd): added in v0.3.2, remove gate after 2027-02-10.
+    if (daemonClient.getLastServerInfoMessage()?.features?.providersSnapshotCwd !== true) {
+        return Promise.reject(new Error("Update the host to wait for provider discovery."));
+    }
+    const { timeoutMs = 60000, ...snapshotOptions } = options;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let requestId = null;
+        let snapshotCwd;
+        const pendingUpdates = new Map();
+        let latestEntries = [];
+        const cleanup = () => {
+            clearTimeout(timeout);
+            unsubscribe();
+        };
+        const finish = (snapshot) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(snapshot);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error instanceof Error ? error : new Error(String(error)));
+        };
+        const updateMatches = (update) => update.cwd === snapshotCwd;
+        const unsubscribe = daemonClient.on("providers_snapshot_update", (message) => {
+            const update = message.payload;
+            if (!requestId) {
+                pendingUpdates.set(update.cwd, update);
+                return;
+            }
+            if (!updateMatches(update))
+                return;
+            latestEntries = update.entries;
+            if (update.entries.some((entry) => entry.status === "loading"))
+                return;
+            finish({ ...update, requestId });
+        });
+        const timeout = setTimeout(() => {
+            const loading = latestEntries
+                .filter((entry) => entry.status === "loading")
+                .map((entry) => entry.provider)
+                .join(", ");
+            fail(new Error(loading
+                ? `Timed out waiting for providers: ${loading}`
+                : "Timed out waiting for provider discovery"));
+        }, timeoutMs);
+        void daemonClient
+            .getProvidersSnapshot(snapshotOptions)
+            .then((snapshot) => {
+            requestId = snapshot.requestId;
+            snapshotCwd = snapshot.cwd;
+            latestEntries = snapshot.entries;
+            if (!snapshot.entries.some((entry) => entry.status === "loading")) {
+                finish(snapshot);
+                return;
+            }
+            const pendingUpdate = pendingUpdates.get(snapshotCwd);
+            if (pendingUpdate && !pendingUpdate.entries.some((entry) => entry.status === "loading")) {
+                finish({ ...pendingUpdate, requestId });
+            }
+            return undefined;
+        })
+            .catch(fail);
+    });
+}
+function createGeneratedClientId() {
+    const randomId = typeof globalThis.crypto?.randomUUID === "function"
+        ? globalThis.crypto.randomUUID()
+        : Math.random().toString(36).slice(2);
+    return `paseo-sdk-${randomId}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/provider-snapshots/index.d.ts

@@ -0,0 +1,23 @@
+import type { GetProvidersSnapshotResponseMessage, SessionOutboundMessage } from "@camerontaylor/paseo-protocol/messages";
+type Update = Extract<SessionOutboundMessage, {
+    type: "providers_snapshot_update";
+}>;
+type Snapshot = GetProvidersSnapshotResponseMessage["payload"];
+/** Resolve announcements only while observed, coalescing changes during a fetch. */
+export declare class ProviderSnapshotUpdates {
+    private readonly host;
+    private pending;
+    private paused;
+    constructor(host: {
+        fetch(cwd: string | undefined): Promise<Snapshot>;
+        emit(update: Update): void;
+        failed(error: unknown): void;
+    });
+    clear(): void;
+    pause(): void;
+    resume(): void;
+    receive(update: Update): void;
+    private resolve;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/provider-snapshots/index.js

@@ -0,0 +1,60 @@
+/** Resolve announcements only while observed, coalescing changes during a fetch. */
+export class ProviderSnapshotUpdates {
+    constructor(host) {
+        this.host = host;
+        this.pending = new Map();
+        this.paused = false;
+    }
+    clear() {
+        this.pending.clear();
+    }
+    pause() {
+        this.paused = true;
+        // Invalidate old responses while retaining the announcements they would resolve.
+        for (const [cwd, pending] of this.pending) {
+            this.pending.set(cwd, { latest: pending.latest, running: false });
+        }
+    }
+    resume() {
+        this.paused = false;
+        for (const pending of this.pending.values())
+            this.receive(pending.latest);
+    }
+    receive(update) {
+        const cwd = update.payload.cwd;
+        const pending = this.pending.get(cwd) ?? { latest: update, running: false };
+        pending.latest = update;
+        this.pending.set(cwd, pending);
+        if (this.paused || pending.running)
+            return;
+        pending.running = true;
+        void this.resolve(cwd, pending);
+    }
+    async resolve(cwd, pending) {
+        try {
+            while (this.pending.get(cwd) === pending) {
+                const announced = pending.latest;
+                const snapshot = await this.host.fetch(cwd);
+                if (this.pending.get(cwd) !== pending)
+                    return;
+                // A change arriving while the body was in flight needs the current body.
+                // If that response already covers it, no second fetch is necessary.
+                if (pending.latest !== announced &&
+                    pending.latest.payload.snapshotHash !== snapshot.snapshotHash)
+                    continue;
+                this.pending.delete(cwd);
+                this.host.emit({ type: "providers_snapshot_update", payload: snapshot });
+                return;
+            }
+        }
+        catch (error) {
+            if (this.pending.get(cwd) === pending)
+                this.host.failed(error);
+        }
+        finally {
+            if (this.pending.get(cwd) === pending)
+                this.pending.delete(cwd);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/terminal-stream-router.d.ts

@@ -0,0 +1,28 @@
+import { type TerminalStreamFrame } from "@camerontaylor/paseo-protocol/binary-frames/index";
+import type { TerminalInput, TerminalState } from "@camerontaylor/paseo-protocol/messages";
+export type TerminalStreamEvent = {
+    terminalId: string;
+    type: "output";
+    data: Uint8Array;
+} | {
+    terminalId: string;
+    type: "snapshot";
+    state: TerminalState;
+} | {
+    terminalId: string;
+    type: "restore";
+    data: Uint8Array;
+};
+export declare class TerminalStreamRouter {
+    private readonly terminalSlots;
+    private readonly slotTerminals;
+    private readonly listeners;
+    onEvent(handler: (event: TerminalStreamEvent) => void): () => void;
+    setSlot(terminalId: string, slot: number): void;
+    removeTerminal(terminalId: string): void;
+    clearSlots(): void;
+    encodeInput(terminalId: string, message: TerminalInput["message"]): Uint8Array | null;
+    handleFrame(frame: TerminalStreamFrame): void;
+    private emit;
+}
+//# sourceMappingURL=terminal-stream-router.d.ts.map

package/dist/terminal-stream-router.js

@@ -0,0 +1,109 @@
+import { decodeTerminalSnapshotPayload, encodeTerminalResizePayload, encodeTerminalStreamFrame, TerminalStreamOpcode, } from "@camerontaylor/paseo-protocol/binary-frames/index";
+export class TerminalStreamRouter {
+    constructor() {
+        this.terminalSlots = new Map();
+        this.slotTerminals = new Map();
+        this.listeners = new Set();
+    }
+    onEvent(handler) {
+        this.listeners.add(handler);
+        return () => {
+            this.listeners.delete(handler);
+        };
+    }
+    setSlot(terminalId, slot) {
+        const existingTerminalId = this.slotTerminals.get(slot);
+        if (existingTerminalId && existingTerminalId !== terminalId) {
+            this.terminalSlots.delete(existingTerminalId);
+        }
+        const existingSlot = this.terminalSlots.get(terminalId);
+        if (typeof existingSlot === "number" && existingSlot !== slot) {
+            this.slotTerminals.delete(existingSlot);
+        }
+        this.terminalSlots.set(terminalId, slot);
+        this.slotTerminals.set(slot, terminalId);
+    }
+    removeTerminal(terminalId) {
+        const slot = this.terminalSlots.get(terminalId);
+        if (typeof slot !== "number") {
+            return;
+        }
+        this.terminalSlots.delete(terminalId);
+        if (this.slotTerminals.get(slot) === terminalId) {
+            this.slotTerminals.delete(slot);
+        }
+    }
+    clearSlots() {
+        this.terminalSlots.clear();
+        this.slotTerminals.clear();
+    }
+    encodeInput(terminalId, message) {
+        const slot = this.terminalSlots.get(terminalId);
+        if (typeof slot !== "number") {
+            return null;
+        }
+        if (message.type === "input") {
+            return encodeTerminalStreamFrame({
+                opcode: TerminalStreamOpcode.Input,
+                slot,
+                payload: message.data,
+            });
+        }
+        if (message.type === "resize") {
+            return encodeTerminalStreamFrame({
+                opcode: TerminalStreamOpcode.Resize,
+                slot,
+                payload: encodeTerminalResizePayload({
+                    rows: message.rows,
+                    cols: message.cols,
+                    ...(message.intent ? { intent: message.intent } : {}),
+                }),
+            });
+        }
+        return null;
+    }
+    handleFrame(frame) {
+        const terminalId = this.slotTerminals.get(frame.slot);
+        if (!terminalId) {
+            return;
+        }
+        if (frame.opcode === TerminalStreamOpcode.Output) {
+            this.emit({
+                terminalId,
+                type: "output",
+                data: frame.payload,
+            });
+            return;
+        }
+        if (frame.opcode === TerminalStreamOpcode.Restore) {
+            this.emit({
+                terminalId,
+                type: "restore",
+                data: frame.payload,
+            });
+            return;
+        }
+        if (frame.opcode === TerminalStreamOpcode.Snapshot) {
+            const state = decodeTerminalSnapshotPayload(frame.payload);
+            if (!state) {
+                return;
+            }
+            this.emit({
+                terminalId,
+                type: "snapshot",
+                state,
+            });
+        }
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+}
+//# sourceMappingURL=terminal-stream-router.js.map