@camerontaylor/paseo-client 0.12.0-fork.1 → 0.13.0-fork.1

package/dist/hosts/index.d.ts

@@ -0,0 +1,22 @@
+import { DaemonClient } from "../daemon-client.js";
+import type { DaemonTransportFactory } from "../daemon-client-transport-types.js";
+import type { OwnedSubscription } from "../connection/index.js";
+import type { PaseoApi, createPaseoApi } from "../index.js";
+import type { HostAdd, HostUpdate, HostSummary, HostDirectory } from "@camerontaylor/paseo-protocol/hosts";
+export interface PaseoHostActions {
+    list(): Promise<HostDirectory>;
+    observe(): OwnedSubscription<HostDirectory>;
+    add(input: HostAdd): Promise<HostSummary>;
+    update(registrationId: string, patch: HostUpdate): Promise<HostSummary>;
+    remove(registrationId: string): Promise<void>;
+    client(serverId: string): Promise<PaseoApi>;
+}
+export declare function createHostChannelTransport(origin: DaemonClient, serverId: string, scopeId: string, initialRouteId: string | null, link?: boolean): DaemonTransportFactory;
+export declare function createHostActions(origin: DaemonClient, owner: {
+    own<T extends {
+        release(): Promise<void>;
+    }>(create: () => T): T;
+    signal: AbortSignal;
+    api: typeof createPaseoApi;
+}): PaseoHostActions;
+//# sourceMappingURL=index.d.ts.map

package/dist/hosts/index.js

