@hyperdrive.bot/fleet-client 0.3.218 → 0.3.221

package/README.md

@@ -1,12 +1,44 @@
 # @hyperdrive.bot/fleet-client
 
-Paseo's JavaScript/TypeScript client package.
+TypeScript SDK for building integrations on top of a Paseo daemon.
 
-## Stability
+```bash
+npm install @getpaseo/client
+```
+
+```ts
+import { createPaseoClient } from "@getpaseo/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 `@getpaseo/client/internal/*` are unsupported implementation details used by Paseo's own packages.
 
-This package is public so Paseo's published packages can depend on it cleanly.
-It is not a stable public SDK yet.
+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
 
-APIs, exports, runtime behavior, and types may change or disappear in any
-release without advance notice. Use it outside Paseo at your own risk until the
-package is explicitly documented as stable.
+The high-level API exported from `@getpaseo/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

@@ -5,7 +5,7 @@ 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): T;
-export declare function normalizeProviderSnapshotUpdateMessage(msg: SessionOutboundMessage): SessionOutboundMessage;
+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

@@ -1,4 +1,5 @@
 import { normalizeAgentModelDefinition } from "@hyperdrive.bot/fleet-protocol/agent-types";
+import { expandProviderSnapshot } from "@hyperdrive.bot/fleet-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) {
@@ -29,14 +30,22 @@ export function normalizeListProviderModelsPayload(payload) {
     const models = normalizeAgentModels(payload.models);
     return models === payload.models ? payload : { ...payload, models };
 }
-export function normalizeProvidersSnapshotPayload(payload) {
-    const entries = normalizeProviderSnapshotEntries(payload.entries);
+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) {
+export function normalizeProviderSnapshotUpdateMessage(msg, expand = true) {
     if (msg.type !== "providers_snapshot_update") {
         return msg;
     }
-    return { ...msg, payload: normalizeProvidersSnapshotPayload(msg.payload) };
+    return { ...msg, payload: normalizeProvidersSnapshotPayload(msg.payload, expand) };
 }
 //# sourceMappingURL=normalize-provider-models.js.map

package/dist/connection/index.d.ts

@@ -0,0 +1,50 @@
+export { OwnedSubscriptions, type OwnedSubscription, type SubscriptionObserver } from "./owned.js";
+import { OwnedSubscriptions, type OwnedSubscription, type OwnedSubscriptionsHost } from "./owned.js";
+import { type ObservationRequest } from "./legacy.js";
+import { type SessionInboundMessage, type SessionOutboundMessage, type ServerInfoStatusPayload } from "@hyperdrive.bot/fleet-protocol/messages";
+import { type ClientCapability } from "@hyperdrive.bot/fleet-protocol/client-capabilities";
+export declare class ConnectionSubscriptions extends OwnedSubscriptions {
+    private readonly connection;
+    private legacy;
+    constructor(connection: OwnedSubscriptionsHost & {
+        send(message: ObservationRequest): Promise<void>;
+    });
+    restore(info?: ServerInfoStatusPayload, capabilities?: Partial<Record<ClientCapability, unknown>>): void;
+    disconnected(): void;
+    observeRequest<T>(query: ObservationRequest, request: (query: ObservationRequest, accept: (snapshot: T) => void) => Promise<T>, signal?: AbortSignal, failed?: () => void): OwnedSubscription<T>;
+    owns(message: SessionOutboundMessage): boolean;
+    receive(message: SessionOutboundMessage): void;
+    normalize(message: SessionOutboundMessage): SessionOutboundMessage;
+    prepareRequest(message: SessionInboundMessage): {
+        message: SessionInboundMessage;
+        receive(message: SessionOutboundMessage): SessionOutboundMessage;
+        finish(): Promise<void>;
+    };
+}
+export declare const DEFAULT_CLIENT_CAPABILITIES: {
+    hello_rejection: true;
+    owned_subscriptions: true;
+    all_providers: true;
+    selective_agent_timeline: true;
+    reasoning_merge_enum: true;
+    custom_mode_icons: true;
+    terminal_reflowable_snapshot: true;
+    provider_subagents: true;
+    projected_subagent_timeline: 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;
+    agent_directory_delta: true;
+};
+/** Calling releases demand; ready waits for membership, or local attachment on broadcast hosts. */
+export type TimelineSubscription = (() => void) & {
+    readonly ready: Promise<void>;
+    readonly subscriptionId: string | null;
+    release(): Promise<void>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/connection/index.js

@@ -0,0 +1,119 @@
+export { OwnedSubscriptions } from "./owned.js";
+import { OwnedSubscriptions, } from "./owned.js";
+import { LegacySubscriptions } from "./legacy.js";
+import { CLIENT_CAPS, } from "@hyperdrive.bot/fleet-protocol/client-capabilities";
+export class ConnectionSubscriptions extends OwnedSubscriptions {
+    constructor(connection) {
+        super({
+            ...connection,
+            release: async (id) => {
+                if (!this.legacy)
+                    return connection.release(id);
+                const message = this.legacy.release(id);
+                if (message)
+                    await connection.send(message);
+            },
+        });
+        this.connection = connection;
+        this.legacy = null;
+    }
+    restore(info, capabilities) {
+        if (info) {
+            const clientCapabilities = capabilities ?? DEFAULT_CLIENT_CAPABILITIES;
+            const owned = info.features?.ownedSubscriptions === true &&
+                clientCapabilities[CLIENT_CAPS.ownedSubscriptions] === true;
+            this.legacy = null;
+            if (!owned) {
+                this.legacy = new LegacySubscriptions(info, this.connection.send, capabilities?.[CLIENT_CAPS.browserHost]);
+            }
+        }
+        super.restore();
+    }
+    disconnected() {
+        super.disconnected();
+        this.legacy = null;
+    }
+    observeRequest(query, request, signal, failed) {
+        return super.observe(async (accept) => {
+            const legacy = this.legacy;
+            if (!legacy)
+                return request(query, accept);
+            const interest = legacy.start(query);
+            const snapshot = (payload) => ({
+                ...payload,
+                subscriptionId: interest.id,
+            });
+            try {
+                const message = legacy.request(interest);
+                if (!message) {
+                    // Broadcast-era hosts have no acknowledgement. Readiness means the
+                    // local listener is attached; no server membership is being claimed.
+                    const value = snapshot({
+                        requestId: interest.id,
+                        ...(query.type === "agent.timeline.set_subscription.request"
+                            ? { agentIds: query.agentIds }
+                            : {}),
+                    });
+                    accept(value);
+                    return value;
+                }
+                return snapshot(await request(message, (payload) => accept(snapshot(payload))));
+            }
+            catch (error) {
+                const release = legacy.release(interest.id);
+                if (release && this.legacy === legacy)
+                    await this.connection.send(release).catch(this.connection.failed);
+                throw error;
+            }
+        }, signal, failed);
+    }
+    owns(message) {
+        return this.legacy ? this.legacy.owns(message) : super.owns(message);
+    }
+    receive(message) {
+        if (this.legacy)
+            this.legacy.receive(message, (update) => super.receive(update));
+        else
+            super.receive(message);
+    }
+    normalize(message) {
+        return this.legacy?.normalize(message) ?? message;
+    }
+    prepareRequest(message) {
+        return (this.legacy?.prepareRequest(message) ?? {
+            message,
+            receive: (value) => value,
+            finish: async () => { },
+        });
+    }
+}
+// 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.helloRejection]: true,
+    [CLIENT_CAPS.ownedSubscriptions]: true,
+    [CLIENT_CAPS.allProviders]: true,
+    [CLIENT_CAPS.selectiveAgentTimeline]: true,
+    [CLIENT_CAPS.reasoningMergeEnum]: true,
+    [CLIENT_CAPS.customModeIcons]: true,
+    [CLIENT_CAPS.terminalReflowableSnapshot]: true,
+    [CLIENT_CAPS.providerSubagents]: true,
+    [CLIENT_CAPS.projectedSubagentTimeline]: 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,
+    // Fork capability: the daemon only adds directory revisions for clients that
+    // advertise it, so it has to ride upstream's hello path or every client silently
+    // loses delta responses. Our pre-merge hello advertised exactly this one.
+    [CLIENT_CAPS.agentDirectoryDelta]: true,
+    // `daemonHealth` is deliberately NOT here. The mobile app opts in per client
+    // (`host-runtime.ts`, `capabilities: { [CLIENT_CAPS.daemonHealth]: true }`) because it
+    // is the only consumer, forwarding the push to rate-limited telemetry. Defaulting it on
+    // would make the daemon push health to the CLI, MCP and hub clients, which ignore it.
+};
+//# sourceMappingURL=index.js.map

