@camerontaylor/paseo-client 0.8.0-fork.1

package/README.md

@@ -0,0 +1,44 @@
+# @getpaseo/client
+
+TypeScript SDK for building integrations on top of a Paseo daemon.
+
+```bash
+npm install @getpaseo/client
+```
+
+```ts
+import { createPaseoClient } from "@camerontaylor/paseo-client";
+
+const client = createPaseoClient({ url: "ws://127.0.0.1:6767/ws" });
+await client.connect();
+
+const agent = await client.agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  cwd: "/Users/me/dev/storefront",
+  prompt: "Review the current diff and name the riskiest change.",
+});
+
+const result = await agent.waitForFinish();
+console.log(result.lastMessage);
+
+await client.close();
+```
+
+The public API is the package root. Imports under `@camerontaylor/paseo-client/internal/*` are unsupported implementation details used by Paseo's own packages.
+
+Read the [SDK documentation](https://paseo.sh/docs/sdk) for agents, workspaces, terminals, provider discovery, events, recipes, and the API reference. Runnable TypeScript patterns also live in [`examples/`](./examples/README.md).
+
+## Runtime
+
+The client needs a WebSocket implementation. Modern browsers and Node.js 22 provide one globally.
+
+Use a WebSocket URL ending in `/ws`, such as `ws://127.0.0.1:6767/ws`. Pass `password` when the daemon requires authentication.
+
+The client advertises its supported protocol capabilities by default. Optional `capabilities`
+overrides extend or override that declaration; browser hosting must be supplied by the caller.
+Connecting alone does not subscribe to agent timelines or catalog events. See the
+[event guide](https://paseo.sh/docs/sdk/events) for subscription lifetimes and timeline replacements.
+
+## Stability
+
+The high-level API exported from `@camerontaylor/paseo-client` is the supported SDK surface. The SDK and daemon remain protocol-compatible across versions, but newly added capabilities can require a newer daemon.

package/dist/compat/normalize-provider-models.d.ts

@@ -0,0 +1,11 @@
+import type { GetProvidersSnapshotResponseMessage, ListProviderModelsResponseMessage, SessionOutboundMessage } from "@camerontaylor/paseo-protocol/messages";
+type ListProviderModelsPayload = ListProviderModelsResponseMessage["payload"];
+type GetProvidersSnapshotPayload = GetProvidersSnapshotResponseMessage["payload"];
+type ProvidersSnapshotUpdatePayload = Extract<SessionOutboundMessage, {
+    type: "providers_snapshot_update";
+}>["payload"];
+export declare function normalizeListProviderModelsPayload(payload: ListProviderModelsPayload): ListProviderModelsPayload;
+export declare function normalizeProvidersSnapshotPayload<T extends GetProvidersSnapshotPayload | ProvidersSnapshotUpdatePayload>(payload: T, expand?: boolean): T;
+export declare function normalizeProviderSnapshotUpdateMessage(msg: SessionOutboundMessage, expand?: boolean): SessionOutboundMessage;
+export {};
+//# sourceMappingURL=normalize-provider-models.d.ts.map

package/dist/compat/normalize-provider-models.js

@@ -0,0 +1,51 @@
+import { normalizeAgentModelDefinition } from "@camerontaylor/paseo-protocol/agent-types";
+import { expandProviderSnapshot } from "@camerontaylor/paseo-protocol/provider-snapshot-codec";
+// COMPAT(model-normalize): daemon normalizes at source (provider-registry) — shim covers older daemons; drop when floor >= v0.1.104
+function normalizeAgentModels(models) {
+    if (!models) {
+        return models;
+    }
+    let changed = false;
+    const normalized = models.map((model) => {
+        const next = normalizeAgentModelDefinition(model);
+        changed || (changed = next !== model);
+        return next;
+    });
+    return changed ? normalized : models;
+}
+function normalizeProviderSnapshotEntry(entry) {
+    const models = normalizeAgentModels(entry.models);
+    return models === entry.models ? entry : { ...entry, models };
+}
+function normalizeProviderSnapshotEntries(entries) {
+    let changed = false;
+    const normalized = entries.map((entry) => {
+        const next = normalizeProviderSnapshotEntry(entry);
+        changed || (changed = next !== entry);
+        return next;
+    });
+    return changed ? normalized : entries;
+}
+export function normalizeListProviderModelsPayload(payload) {
+    const models = normalizeAgentModels(payload.models);
+    return models === payload.models ? payload : { ...payload, models };
+}
+export function normalizeProvidersSnapshotPayload(payload, expand = true) {
+    if (payload.compactSnapshot && !expand)
+        return payload;
+    const decoded = payload.compactSnapshot
+        ? expandProviderSnapshot(payload.compactSnapshot)
+        : normalizeProviderSnapshotEntries(payload.entries);
+    const freshness = payload.fetchedAt;
+    const entries = freshness && expand
+        ? decoded.map((entry) => freshness[entry.provider] ? { ...entry, fetchedAt: freshness[entry.provider] } : entry)
+        : decoded;
+    return entries === payload.entries ? payload : { ...payload, entries };
+}
+export function normalizeProviderSnapshotUpdateMessage(msg, expand = true) {
+    if (msg.type !== "providers_snapshot_update") {
+        return msg;
+    }
+    return { ...msg, payload: normalizeProvidersSnapshotPayload(msg.payload, expand) };
+}
+//# sourceMappingURL=normalize-provider-models.js.map

package/dist/connection/index.d.ts

@@ -0,0 +1,42 @@
+import type { SessionEventSubscription } from "@camerontaylor/paseo-protocol/messages";
+export declare const DEFAULT_CLIENT_CAPABILITIES: {
+    all_providers: true;
+    selective_agent_timeline: true;
+    reasoning_merge_enum: true;
+    custom_mode_icons: true;
+    terminal_reflowable_snapshot: true;
+    provider_subagents: true;
+    side_conversations: true;
+    project_updates: true;
+    compact_provider_snapshots: true;
+    provider_snapshot_references: true;
+    timeline_replacement_invalidation: true;
+    timeline_notifications: true;
+    plugin_timeline_items: true;
+    workspace_setup_blocked: true;
+    explicit_event_subscriptions: true;
+};
+/** Calling releases demand; ready acknowledges the initial daemon membership. */
+export type TimelineSubscription = (() => void) & {
+    readonly ready: Promise<void>;
+};
+/** Owns connection demand, independently of individual facades and React lifetimes. */
+export declare class ConnectionSubscriptions {
+    private readonly send;
+    private viewed;
+    private timelines;
+    private events;
+    constructor(send: {
+        timelines(agentIds: string[]): Promise<void> | null;
+        events(events: SessionEventSubscription[]): Promise<void>;
+        failed(error: unknown): void;
+    });
+    private agentIds;
+    setViewed(agentIds: string[]): Promise<void>;
+    observeTimeline(agentId: string): TimelineSubscription;
+    private syncTimelines;
+    setEvents(events: SessionEventSubscription[]): void;
+    restore(): void;
+    close(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/connection/index.js

@@ -0,0 +1,111 @@
+import { CLIENT_CAPS } from "@camerontaylor/paseo-protocol/client-capabilities";
+// Protocol support belongs to the installed client. Only browser hosting needs
+// a resource supplied by the caller. Keep this exhaustive as the protocol evolves.
+export const DEFAULT_CLIENT_CAPABILITIES = {
+    [CLIENT_CAPS.allProviders]: true,
+    [CLIENT_CAPS.selectiveAgentTimeline]: true,
+    [CLIENT_CAPS.reasoningMergeEnum]: true,
+    [CLIENT_CAPS.customModeIcons]: true,
+    [CLIENT_CAPS.terminalReflowableSnapshot]: true,
+    [CLIENT_CAPS.providerSubagents]: true,
+    // Fork-only capability, so this entry is fork-only too. The map is
+    // exhaustive over ClientCapability and the fork adds sideConversations to
+    // CLIENT_CAPS, so omitting it is a TS1360 the moment the fork merges.
+    // Nothing conflicts here: the file is upstream-new (#4470), the fork never
+    // edits it, and git never asks. Carried as a branch, not a resolution.
+    [CLIENT_CAPS.sideConversations]: true,
+    [CLIENT_CAPS.projectUpdates]: true,
+    [CLIENT_CAPS.compactProviderSnapshots]: true,
+    [CLIENT_CAPS.providerSnapshotReferences]: true,
+    [CLIENT_CAPS.timelineReplacementInvalidation]: true,
+    [CLIENT_CAPS.timelineNotifications]: true,
+    [CLIENT_CAPS.pluginTimelineItems]: true,
+    [CLIENT_CAPS.workspaceSetupBlocked]: true,
+    [CLIENT_CAPS.explicitEventSubscriptions]: true,
+};
+class TimelineInterest {
+    constructor() {
+        this.ready = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+        // Readiness is optional for fire-and-forget listeners.
+        void this.ready.catch(() => { });
+    }
+}
+/** Owns connection demand, independently of individual facades and React lifetimes. */
+export class ConnectionSubscriptions {
+    constructor(send) {
+        this.send = send;
+        this.viewed = new Set();
+        this.timelines = new Map();
+        this.events = [];
+    }
+    agentIds() {
+        return [...new Set([...this.viewed, ...this.timelines.keys()])].sort();
+    }
+    setViewed(agentIds) {
+        this.viewed = new Set(agentIds);
+        return this.syncTimelines();
+    }
+    observeTimeline(agentId) {
+        const interests = this.timelines.get(agentId) ?? new Set();
+        const interest = new TimelineInterest();
+        interests.add(interest);
+        this.timelines.set(agentId, interests);
+        // Each caller gets acknowledgement for its own registration, even when an
+        // existing listener first subscribed on an earlier connection.
+        void this.syncTimelines().catch(this.send.failed);
+        let active = true;
+        return Object.assign(() => {
+            if (!active)
+                return;
+            active = false;
+            interest.reject(new Error("Timeline subscription released before it was ready"));
+            interests.delete(interest);
+            if (interests.size === 0) {
+                this.timelines.delete(agentId);
+                void this.syncTimelines().catch(this.send.failed);
+            }
+        }, { ready: interest.ready });
+    }
+    async syncTimelines() {
+        const interests = [];
+        for (const listeners of this.timelines.values()) {
+            for (const interest of listeners)
+                interests.push(interest);
+        }
+        try {
+            const sent = this.send.timelines(this.agentIds());
+            if (!sent)
+                return;
+            await sent;
+            for (const interest of interests)
+                interest.resolve();
+        }
+        catch (error) {
+            for (const interest of interests)
+                interest.reject(error);
+            throw error;
+        }
+    }
+    setEvents(events) {
+        if (JSON.stringify(this.events) === JSON.stringify(events))
+            return;
+        this.events = events;
+        void this.send.events(events).catch(this.send.failed);
+    }
+    restore() {
+        if (this.agentIds().length)
+            void this.syncTimelines().catch(this.send.failed);
+        if (this.events.length)
+            void this.send.events(this.events).catch(this.send.failed);
+    }
+    close() {
+        for (const interests of this.timelines.values()) {
+            for (const interest of interests)
+                interest.reject(new Error("Daemon client closed"));
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/creation/index.d.ts

@@ -0,0 +1,47 @@
+import type { AgentSnapshotPayload, CreationSnapshot, WorkspaceCreateResponse } from "@camerontaylor/paseo-protocol/messages";
+import type { CreateAgentRequestOptions, CreateWorkspaceRequestOptions } from "../daemon-client.js";
+type Kind = CreationSnapshot["kind"];
+export interface CreationResult {
+    agent?: AgentSnapshotPayload | null;
+    workspace?: WorkspaceCreateResponse["payload"]["workspace"];
+    creation?: CreationSnapshot;
+    error: string | null;
+    errorCode?: string;
+    setupTerminalId?: string | null;
+    setupSkippedReason?: string;
+    requestId?: string;
+}
+interface Dependencies {
+    supports: () => boolean;
+    connected: () => boolean;
+    requestId: () => string;
+    request: (kind: Kind, input: Record<string, unknown>) => Promise<CreationResult>;
+    subscribe: (kind: Kind, key: string, enabled?: boolean) => Promise<CreationSnapshot | null>;
+    legacyAgent: (input: CreateAgentRequestOptions) => Promise<AgentSnapshotPayload>;
+    legacyWorkspace: (input: CreateWorkspaceRequestOptions) => Promise<WorkspaceCreateResponse["payload"]>;
+    sendMessage: (id: string, text: string, options: {
+        messageId: string;
+        images?: CreateAgentRequestOptions["images"];
+        attachments?: CreateAgentRequestOptions["attachments"];
+    }) => Promise<unknown>;
+}
+/** Client-owned observation and compatibility. UI callbacks never advance creation. */
+export declare class CreationClient {
+    private readonly deps;
+    private readonly operations;
+    constructor(deps: Dependencies);
+    createAgent(input: CreateAgentRequestOptions): Promise<CreationResult>;
+    createWorkspace(input: CreateWorkspaceRequestOptions): Promise<CreationResult>;
+    private legacyAgent;
+    private start;
+    private submit;
+    receive(snapshot: CreationSnapshot): void;
+    private recover;
+    reconnect(): void;
+    close(): void;
+    private finish;
+    private fail;
+    private notify;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/creation/index.js

@@ -0,0 +1,216 @@
+/** Client-owned observation and compatibility. UI callbacks never advance creation. */
+export class CreationClient {
+    constructor(deps) {
+        this.deps = deps;
+        this.operations = new Map();
+    }
+    createAgent(input) {
+        const { onEvent, ...request } = input;
+        return this.start("agent", request, onEvent, () => this.legacyAgent(request));
+    }
+    createWorkspace(input) {
+        const { onEvent, ...request } = input;
+        return this.start("workspace", request, onEvent, async (operation) => {
+            if (request.workspaceId || request.agent?.agentId)
+                throw new Error("Update the host to use caller-selected creation IDs.");
+            const { agent, ...workspaceInput } = request;
+            const workspace = await this.deps.legacyWorkspace(workspaceInput);
+            if (workspace.error || !workspace.workspace)
+                return workspace;
+            this.receive({
+                kind: "workspace",
+                idempotencyKey: operation.key,
+                revision: 1,
+                phase: "workspace_ready",
+                workspaceId: workspace.workspace.id,
+                agentId: null,
+                workspace: workspace.workspace,
+                setupSkippedReason: workspace.setupSkippedReason,
+                error: null,
+            });
+            if (!agent)
+                return workspace;
+            const sourceCwd = request.source.kind === "directory" ? request.source.path : request.source.cwd;
+            const cwd = sourceCwd
+                ? remapDirectory(agent.config.cwd, sourceCwd, workspace.workspace.workspaceDirectory)
+                : workspace.workspace.workspaceDirectory;
+            const created = await this.legacyAgent({
+                ...agent,
+                config: { ...agent.config, cwd },
+                workspaceId: workspace.workspace.id,
+                idempotencyKey: `${operation.key}:agent`,
+            });
+            return { ...workspace, agent: created.agent };
+        });
+    }
+    async legacyAgent(input) {
+        if (input.agentId)
+            throw new Error("Update the host to use caller-selected creation IDs.");
+        // COMPAT(creationLifecycle): added in v0.8.0, remove after 2027-03-11 once the daemon floor supports creationLifecycle.
+        // Old keyed creates reject initialPrompt. Keep this adaptation private to the SDK.
+        if (input.idempotencyKey) {
+            const { initialPrompt = "", images, attachments, ...creation } = input;
+            const hasPrompt = Boolean(initialPrompt.trim() || images?.length || attachments?.length);
+            if (hasPrompt && input.outputSchema)
+                throw new Error("Update the host to create a keyed agent with structured initial output.");
+            const agent = await this.deps.legacyAgent(creation);
+            if (hasPrompt)
+                await this.deps.sendMessage(agent.id, initialPrompt, {
+                    messageId: input.clientMessageId ?? `${input.idempotencyKey}:initial-message`,
+                    images,
+                    attachments,
+                });
+            return { agent, error: null };
+        }
+        return { agent: await this.deps.legacyAgent(input), error: null };
+    }
+    start(kind, input, observer, legacy) {
+        const key = typeof input.idempotencyKey === "string" ? input.idempotencyKey : this.deps.requestId();
+        const identity = JSON.stringify([kind, key]);
+        const { requestId: _requestId, ...intent } = input;
+        const fingerprint = JSON.stringify(intent, (_key, value) => value && typeof value === "object" && !Array.isArray(value)
+            ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)))
+            : value);
+        const previous = this.operations.get(identity);
+        if (previous) {
+            if (previous.fingerprint !== fingerprint)
+                return Promise.reject(new Error(`${kind}_request_key_conflict`));
+            if (observer) {
+                previous.observers.add(observer);
+                if (previous.snapshot)
+                    this.notify(observer, previous.snapshot);
+            }
+            return previous.result;
+        }
+        let resolve;
+        let reject;
+        const result = new Promise((done, fail) => {
+            resolve = done;
+            reject = fail;
+        });
+        const operation = {
+            kind,
+            key,
+            input: { ...input, idempotencyKey: key },
+            fingerprint,
+            observers: new Set(observer ? [observer] : []),
+            result,
+            resolve,
+            reject,
+            settled: false,
+            modern: this.deps.supports(),
+            recovering: false,
+        };
+        this.operations.set(identity, operation);
+        if (operation.modern)
+            void this.submit(operation);
+        else
+            void legacy(operation).then((value) => this.finish(operation, value), (error) => this.fail(operation, error));
+        return result;
+    }
+    async submit(operation) {
+        try {
+            const result = await this.deps.request(operation.kind, {
+                ...operation.input,
+                subscribe: true,
+            });
+            if (result.creation)
+                this.receive(result.creation);
+            this.finish(operation, result);
+        }
+        catch (error) {
+            if (operation.settled || !this.deps.connected())
+                return;
+            this.fail(operation, error);
+        }
+    }
+    receive(snapshot) {
+        const operation = this.operations.get(JSON.stringify([snapshot.kind, snapshot.idempotencyKey]));
+        if (!operation || (operation.snapshot && operation.snapshot.revision >= snapshot.revision))
+            return;
+        operation.snapshot = snapshot;
+        for (const observer of operation.observers)
+            this.notify(observer, snapshot);
+        if (operation.recovering && (snapshot.phase === "completed" || snapshot.phase === "failed")) {
+            this.finish(operation, {
+                agent: snapshot.agent,
+                workspace: snapshot.workspace,
+                creation: snapshot,
+                setupSkippedReason: snapshot.setupSkippedReason,
+                error: snapshot.error,
+                errorCode: snapshot.errorCode,
+            });
+        }
+    }
+    async recover(operation) {
+        operation.recovering = true;
+        const snapshot = await this.deps.subscribe(operation.kind, operation.key);
+        if (!snapshot) {
+            await this.submit(operation);
+            return;
+        }
+        this.receive(snapshot);
+        if (snapshot.phase === "completed" || snapshot.phase === "failed") {
+            this.finish(operation, {
+                agent: snapshot.agent,
+                workspace: snapshot.workspace,
+                creation: snapshot,
+                setupSkippedReason: snapshot.setupSkippedReason,
+                error: snapshot.error,
+                errorCode: snapshot.errorCode,
+            });
+        }
+    }
+    reconnect() {
+        for (const operation of this.operations.values()) {
+            if (operation.settled || !operation.modern)
+                continue;
+            void this.recover(operation).catch((error) => {
+                if (this.deps.connected())
+                    this.fail(operation, error);
+            });
+        }
+    }
+    close() {
+        for (const operation of this.operations.values())
+            if (!operation.settled)
+                this.fail(operation, new Error("Daemon client closed"));
+        this.operations.clear();
+    }
+    finish(operation, result) {
+        if (operation.settled)
+            return;
+        operation.settled = true;
+        if (operation.recovering)
+            void this.deps.subscribe(operation.kind, operation.key, false).catch(() => undefined);
+        operation.resolve(result);
+        operation.observers.clear();
+        this.operations.delete(JSON.stringify([operation.kind, operation.key]));
+    }
+    fail(operation, error) {
+        if (operation.settled)
+            return;
+        operation.settled = true;
+        operation.reject(error instanceof Error ? error : new Error(String(error)));
+        operation.observers.clear();
+        this.operations.delete(JSON.stringify([operation.kind, operation.key]));
+    }
+    notify(observer, snapshot) {
+        try {
+            observer(snapshot);
+        }
+        catch {
+            /* Observation does not control execution. */
+        }
+    }
+}
+function remapDirectory(cwd, source, target) {
+    const normalize = (value) => value.replace(/\\/g, "/").replace(/\/$/, "");
+    const normalized = normalize(cwd), root = normalize(source);
+    if (normalized === root)
+        return target;
+    if (!normalized.startsWith(`${root}/`))
+        throw new Error("Agent directory must be inside the workspace source");
+    return `${normalize(target)}${normalized.slice(root.length)}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/daemon-client-relay-e2ee-transport.d.ts

@@ -0,0 +1,8 @@
+import type { DaemonTransport, DaemonTransportFactory, TransportLogger } from "./daemon-client-transport-types.js";
+export declare function createRelayE2eeTransportFactory(args: {
+    baseFactory: DaemonTransportFactory;
+    daemonPublicKeyB64: string;
+    logger: TransportLogger;
+}): DaemonTransportFactory;
+export declare function createEncryptedTransport(base: DaemonTransport, daemonPublicKeyB64: string, logger: TransportLogger): DaemonTransport;
+//# sourceMappingURL=daemon-client-relay-e2ee-transport.d.ts.map