@@ -0,0 +1,188 @@
+import { safeRandomId } from "../daemon-client-transport-utils.js";
+import { DaemonClient } from "../daemon-client.js";
+export function createHostChannelTransport(origin, serverId, scopeId, initialRouteId, link = false) {
+    let first = initialRouteId;
+    return () => {
+        const opens = new Set();
+        const closes = new Set();
+        const messages = new Set();
+        const errors = new Set();
+        let routeId = null;
+        let closed = false;
+        const cleanups = [];
+        const close = (error) => {
+            if (closed)
+                return;
+            closed = true;
+            if (error instanceof Error)
+                Object.assign(error, { serverId });
+            for (const cleanup of cleanups)
+                cleanup();
+            try {
+                if (routeId)
+                    origin.closeHostRoute(routeId);
+                else
+                    origin.cancelHostRoute(scopeId);
+            }
+            catch {
+                /* Transport already closed. */
+            }
+            if (error)
+                for (const handler of errors)
+                    handler(error);
+            for (const handler of closes)
+                handler(error);
+        };
+        cleanups.push(origin.subscribeRawMessages((message) => {
+            if (message.type === "hosts.route.frame" && message.payload.subscriptionId === routeId) {
+                for (const handler of messages)
+                    handler(message.payload.data, false);
+            }
+            if (message.type === "hosts.route.closed" && message.payload.subscriptionId === routeId)
+                close(Object.assign(new Error(message.payload.message), {
+                    code: message.payload.code,
+                    serverId,
+                }));
+        }));
+        cleanups.push(origin.subscribeHostFrames((frame) => {
+            if (frame.routeId === routeId)
+                for (const handler of messages)
+                    handler(frame.payload, true);
+        }));
+        cleanups.push(origin.subscribeConnectionStatus((connectionState) => {
+            if (connectionState.status !== "connected")
+                close();
+        }));
+        let opening;
+        if (first)
+            opening = Promise.resolve(first);
+        else
+            opening = link ? origin.openHostLink(scopeId) : origin.openHostRoute(serverId, scopeId);
+        first = null;
+        void opening
+            .then((id) => {
+            if (closed) {
+                origin.closeHostRoute(id);
+                return;
+            }
+            routeId = id;
+            for (const handler of opens)
+                handler();
+            return undefined;
+        })
+            .catch(close);
+        return {
+            send(data) {
+                if (closed || !routeId)
+                    throw Object.assign(new Error(`Host ${serverId} is offline`), {
+                        code: "host_offline",
+                        serverId,
+                    });
+                origin.sendHostFrame(routeId, typeof data === "string" || data instanceof Uint8Array ? data : new Uint8Array(data));
+            },
+            close: () => close(),
+            onOpen(handler) {
+                opens.add(handler);
+                return () => opens.delete(handler);
+            },
+            onClose(handler) {
+                closes.add(handler);
+                return () => closes.delete(handler);
+            },
+            onError(handler) {
+                errors.add(handler);
+                return () => errors.delete(handler);
+            },
+            onMessage(handler) {
+                messages.add(handler);
+                return () => messages.delete(handler);
+            },
+        };
+    };
+}
+export function createHostActions(origin, owner) {
+    const assertActive = () => {
+        if (owner.signal.aborted)
+            throw new Error("Paseo API is disposed");
+    };
+    return {
+        list: () => {
+            assertActive();
+            return origin.listHosts();
+        },
+        observe: () => owner.own(() => origin.observeHosts()),
+        add: (input) => {
+            assertActive();
+            return origin.addHost(input);
+        },
+        update: (id, patch) => {
+            assertActive();
+            return origin.updateHost(id, patch);
+        },
+        remove: (id) => {
+            assertActive();
+            return origin.removeHost(id);
+        },
+        async client(serverId) {
+            assertActive();
+            origin.requireConnectedHosts();
+            if (origin.getLastServerInfoMessage()?.serverId === serverId) {
+                const api = owner.api(origin, { signal: owner.signal });
+                const scope = owner.own(() => ({ release: () => api.dispose() }));
+                return { ...api, dispose: () => scope.release() };
+            }
+            const scopeId = safeRandomId();
+            const cancel = () => origin.cancelHostRoute(scopeId);
+            owner.signal.addEventListener("abort", cancel, { once: true });
+            let routeId;
+            try {
+                routeId = await origin.openHostRoute(serverId, scopeId);
+            }
+            catch (error) {
+                throw Object.assign(error instanceof Error ? error : new Error(String(error)), {
+                    serverId,
+                });
+            }
+            finally {
+                owner.signal.removeEventListener("abort", cancel);
+            }
+            if (owner.signal.aborted) {
+                origin.closeHostRoute(routeId);
+                assertActive();
+            }
+            const client = new DaemonClient({
+                url: "ws://routed-host/ws",
+                clientId: scopeId,
+                transportFactory: createHostChannelTransport(origin, serverId, scopeId, routeId),
+                // Initial acquisition has a deadline; established scopes restore demand on loss.
+                reconnect: { enabled: false },
+            });
+            const api = owner.api(client, { signal: owner.signal });
+            const scope = owner.own(() => ({
+                release: async () => {
+                    try {
+                        await api.dispose();
+                    }
+                    finally {
+                        await client.close();
+                    }
+                },
+            }));
+            try {
+                await client.connect();
+                client.setReconnectEnabled(true);
+                assertActive();
+                return { ...api, dispose: () => scope.release() };
+            }
+            catch (error) {
+                const failure = Object.assign(error instanceof Error ? error : new Error("Host handshake failed"), {
+                    code: error instanceof Error && "code" in error ? error.code : "host_offline",
+                    serverId,
+                });
+                await scope.release();
+                throw failure;
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+import type { AgentAddress } from "@camerontaylor/paseo-protocol/addresses";
+export type { AgentAddress } from "@camerontaylor/paseo-protocol/addresses";
+import { type PaseoHostActions } from "./hosts/index.js";
+export type { PaseoHostActions } from "./hosts/index.js";
+export type { HostAdd, HostUpdate, HostSummary, HostDirectory } from "@camerontaylor/paseo-protocol/hosts";
 import type { OwnedSubscription } from "./connection/index.js";
 export type { OwnedSubscription, SubscriptionObserver } from "./connection/index.js";
 import type { DaemonClientConfig } from "./daemon-client.js";
@@ -167,7 +172,7 @@ export interface PaseoAgentCreateOptions {
     onEvent?: (snapshot: CreationSnapshot) => void;
     config: PaseoAgentConfig;
     cwd: string;
-    parent?: string | PaseoAgentHandle;
+    parent?: string | AgentAddress | PaseoAgentHandle;
     title?: PaseoAgentSessionConfig["title"];
     env?: CreateAgentRequestMessage["env"];
     prompt?: string;
@@ -259,6 +264,7 @@ export interface PaseoAgentTimelineHandle {
 }
 export interface PaseoAgentHandle {
     readonly id: string;
+    readonly address: AgentAddress;
     /**
      * `workspaceId` through `archivedAt` mirror the last snapshot this handle
      * observed. A handle from `ref()` reads `null` for all of them until
@@ -390,6 +396,7 @@ export interface PaseoConfigActions {
     }>;
 }
 export interface PaseoApi {
+    readonly hosts: PaseoHostActions;
     dispose(): Promise<void>;
     observeEvents: DaemonClient["observeEvents"];
     readonly terminals: PaseoTerminalActions;

package/dist/index.js

@@ -1,3 +1,5 @@
+import { parentAddressLabels } from "@camerontaylor/paseo-protocol/agent-labels";
+import { createHostActions } from "./hosts/index.js";
 import { DaemonClient } from "./daemon-client.js";
 import { createTerminalActions, } from "./terminals/index.js";
 /**
@@ -27,10 +29,11 @@ export function createPaseoClient(config) {
         getConnectionState: () => daemonClient.getConnectionState(),
     };
 }
-function toDaemonAgentCreateOptions(options, placement) {
+function toDaemonAgentCreateOptions(options, placement, serverId) {
     const { config: agentConfig, cwd, parent, title, prompt, ...requestOptions } = options;
     const { provider: providerModel, options: providerOptions, ...runtimeConfig } = agentConfig;
     const { provider, model } = parseProviderModel(providerModel);
+    const relationship = parent ? encodeParent(parent, serverId) : {};
     return {
         ...requestOptions,
         config: {
@@ -42,7 +45,12 @@ function toDaemonAgentCreateOptions(options, placement) {
             ...(providerOptions !== undefined ? { providerOptions } : {}),
         },
         ...(placement ? { workspaceId: placement.workspaceId } : {}),
-        ...(parent ? { callerAgentId: resolveAgentId(parent) } : {}),
+        ...(parent
+            ? {
+                ...relationship,
+                labels: { ...requestOptions.labels, ...relationship.labels },
+            }
+            : {}),
         ...(prompt !== undefined ? { initialPrompt: prompt } : {}),
     };
 }
@@ -81,7 +89,7 @@ export function createPaseoApi(daemonClient, scopeOptions) {
     };
     const createAgentHandle = createAgentHandleFactory(daemonClient, listenAgents, (agentId, handler) => own(() => daemonClient.subscribeAgentTimeline(agentId, handler)));
     const createAgent = async (options, placement) => {
-        const agent = await daemonClient.createAgent(toDaemonAgentCreateOptions(options, placement));
+        const agent = await daemonClient.createAgent(toDaemonAgentCreateOptions(options, placement, daemonClient.getLastServerInfoMessage()?.serverId));
         return createAgentHandle(agent);
     };
     const terminals = createTerminalActions(daemonClient, async (workspaceId) => {
@@ -160,6 +168,7 @@ export function createPaseoApi(daemonClient, scopeOptions) {
     }
     return {
         dispose,
+        hosts: createHostActions(daemonClient, { own, signal: lifetime.signal, api: createPaseoApi }),
         observeEvents,
         terminals,
         projects: {
@@ -176,7 +185,14 @@ export function createPaseoApi(daemonClient, scopeOptions) {
             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);
+                const result = await daemonClient.createWorkspace({
+                    ...options,
+                    ...(agent
+                        ? {
+                            agent: toDaemonAgentCreateOptions(agent, undefined, daemonClient.getLastServerInfoMessage()?.serverId),
+                        }
+                        : {}),
+                }, requestId);
                 if (result.error || !result.workspace) {
                     throw new Error(result.error ?? "The daemon did not create a workspace");
                 }
@@ -296,8 +312,15 @@ function createAgentHandleFactory(daemonClient, listen, subscribeTimeline) {
     return (agent) => {
         const id = typeof agent === "string" ? agent : agent.id;
         let current = typeof agent === "string" ? null : agent;
+        let serverId = daemonClient.getLastServerInfoMessage()?.serverId;
         const handle = {
             id,
+            get address() {
+                serverId ?? (serverId = daemonClient.getLastServerInfoMessage()?.serverId);
+                if (!serverId)
+                    throw new Error("Connect to a host before obtaining an agent address");
+                return { serverId, agentId: id };
+            },
             timeline: {
                 append: (item) => daemonClient.appendAgentTimelineItem(id, item),
                 refetch: async (options) => {
@@ -429,8 +452,15 @@ async function openWorkspace(daemonClient, createWorkspaceHandle, input, request
 function resolveWorkspaceId(workspace) {
     return typeof workspace === "string" ? workspace : workspace.id;
 }
-function resolveAgentId(agent) {
-    return typeof agent === "string" ? agent : agent.id;
+function encodeParent(parent, serverId) {
+    if (typeof parent === "string")
+        return { callerAgentId: parent };
+    const address = "address" in parent ? parent.address : parent;
+    if (!serverId)
+        throw new Error("Connect to a host before creating a child");
+    return address.serverId === serverId
+        ? { callerAgentId: address.agentId, labels: parentAddressLabels(address) }
+        : { labels: parentAddressLabels(address) };
 }
 function parseProviderModel(selection) {
     const separator = selection.indexOf("/");
@@ -443,6 +473,7 @@ function parseProviderModel(selection) {
     };
 }
 function listProviderUsage(daemonClient, options) {
+    daemonClient.ensureConnected();
     // 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."));

package/dist/node/buffering.d.ts

@@ -0,0 +1,10 @@
+/** Counts bytes until the socket's send callback, shared by all links owned by a daemon. */
+export declare class HostTransportBudget {
+    readonly limit: number;
+    private used;
+    constructor(limit?: number);
+    get bufferedBytes(): number;
+    assertCapacity(bytes: number): void;
+    reserve(bytes: number): () => void;
+}
+//# sourceMappingURL=buffering.d.ts.map

package/dist/node/buffering.js

@@ -0,0 +1,28 @@
+/** Counts bytes until the socket's send callback, shared by all links owned by a daemon. */
+export class HostTransportBudget {
+    constructor(limit = 256 * 1024 * 1024) {
+        this.limit = limit;
+        this.used = 0;
+    }
+    get bufferedBytes() {
+        return this.used;
+    }
+    assertCapacity(bytes) {
+        if (bytes > this.limit - this.used)
+            throw Object.assign(new Error("Connected host buffer limit reached"), {
+                code: "resource_limit",
+            });
+    }
+    reserve(bytes) {
+        this.assertCapacity(bytes);
+        this.used += bytes;
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                this.used -= bytes;
+            }
+        };
+    }
+}
+//# sourceMappingURL=buffering.js.map

package/dist/node/index.d.ts

@@ -0,0 +1,13 @@
+export { createHostChannelTransport } from "../hosts/index.js";
+import { HostTransportBudget } from "./buffering.js";
+export { HostTransportBudget } from "./buffering.js";
+import { parseHostTarget } from "@camerontaylor/paseo-protocol/host-target";
+import type { DaemonTransportFactory } from "../daemon-client-transport-types.js";
+import { DaemonClient, type DaemonClientConfig } from "../daemon-client.js";
+export { parseHostTarget };
+export type { SshTunnel } from "./ssh-tunnel.js";
+export { createSshTunnel, resolveSshFailureDetail } from "./ssh-tunnel.js";
+/** A factory owns one attempt, including a fresh SSH process and its teardown. */
+export declare function createHostTransportFactory(connection: string, budget?: HostTransportBudget): DaemonTransportFactory;
+export declare function createHostClient(connection: string, config: Omit<DaemonClientConfig, "url" | "transportFactory">, budget?: HostTransportBudget): DaemonClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.js

@@ -0,0 +1,188 @@
+export { createHostChannelTransport } from "../hosts/index.js";
+import { HostTransportBudget } from "./buffering.js";
+export { HostTransportBudget } from "./buffering.js";
+import { homedir } from "node:os";
+import { WebSocket } from "ws";
+import { parseHostTarget } from "@camerontaylor/paseo-protocol/host-target";
+import { createSshTunnel } from "./ssh-tunnel.js";
+import { createWebSocketTransportFactory } from "../daemon-client-websocket-transport.js";
+import { createRelayE2eeTransportFactory } from "../daemon-client-relay-e2ee-transport.js";
+import { DaemonClient } from "../daemon-client.js";
+export { parseHostTarget };
+export { createSshTunnel, resolveSshFailureDetail } from "./ssh-tunnel.js";
+/** A factory owns one attempt, including a fresh SSH process and its teardown. */
+export function createHostTransportFactory(connection, budget = new HostTransportBudget()) {
+    const target = parseHostTarget(connection);
+    // Rises to "protected" once the daemon negotiates it, so a later attempt
+    // cannot be downgraded to legacy endpoint security.
+    let securityFloor = target.kind === "socket" ? target.offer?.minimumSecurityMode : undefined;
+    return (attemptOptions) => {
+        const opens = new Set();
+        const closes = new Set();
+        const errors = new Set();
+        const messages = new Set();
+        let closed = false;
+        let closeEvent;
+        let transport;
+        let teardown = () => { };
+        let disposeSocket = () => { };
+        let assertOutboundCapacity = (bytes) => budget.assertCapacity(bytes);
+        let sshTunnel = null;
+        const close = (code, reason) => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                transport?.close(code, reason);
+            }
+            finally {
+                try {
+                    disposeSocket();
+                    teardown();
+                }
+                finally {
+                    for (const handler of closes)
+                        handler(closeEvent);
+                }
+            }
+        };
+        void (async () => {
+            let socketTarget;
+            if (target.kind === "ssh") {
+                const tunnel = await createSshTunnel(target.ssh);
+                sshTunnel = tunnel;
+                teardown = () => tunnel.close();
+                socketTarget = parseHostTarget(tunnel.endpoint);
+            }
+            else
+                socketTarget = target;
+            if (closed) {
+                teardown();
+                return;
+            }
+            const socketPath = socketTarget.socketPath?.replace(/^~(?=\/)/, homedir());
+            let factory = createWebSocketTransportFactory((url, options) => {
+                const socket = new WebSocket(socketPath && url.startsWith("ws+unix:") ? `ws+unix://${socketPath}:/ws` : url, options?.protocols, {
+                    headers: options?.headers,
+                    ...(socketPath ? { socketPath } : {}),
+                    maxPayload: 100 * 1024 * 1024,
+                });
+                disposeSocket = () => socket.terminate();
+                assertOutboundCapacity = (bytes) => {
+                    if (socket.bufferedAmount + bytes > 128 * 1024 * 1024) {
+                        throw Object.assign(new Error("Host socket buffer limit reached"), {
+                            code: "resource_limit",
+                        });
+                    }
+                    budget.assertCapacity(bytes);
+                };
+                const pending = new Set();
+                const send = socket.send.bind(socket);
+                socket.send = (data, ...args) => {
+                    const bytes = typeof data === "string"
+                        ? Buffer.byteLength(data)
+                        : Buffer.byteLength(data);
+                    assertOutboundCapacity(bytes);
+                    const release = budget.reserve(bytes);
+                    pending.add(release);
+                    const callback = args.find((value) => typeof value === "function");
+                    const sendOptions = args.find((value) => value !== null && typeof value === "object");
+                    try {
+                        send(data, sendOptions ?? {}, (error) => {
+                            release();
+                            pending.delete(release);
+                            callback?.(error);
+                        });
+                    }
+                    catch (error) {
+                        release();
+                        pending.delete(release);
+                        throw error;
+                    }
+                };
+                socket.once("close", () => {
+                    for (const release of pending)
+                        release();
+                    pending.clear();
+                });
+                return socket;
+            });
+            if (socketTarget.offer)
+                factory = createRelayE2eeTransportFactory({
+                    baseFactory: factory,
+                    daemonPublicKeyB64: socketTarget.offer.daemonPublicKeyB64,
+                    ...(securityFloor ? { minimumMode: securityFloor } : {}),
+                    onSecurityMode: (mode) => {
+                        if (mode === "protected")
+                            securityFloor = "protected";
+                    },
+                    logger: { warn() { } },
+                    assertOutboundCapacity: (bytes) => assertOutboundCapacity(bytes),
+                });
+            transport = factory({ ...attemptOptions, url: socketTarget.url });
+            transport.onOpen(() => {
+                if (!closed)
+                    for (const handler of opens)
+                        handler();
+            });
+            transport.onClose((event) => {
+                closeEvent = event;
+                close();
+            });
+            transport.onError((error) => {
+                if (closed)
+                    return;
+                const detail = sshTunnel?.failureDetail() ?? "";
+                const failure = /permission denied|authentication failed|host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED/i.test(detail)
+                    ? Object.assign(new Error("SSH authentication or host verification failed. Check the SSH configuration on this daemon."), { code: "authentication_failed" })
+                    : error;
+                for (const handler of errors)
+                    handler(failure);
+                close();
+            });
+            transport.onMessage((data, binary) => {
+                if (!closed)
+                    for (const handler of messages)
+                        handler(data, binary);
+            });
+        })().catch(() => {
+            for (const handler of errors)
+                handler(new Error("Host transport failed"));
+            close();
+        });
+        return {
+            send(data) {
+                if (closed || !transport)
+                    throw new Error("Host transport is unavailable");
+                transport.send(data);
+            },
+            close,
+            onOpen(handler) {
+                opens.add(handler);
+                return () => opens.delete(handler);
+            },
+            onClose(handler) {
+                closes.add(handler);
+                return () => closes.delete(handler);
+            },
+            onError(handler) {
+                errors.add(handler);
+                return () => errors.delete(handler);
+            },
+            onMessage(handler) {
+                messages.add(handler);
+                return () => messages.delete(handler);
+            },
+        };
+    };
+}
+export function createHostClient(connection, config, budget) {
+    const target = parseHostTarget(connection);
+    return new DaemonClient({
+        ...config,
+        url: "ws://host-connector/ws",
+        ...(target.password ? { password: target.password } : {}),
+        transportFactory: createHostTransportFactory(connection, budget),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/node/ssh-tunnel.d.ts

@@ -0,0 +1,9 @@
+import { type SshTransportTarget } from "@camerontaylor/paseo-protocol/ssh-transport";
+export interface SshTunnel {
+    endpoint: string;
+    close(): void;
+    failureDetail(): string | null;
+}
+export declare function resolveSshFailureDetail(failure: string | null, stderr: string): string | null;
+export declare function createSshTunnel(target: SshTransportTarget): Promise<SshTunnel>;
+//# sourceMappingURL=ssh-tunnel.d.ts.map