package/dist/connection/legacy-workspaces.d.ts

@@ -0,0 +1,19 @@
+import type { SessionOutboundMessage } from "@hyperdrive.bot/fleet-protocol/messages";
+type AgentEntry = Extract<SessionOutboundMessage, {
+    type: "fetch_agents_response";
+}>["payload"]["entries"][number];
+type Workspace = Extract<SessionOutboundMessage, {
+    type: "fetch_workspaces_response";
+}>["payload"]["entries"][number];
+type WorkspaceUpdate = Extract<SessionOutboundMessage, {
+    type: "workspace_update";
+}>;
+export declare class LegacyWorkspaces {
+    private readonly agents;
+    normalize(message: SessionOutboundMessage): SessionOutboundMessage;
+    read(entries: AgentEntry[], reset: boolean): Workspace[];
+    update(message: SessionOutboundMessage): WorkspaceUpdate[];
+    private workspaces;
+}
+export {};
+//# sourceMappingURL=legacy-workspaces.d.ts.map

package/dist/connection/legacy-workspaces.js

@@ -0,0 +1,160 @@
+import { AgentSnapshotPayloadSchema } from "@hyperdrive.bot/fleet-protocol/messages";
+import { deriveAgentStateBucket, getWorkspaceStateBucketPriority, } from "@hyperdrive.bot/fleet-protocol/agent-state-bucket";
+// Preserve the pre-registry app's identity format. This is an opaque ID, never
+// a filesystem path: converting C:\ to C: changes a drive root into a relative path.
+function legacyWorkspaceId(value) {
+    return value.trim().replace(/\\/g, "/").replace(/\/+$/, "") || "/";
+}
+// COMPAT(legacyWorkspaceDaemon): restored in v0.8.0; remove after 2027-03-11 once daemon floor >= v0.1.97.
+// The pre-registry app grouped agents by checkout path. Keep that representation
+// at the client edge, including live updates, so app workflows need no version branch.
+export class LegacyWorkspaces {
+    constructor() {
+        this.agents = new Map();
+    }
+    normalize(message) {
+        const stamp = (agent) => ({
+            ...agent,
+            workspaceId: agent.workspaceId ?? legacyWorkspaceId(agent.cwd),
+        });
+        if (message.type === "fetch_agents_response")
+            return {
+                ...message,
+                payload: {
+                    ...message.payload,
+                    entries: message.payload.entries.map((entry) => ({
+                        ...entry,
+                        agent: stamp(entry.agent),
+                    })),
+                },
+            };
+        if (message.type === "agent_update" && message.payload.kind === "upsert")
+            return { ...message, payload: { ...message.payload, agent: stamp(message.payload.agent) } };
+        if ((message.type === "fetch_agent_response" ||
+            message.type === "fetch_agent_timeline_response" ||
+            message.type === "cancel_agent_response") &&
+            message.payload.agent) {
+            return {
+                ...message,
+                payload: { ...message.payload, agent: stamp(message.payload.agent) },
+            };
+        }
+        if (message.type === "status" &&
+            (message.payload.status === "agent_created" || message.payload.status === "agent_resumed")) {
+            return {
+                ...message,
+                payload: {
+                    ...message.payload,
+                    agent: stamp(AgentSnapshotPayloadSchema.parse(message.payload.agent)),
+                },
+            };
+        }
+        return message;
+    }
+    read(entries, reset) {
+        if (reset)
+            this.agents.clear();
+        for (const entry of entries)
+            this.agents.set(entry.agent.id, entry);
+        const pageIds = new Set(entries.map(workspaceId));
+        return [...this.workspaces().values()].filter((workspace) => pageIds.has(workspace.id));
+    }
+    update(message) {
+        if (message.type !== "agent_update")
+            return [];
+        const before = this.workspaces();
+        const update = message.payload;
+        if (update.kind === "remove")
+            this.agents.delete(update.agentId);
+        else {
+            const project = update.project ?? this.agents.get(update.agent.id)?.project;
+            if (update.agent.archivedAt)
+                this.agents.delete(update.agent.id);
+            else if (project)
+                this.agents.set(update.agent.id, { agent: update.agent, project });
+        }
+        const after = this.workspaces();
+        const changes = [];
+        for (const [id, workspace] of after) {
+            if (JSON.stringify(before.get(id)) !== JSON.stringify(workspace))
+                changes.push({ type: "workspace_update", payload: { kind: "upsert", workspace } });
+        }
+        for (const id of before.keys())
+            if (!after.has(id))
+                changes.push({ type: "workspace_update", payload: { kind: "remove", id } });
+        return changes;
+    }
+    workspaces() {
+        const workspaces = new Map();
+        for (const entry of this.agents.values()) {
+            const { agent, project } = entry;
+            const { checkout } = project;
+            const id = workspaceId(entry);
+            const status = deriveAgentStateBucket({
+                status: agent.status,
+                pendingPermissionCount: agent.pendingPermissions.length,
+                requiresAttention: agent.requiresAttention,
+                attentionReason: agent.attentionReason,
+            });
+            const existing = workspaces.get(id);
+            if (existing &&
+                getWorkspaceStateBucketPriority(existing.status) <= getWorkspaceStateBucketPriority(status))
+                continue;
+            workspaces.set(id, {
+                id,
+                projectId: project.projectKey,
+                projectDisplayName: project.projectName,
+                projectCustomName: null,
+                projectRootPath: checkout.mainRepoRoot ?? checkout.worktreeRoot ?? checkout.cwd,
+                workspaceDirectory: checkout.cwd,
+                projectKind: checkout.isGit ? "git" : "non_git",
+                workspaceKind: workspaceKind(checkout),
+                name: workspaceName(entry, id),
+                title: null,
+                status,
+                statusEnteredAt: agent.attentionTimestamp ?? agent.updatedAt,
+                activityAt: agent.updatedAt,
+                archivingAt: null,
+                diffStat: null,
+                scripts: [],
+                gitRuntime: gitRuntime(checkout),
+                githubRuntime: null,
+                project,
+            });
+        }
+        return workspaces;
+    }
+}
+function workspaceId(entry) {
+    return entry.agent.workspaceId ?? legacyWorkspaceId(entry.project.checkout.cwd);
+}
+function workspaceKind(checkout) {
+    if (!checkout.isGit)
+        return "directory";
+    if (checkout.isPaseoOwnedWorktree)
+        return "worktree";
+    return "checkout";
+}
+function workspaceName(entry, id) {
+    const name = entry.project.workspaceName?.trim();
+    if (name)
+        return name;
+    const branch = entry.project.checkout.currentBranch?.trim();
+    if (branch && branch !== "HEAD")
+        return branch;
+    return id.slice(id.lastIndexOf("/") + 1);
+}
+function gitRuntime(checkout) {
+    if (!checkout.isGit)
+        return null;
+    return {
+        currentBranch: checkout.currentBranch,
+        remoteUrl: checkout.remoteUrl,
+        isPaseoOwnedWorktree: checkout.isPaseoOwnedWorktree,
+        isDirty: null,
+        aheadBehind: null,
+        aheadOfOrigin: null,
+        behindOfOrigin: null,
+    };
+}
+//# sourceMappingURL=legacy-workspaces.js.map

package/dist/connection/legacy.d.ts

@@ -0,0 +1,31 @@
+import type { ServerInfoStatusPayload, SessionInboundMessage, SessionOutboundMessage } from "@hyperdrive.bot/fleet-protocol/messages";
+export type ObservationRequest = {
+    type: SessionInboundMessage["type"];
+} & Record<string, unknown>;
+interface Interest {
+    id: string;
+    query: ObservationRequest;
+}
+export declare class LegacySubscriptions {
+    private readonly info;
+    private readonly send;
+    private readonly browserHost;
+    private readonly interests;
+    private readonly workspaces;
+    constructor(info: ServerInfoStatusPayload, send: (message: ObservationRequest) => Promise<void>, browserHost: unknown);
+    normalize(message: SessionOutboundMessage): SessionOutboundMessage;
+    prepareRequest(message: SessionInboundMessage): {
+        message: SessionInboundMessage;
+        receive(message: SessionOutboundMessage): SessionOutboundMessage;
+        finish(): Promise<void>;
+    };
+    start(query: ObservationRequest): Interest;
+    request({ id, query }: Interest): ObservationRequest | null;
+    private members;
+    release(id: string): ObservationRequest | null;
+    owns(message: SessionOutboundMessage): boolean;
+    receive(message: SessionOutboundMessage, deliver: (message: SessionOutboundMessage) => void): void;
+    private matches;
+}
+export {};
+//# sourceMappingURL=legacy.d.ts.map