@getpaseo/client 0.3.0 → 0.4.0-beta.1

package/README.md

@@ -1,12 +1,39 @@
 # @getpaseo/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();
+```
 
-This package is public so Paseo's published packages can depend on it cleanly.
-It is not a stable public SDK yet.
+The public API is the package root. Imports under `@getpaseo/client/internal/*` are unsupported implementation details used by Paseo's own packages.
+
+Read the [SDK documentation](https://paseo.sh/docs/sdk) for agents, workspaces, 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.
+
+## 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/daemon-client.d.ts

@@ -4,7 +4,7 @@ import type { AgentAttentionNotificationPayload } from "@getpaseo/protocol/agent
 import { AgentRefreshedStatusPayloadSchema, CheckoutRenameBranchResponseSchema, RenameTerminalResponseSchema, RestartRequestedStatusPayloadSchema, ShutdownRequestedStatusPayloadSchema, DaemonUpdateResponseSchema, type ServerInfoStatusPayload } from "@getpaseo/protocol/messages";
 import type { AgentStreamEventPayload, AgentSnapshotPayload, ProjectPlacementPayload, AgentPermissionResolvedMessage, CreateAgentRequestMessage, CreatePaseoWorktreeRequest, FileDownloadTokenResponse, FileUploadResponse, FileExplorerResponse, FileVersion, FileWriteResult, FetchAgentTimelineResponseMessage, AgentForkContextResponseMessage, GitSetupOptions, CheckoutStatusResponse, CheckoutCommit, ParsedDiffFile, CheckoutCommitResponse, CheckoutMergeResponse, CheckoutMergeFromBaseResponse, CheckoutPullResponse, CheckoutPushResponse, CheckoutRefreshResponse, CheckoutPrCreateResponse, CheckoutPrMergeResponse, CheckoutPrMergeMethod, CheckoutForgeSetAutoMergeResponse, CheckoutGithubSetAutoMergeResponse, CheckoutForgeGetCheckDetailsResponse, CheckoutGithubGetCheckDetailsResponse, CheckoutPrStatusResponse, PullRequestTimelineResponse, CheckoutSwitchBranchResponse, StashSaveResponse, StashPopResponse, StashListResponse, ValidateBranchResponse, BranchSuggestionsResponse, ForgeSearchResponse, ForgeSearchRequest, GitHubSearchResponse, GitHubSearchRequest, DirectorySuggestionsResponse, PaseoWorktreeListResponse, PaseoWorktreeArchiveResponse, ProjectIconSource, ProjectIconResponse, ProjectIconGetResponse, ProjectAddResponse, ProjectCreateDirectoryResponse, OpenProjectResponseMessage, WorkspaceGithubSearchRepositoriesResponse, ProjectGithubCloneProtocol, ProjectGithubCloneResponse, ArchiveWorkspaceResponseMessage, WorkspaceSetupStatusResponseMessage, ListCommandsResponse, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ListProviderModesResponseMessage, ListAvailableProvidersResponse, GetProvidersSnapshotResponseMessage, RefreshProvidersSnapshotResponseMessage, ProviderDiagnosticResponseMessage, ProviderUsageListResponseMessage, DaemonGetStatusResponse, DaemonGetPairingOfferResponse, DiagnosticsResponse, AgentRewindResponseMessage, ListTerminalsResponse, CreateTerminalResponse, SubscribeTerminalResponse, SubscribeTerminalRequest, CloseItemsResponse, KillTerminalResponse, CaptureTerminalResponse, TerminalInput, SessionInboundMessage, SessionOutboundMessage, SendAgentMessageRequest, PaseoConfigRaw, PaseoConfigRevision, WorkspaceCreateRequest, WorkspaceRecoveryState } from "@getpaseo/protocol/messages";
 import type { AgentPermissionRequest, AgentPermissionResponse, AgentPersistenceHandle, AgentProviderNotice, AgentProvider, AgentSessionConfig } from "@getpaseo/protocol/agent-types";
-import type { MutableDaemonConfig, MutableDaemonConfigPatch } from "@getpaseo/protocol/messages";
+import type { AgentConfigApply, MutableDaemonConfig, MutableDaemonConfigPatch } from "@getpaseo/protocol/messages";
 import { type DaemonTransportFactory, type WebSocketFactory } from "./daemon-client-transport.js";
 import { type TerminalStreamEvent } from "./terminal-stream-router.js";
 import type { BrowserAutomationExecuteRequest, BrowserAutomationExecuteResponse } from "@getpaseo/protocol/browser-automation/rpc-schemas";
@@ -108,7 +108,6 @@ export interface DaemonClientConfig {
     runtimeGeneration?: number | null;
     password?: string;
     authHeader?: string;
-    headers?: Record<string, string>;
     suppressSendErrors?: boolean;
     transportFactory?: DaemonTransportFactory;
     webSocketFactory?: WebSocketFactory;
@@ -271,42 +270,6 @@ type SubscribeTerminalPayload = SubscribeTerminalResponse["payload"];
 type CloseItemsPayload = CloseItemsResponse["payload"];
 type KillTerminalPayload = KillTerminalResponse["payload"];
 type CaptureTerminalPayload = CaptureTerminalResponse["payload"];
-type ChatCreatePayload = Extract<SessionOutboundMessage, {
-    type: "chat/create/response";
-}>["payload"];
-type ChatListPayload = Extract<SessionOutboundMessage, {
-    type: "chat/list/response";
-}>["payload"];
-type ChatInspectPayload = Extract<SessionOutboundMessage, {
-    type: "chat/inspect/response";
-}>["payload"];
-type ChatDeletePayload = Extract<SessionOutboundMessage, {
-    type: "chat/delete/response";
-}>["payload"];
-type ChatPostPayload = Extract<SessionOutboundMessage, {
-    type: "chat/post/response";
-}>["payload"];
-type ChatReadPayload = Extract<SessionOutboundMessage, {
-    type: "chat/read/response";
-}>["payload"];
-type ChatWaitPayload = Extract<SessionOutboundMessage, {
-    type: "chat/wait/response";
-}>["payload"];
-type LoopRunPayload = Extract<SessionOutboundMessage, {
-    type: "loop/run/response";
-}>["payload"];
-type LoopListPayload = Extract<SessionOutboundMessage, {
-    type: "loop/list/response";
-}>["payload"];
-type LoopInspectPayload = Extract<SessionOutboundMessage, {
-    type: "loop/inspect/response";
-}>["payload"];
-type LoopLogsPayload = Extract<SessionOutboundMessage, {
-    type: "loop/logs/response";
-}>["payload"];
-type LoopStopPayload = Extract<SessionOutboundMessage, {
-    type: "loop/stop/response";
-}>["payload"];
 type ScheduleCreatePayload = Extract<SessionOutboundMessage, {
     type: "schedule/create/response";
 }>["payload"];
@@ -438,70 +401,6 @@ export type FetchWorkspacesPageInfo = FetchWorkspacesPayload["pageInfo"];
 export type ProjectListPayload = Extract<SessionOutboundMessage, {
     type: "project.list.response";
 }>["payload"];
-export interface CreateChatRoomOptions {
-    name: string;
-    purpose?: string | null;
-    requestId?: string;
-}
-export interface InspectChatRoomOptions {
-    room: string;
-    requestId?: string;
-}
-export interface DeleteChatRoomOptions {
-    room: string;
-    requestId?: string;
-}
-export interface PostChatMessageOptions {
-    room: string;
-    body: string;
-    authorAgentId?: string;
-    replyToMessageId?: string | null;
-    requestId?: string;
-}
-export interface ReadChatMessagesOptions {
-    room: string;
-    limit?: number;
-    since?: string;
-    authorAgentId?: string;
-    requestId?: string;
-    timeout?: number;
-}
-export interface WaitForChatMessagesOptions {
-    room: string;
-    afterMessageId?: string | null;
-    timeoutMs?: number;
-    requestId?: string;
-}
-export interface RunLoopOptions {
-    prompt: string;
-    cwd: string;
-    provider?: string;
-    model?: string;
-    modeId?: string;
-    verifierProvider?: string;
-    verifierModel?: string;
-    verifierModeId?: string;
-    verifyPrompt?: string | null;
-    verifyChecks?: string[];
-    name?: string | null;
-    sleepMs?: number;
-    maxIterations?: number;
-    maxTimeMs?: number;
-    requestId?: string;
-}
-export interface InspectLoopOptions {
-    id: string;
-    requestId?: string;
-}
-export interface LoopLogsOptions {
-    id: string;
-    afterSeq?: number;
-    requestId?: string;
-}
-export interface StopLoopOptions {
-    id: string;
-    requestId?: string;
-}
 export interface CreateScheduleOptions {
     prompt: string;
     name?: string | null;
@@ -527,11 +426,7 @@ export interface CreateScheduleOptions {
             archiveOnFinish?: boolean;
             isolation?: "local" | "worktree";
             title?: string | null;
-            approvalPolicy?: string;
-            sandboxMode?: string;
-            networkAccess?: boolean;
-            webSearch?: boolean;
-            extra?: AgentSessionConfig["extra"];
+            providerOptions?: AgentSessionConfig["providerOptions"];
             systemPrompt?: string;
             mcpServers?: AgentSessionConfig["mcpServers"];
         };
@@ -595,6 +490,21 @@ export interface WaitForFinishResult {
     error: string | null;
     lastMessage: string | null;
 }
+type GetDaemonConfigResponse = Extract<SessionOutboundMessage, {
+    type: "get_daemon_config_response";
+}>;
+type SetDaemonConfigResponse = Extract<SessionOutboundMessage, {
+    type: "set_daemon_config_response";
+}>;
+type CorrelatedResponseMessage = Extract<SessionOutboundMessage, {
+    payload: {
+        requestId: string;
+    };
+}> | GetDaemonConfigResponse | SetDaemonConfigResponse;
+type CorrelatedResponseType = CorrelatedResponseMessage["type"];
+type CorrelatedResponsePayload<TType extends CorrelatedResponseType> = Extract<CorrelatedResponseMessage, {
+    type: TType;
+}>["payload"];
 export declare class DaemonClient {
     private config;
     private transport;
@@ -698,6 +608,7 @@ export declare class DaemonClient {
         appVisibilityChangedAt?: string;
     }): void;
     registerPushToken(token: string): void;
+    unregisterPushToken(token: string): Promise<void>;
     ping(params?: {
         requestId?: string;
         timeoutMs?: number;
@@ -804,6 +715,14 @@ export declare class DaemonClient {
     setAgentModel(agentId: string, modelId: string | null): Promise<void>;
     setAgentFeature(agentId: string, featureId: string, value: unknown): Promise<void>;
     setAgentThinkingOption(agentId: string, thinkingOptionId: string | null): Promise<AgentProviderNotice | null>;
+    /**
+     * Applies a whole agent-config bundle in one request. Use this instead of
+     * chaining the single-field setters when the values belong together so client
+     * interruption and other mutations cannot interleave between steps. A
+     * provider rejection can still leave earlier steps applied.
+     * Gated on `server_info.features.agentConfigApply`.
+     */
+    applyAgentConfig(agentId: string, config: AgentConfigApply): Promise<AgentProviderNotice | null>;
     restartServer(reason?: string, requestId?: string): Promise<RestartRequestedStatusPayload>;
     shutdownServer(options?: ShutdownServerOptions): Promise<ShutdownRequestedStatusPayload>;
     updateDaemon(requestId?: string): Promise<DaemonUpdateResponse["payload"]>;
@@ -973,6 +892,28 @@ export declare class DaemonClient {
         expectedModifiedAt: string;
         expectedRevision?: string;
     }): Promise<FileWriteResult>;
+    createFileEntry(input: {
+        cwd: string;
+        parentPath: string;
+        name: string;
+        kind: "file" | "directory";
+    }): Promise<CorrelatedResponsePayload<"fs.entry.create.response">>;
+    renameFileEntry(input: {
+        cwd: string;
+        path: string;
+        name: string;
+    }): Promise<CorrelatedResponsePayload<"fs.entry.rename.response">>;
+    duplicateFileEntry(input: {
+        cwd: string;
+        path: string;
+    }): Promise<CorrelatedResponsePayload<"fs.entry.duplicate.response">>;
+    deleteFileEntry(input: {
+        cwd: string;
+        path: string;
+    }): Promise<CorrelatedResponsePayload<"fs.entry.delete.response">>;
+    checkoutDiscardChanges(cwd: string, input: {
+        paths: string[];
+    }): Promise<CorrelatedResponsePayload<"checkout.discard_changes.response">>;
     uploadFile(input: FileUploadInput): Promise<FileUploadResult>;
     requestDownloadToken(cwd: string, path: string, requestId?: string): Promise<FileDownloadTokenPayload>;
     requestProjectIcon(cwd: string, requestId?: string): Promise<ProjectIconResponse["payload"]>;
@@ -1100,13 +1041,6 @@ export declare class DaemonClient {
         end?: number;
         stripAnsi?: boolean;
     }, requestId?: string): Promise<CaptureTerminalPayload>;
-    createChatRoom(options: CreateChatRoomOptions): Promise<ChatCreatePayload>;
-    listChatRooms(requestId?: string): Promise<ChatListPayload>;
-    inspectChatRoom(options: InspectChatRoomOptions): Promise<ChatInspectPayload>;
-    deleteChatRoom(options: DeleteChatRoomOptions): Promise<ChatDeletePayload>;
-    postChatMessage(options: PostChatMessageOptions): Promise<ChatPostPayload>;
-    readChatMessages(options: ReadChatMessagesOptions): Promise<ChatReadPayload>;
-    waitForChatMessages(options: WaitForChatMessagesOptions): Promise<ChatWaitPayload>;
     scheduleCreate(options: CreateScheduleOptions): Promise<ScheduleCreatePayload>;
     scheduleList(requestId?: string): Promise<ScheduleListPayload>;
     scheduleInspect(options: InspectScheduleOptions): Promise<ScheduleInspectPayload>;
@@ -1116,11 +1050,6 @@ export declare class DaemonClient {
     scheduleDelete(options: InspectScheduleOptions): Promise<ScheduleDeletePayload>;
     scheduleRunOnce(options: InspectScheduleOptions): Promise<ScheduleRunOncePayload>;
     scheduleUpdate(options: UpdateScheduleOptions): Promise<ScheduleUpdatePayload>;
-    loopRun(options: RunLoopOptions): Promise<LoopRunPayload>;
-    loopList(requestId?: string): Promise<LoopListPayload>;
-    loopInspect(options: string | InspectLoopOptions): Promise<LoopInspectPayload>;
-    loopLogs(options: string | LoopLogsOptions, afterSeq?: number): Promise<LoopLogsPayload>;
-    loopStop(options: string | StopLoopOptions): Promise<LoopStopPayload>;
     onTerminalStreamEvent(handler: (event: TerminalStreamEvent) => void): () => void;
     waitForTerminalStreamEvent(predicate: (event: TerminalStreamEvent) => boolean, timeout?: number): Promise<TerminalStreamEvent>;
     private createRequestId;

package/dist/daemon-client.js

@@ -112,6 +112,7 @@ function toTimeoutError(error, label, timeoutMs) {
 const DEFAULT_RECONNECT_BASE_DELAY_MS = 1500;
 const DEFAULT_RECONNECT_MAX_DELAY_MS = 30000;
 const DEFAULT_SESSION_RPC_TIMEOUT_MS = 60000;
+const PUSH_TOKEN_REVOCATION_TIMEOUT_MS = 2000;
 const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
 const DEFAULT_LIVENESS_TIMEOUT_MS = 5000;
 const LIVENESS_HEARTBEAT_INTERVAL_MS = 10000;
@@ -331,7 +332,7 @@ export class DaemonClient {
         if (this.connectionState.status === "connecting") {
             return;
         }
-        const headers = { ...this.config.headers };
+        const headers = {};
         const password = normalizePassword(this.config.password);
         if (password) {
             headers.Authorization = `Bearer ${password}`;
@@ -902,6 +903,15 @@ export class DaemonClient {
             token,
         });
     }
+    async unregisterPushToken(token) {
+        const requestId = this.createRequestId();
+        await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "push.unregister.request", token, requestId },
+            responseType: "push.unregister.response",
+            timeout: PUSH_TOKEN_REVOCATION_TIMEOUT_MS,
+        });
+    }
     async ping(params) {
         const requestId = params?.requestId ?? `ping-${Date.now()}-${Math.random().toString(36).slice(2)}`;
         const clientSentAt = Date.now();
@@ -1985,6 +1995,40 @@ export class DaemonClient {
         }
         return payload.notice ?? null;
     }
+    /**
+     * Applies a whole agent-config bundle in one request. Use this instead of
+     * chaining the single-field setters when the values belong together so client
+     * interruption and other mutations cannot interleave between steps. A
+     * provider rejection can still leave earlier steps applied.
+     * Gated on `server_info.features.agentConfigApply`.
+     */
+    async applyAgentConfig(agentId, config) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.config.apply.request",
+            agentId,
+            config,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent.config.apply.response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "applyAgentConfig rejected");
+        }
+        return payload.notice ?? null;
+    }
     async restartServer(reason, requestId) {
         const resolvedRequestId = this.createRequestId(requestId);
         const message = SessionInboundMessageSchema.parse({
@@ -2851,6 +2895,31 @@ export class DaemonClient {
         });
         return payload.result;
     }
+    async createFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.create.request", ...input },
+        });
+    }
+    async renameFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.rename.request", ...input },
+        });
+    }
+    async duplicateFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.duplicate.request", ...input },
+        });
+    }
+    async deleteFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.delete.request", ...input },
+        });
+    }
+    async checkoutDiscardChanges(cwd, input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "checkout.discard_changes.request", cwd, paths: input.paths },
+        });
+    }
     async uploadFile(input) {
         const bytes = asUint8Array(input.bytes);
         if (!bytes) {
@@ -3436,86 +3505,6 @@ export class DaemonClient {
             options: { skipQueue: true },
         });
     }
-    async createChatRoom(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "chat/create",
-                name: options.name,
-                ...(options.purpose ? { purpose: options.purpose } : {}),
-            },
-            responseType: "chat/create/response",
-        });
-    }
-    async listChatRooms(requestId) {
-        return this.sendCorrelatedSessionRequest({
-            requestId,
-            message: {
-                type: "chat/list",
-            },
-            responseType: "chat/list/response",
-        });
-    }
-    async inspectChatRoom(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "chat/inspect",
-                room: options.room,
-            },
-            responseType: "chat/inspect/response",
-        });
-    }
-    async deleteChatRoom(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "chat/delete",
-                room: options.room,
-            },
-            responseType: "chat/delete/response",
-        });
-    }
-    async postChatMessage(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "chat/post",
-                room: options.room,
-                body: options.body,
-                ...(options.authorAgentId ? { authorAgentId: options.authorAgentId } : {}),
-                ...(options.replyToMessageId ? { replyToMessageId: options.replyToMessageId } : {}),
-            },
-            responseType: "chat/post/response",
-        });
-    }
-    async readChatMessages(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "chat/read",
-                room: options.room,
-                ...(typeof options.limit === "number" ? { limit: options.limit } : {}),
-                ...(options.since ? { since: options.since } : {}),
-                ...(options.authorAgentId ? { authorAgentId: options.authorAgentId } : {}),
-            },
-            responseType: "chat/read/response",
-            timeout: options.timeout,
-        });
-    }
-    async waitForChatMessages(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "chat/wait",
-                room: options.room,
-                ...(options.afterMessageId ? { afterMessageId: options.afterMessageId } : {}),
-                ...(typeof options.timeoutMs === "number" ? { timeoutMs: options.timeoutMs } : {}),
-            },
-            responseType: "chat/wait/response",
-            timeout: (options.timeoutMs ?? 0) + 10000,
-        });
-    }
     async scheduleCreate(options) {
         return this.sendCorrelatedSessionRequest({
             requestId: options.requestId,
@@ -3617,76 +3606,6 @@ export class DaemonClient {
             responseType: "schedule/update/response",
         });
     }
-    async loopRun(options) {
-        return this.sendCorrelatedSessionRequest({
-            requestId: options.requestId,
-            message: {
-                type: "loop/run",
-                prompt: options.prompt,
-                cwd: options.cwd,
-                ...(options.provider ? { provider: options.provider } : {}),
-                ...(options.model ? { model: options.model } : {}),
-                ...(options.modeId ? { modeId: options.modeId } : {}),
-                ...(options.verifierProvider ? { verifierProvider: options.verifierProvider } : {}),
-                ...(options.verifierModel ? { verifierModel: options.verifierModel } : {}),
-                ...(options.verifierModeId ? { verifierModeId: options.verifierModeId } : {}),
-                ...(options.verifyPrompt ? { verifyPrompt: options.verifyPrompt } : {}),
-                ...(options.verifyChecks && options.verifyChecks.length > 0
-                    ? { verifyChecks: options.verifyChecks }
-                    : {}),
-                ...(options.name ? { name: options.name } : {}),
-                ...(typeof options.sleepMs === "number" ? { sleepMs: options.sleepMs } : {}),
-                ...(typeof options.maxIterations === "number"
-                    ? { maxIterations: options.maxIterations }
-                    : {}),
-                ...(typeof options.maxTimeMs === "number" ? { maxTimeMs: options.maxTimeMs } : {}),
-            },
-            responseType: "loop/run/response",
-        });
-    }
-    async loopList(requestId) {
-        return this.sendCorrelatedSessionRequest({
-            requestId,
-            message: {
-                type: "loop/list",
-            },
-            responseType: "loop/list/response",
-        });
-    }
-    async loopInspect(options) {
-        const normalized = typeof options === "string" ? { id: options } : options;
-        return this.sendCorrelatedSessionRequest({
-            requestId: normalized.requestId,
-            message: {
-                type: "loop/inspect",
-                id: normalized.id,
-            },
-            responseType: "loop/inspect/response",
-        });
-    }
-    async loopLogs(options, afterSeq) {
-        const normalized = typeof options === "string" ? { id: options, afterSeq } : options;
-        return this.sendCorrelatedSessionRequest({
-            requestId: normalized.requestId,
-            message: {
-                type: "loop/logs",
-                id: normalized.id,
-                ...(typeof normalized.afterSeq === "number" ? { afterSeq: normalized.afterSeq } : {}),
-            },
-            responseType: "loop/logs/response",
-        });
-    }
-    async loopStop(options) {
-        const normalized = typeof options === "string" ? { id: options } : options;
-        return this.sendCorrelatedSessionRequest({
-            requestId: normalized.requestId,
-            message: {
-                type: "loop/stop",
-                id: normalized.id,
-            },
-            responseType: "loop/stop/response",
-        });
-    }
     onTerminalStreamEvent(handler) {
         return this.terminalStreams.onEvent(handler);
     }

package/dist/index.d.ts

@@ -1,8 +1,5 @@
-import type { AgentSnapshotPayload, CreateAgentRequestMessage, FetchWorkspacesRequestMessage, FetchWorkspacesResponseMessage, GetProvidersSnapshotResponseMessage, ListAvailableProvidersResponse, ListProviderFeaturesRequestMessage, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ListProviderModesResponseMessage, MutableDaemonConfig, MutableDaemonConfigPatch, ProviderDiagnosticResponseMessage, ProjectPlacementPayload, RefreshProvidersSnapshotResponseMessage, SendAgentMessageRequest, SessionOutboundMessage, WorkspaceDescriptorPayload } from "@getpaseo/protocol/messages";
-import { DaemonClient } from "./daemon-client.js";
-import type { FetchAgentTimelineCursor, FetchAgentTimelineDirection, FetchAgentTimelinePayload, FetchAgentTimelineProjection } from "./daemon-client.js";
-export { DaemonClient };
-export type { DaemonClientConfig, DaemonEvent, BrowserAutomationExecuteRequestMessage, BrowserAutomationExecuteResponseMessage, WebSocketFactory, WebSocketLike, } from "./daemon-client.js";
+import type { AgentSnapshotPayload, CreateAgentRequestMessage, FetchWorkspacesRequestMessage, FetchWorkspacesResponseMessage, GetProvidersSnapshotResponseMessage, ListAvailableProvidersResponse, ListProviderFeaturesRequestMessage, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ListProviderModesResponseMessage, MutableDaemonConfig, MutableDaemonConfigPatch, ProviderDiagnosticResponseMessage, ProjectPlacementPayload, RefreshProvidersSnapshotResponseMessage, SendAgentMessageRequest, SessionOutboundMessage, WorkspaceDescriptorPayload, WorkspaceCreateRequest } from "@getpaseo/protocol/messages";
+import type { FetchAgentsEntry, FetchAgentsOptions, FetchAgentsPageInfo, FetchAgentTimelineCursor, FetchAgentTimelineDirection, FetchAgentTimelinePayload, FetchAgentTimelineProjection, WaitForFinishResult } from "./daemon-client.js";
 export type ConnectionState = {
     status: "idle";
 } | {
@@ -29,7 +26,6 @@ export interface PaseoClientConfig {
     runtimeGeneration?: number | null;
     password?: string;
     authHeader?: string;
-    headers?: Record<string, string>;
     suppressSendErrors?: boolean;
     logger?: PaseoLogger;
     connectTimeoutMs?: number;
@@ -47,6 +43,13 @@ export interface PaseoClientConfig {
 }
 export type PaseoWorkspace = WorkspaceDescriptorPayload;
 export type PaseoAgent = AgentSnapshotPayload;
+export type PaseoAgentListOptions = FetchAgentsOptions;
+export interface PaseoAgentListResult {
+    requestId: string;
+    subscriptionId?: string | null;
+    entries: FetchAgentsEntry[];
+    pageInfo: FetchAgentsPageInfo;
+}
 export type PaseoWorkspaceListOptions = Omit<FetchWorkspacesRequestMessage, "type" | "requestId"> & {
     requestId?: string;
 };
@@ -60,11 +63,9 @@ export interface PaseoWorkspaceOpenOptions {
     cwd: string;
     requestId?: string;
 }
-export interface PaseoWorkspaceOpenResult {
-    requestId: string;
-    workspace: PaseoWorkspaceHandle | null;
-    error: string | null;
-}
+export type PaseoWorkspaceCreateOptions = Omit<WorkspaceCreateRequest, "type" | "requestId"> & {
+    requestId?: string;
+};
 export interface PaseoWorkspaceArchiveResult {
     requestId: string;
     workspaceId: string;
@@ -75,19 +76,17 @@ export type PaseoWorkspaceUpdate = Extract<SessionOutboundMessage, {
     type: "workspace_update";
 }>["payload"];
 export type PaseoWorkspaceUpdateHandler = (update: PaseoWorkspaceUpdate) => void;
-/**
- * A handle is a stable typed reference to a daemon resource. Its identity is the
- * daemon id, and `latest()` only returns the most recent snapshot this handle has
- * seen through construction, `refetch()`, or this handle's local subscription.
- */
 export interface PaseoWorkspaceHandle {
     readonly id: string;
-    latest(): PaseoWorkspace | null;
-    /**
-     * Fetches a fresh workspace snapshot through the existing workspace list RPC,
-     * exact-matches this handle id from the result, and updates `latest()`.
-     */
-    refetch(options?: {
+    readonly projectId: string | null;
+    readonly directory: string | null;
+    readonly name: string | null;
+    readonly status: PaseoWorkspace["status"] | null;
+    readonly agents: {
+        create(options: PaseoWorkspaceAgentCreateOptions): Promise<PaseoAgentHandle>;
+    };
+    current(): PaseoWorkspace | null;
+    refresh(options?: {
         requestId?: string;
     }): Promise<PaseoWorkspace | null>;
     archive(requestId?: string): Promise<PaseoWorkspaceArchiveResult>;
@@ -102,8 +101,8 @@ export interface PaseoWorkspaceHandle {
 export interface PaseoWorkspaceActions {
     list(options?: PaseoWorkspaceListOptions): Promise<PaseoWorkspaceListResult>;
     ref(workspace: string | PaseoWorkspace): PaseoWorkspaceHandle;
-    open(input: string | PaseoWorkspaceOpenOptions, requestId?: string): Promise<PaseoWorkspaceOpenResult>;
-    create(input: string | PaseoWorkspaceOpenOptions, requestId?: string): Promise<PaseoWorkspaceOpenResult>;
+    open(input: string | PaseoWorkspaceOpenOptions, requestId?: string): Promise<PaseoWorkspaceHandle>;
+    create(options: PaseoWorkspaceCreateOptions): Promise<PaseoWorkspaceHandle>;
     archive(workspace: string | PaseoWorkspaceHandle, requestId?: string): Promise<PaseoWorkspaceArchiveResult>;
     /**
      * Local event subscription over the low-level driver's workspace_update stream.
@@ -112,23 +111,38 @@ export interface PaseoWorkspaceActions {
     subscribe(handler: PaseoWorkspaceUpdateHandler): () => void;
 }
 type PaseoAgentSessionConfig = CreateAgentRequestMessage["config"];
-type PaseoAgentProvider = PaseoAgentSessionConfig["provider"];
-type PaseoAgentConfigOverrides = Partial<Omit<PaseoAgentSessionConfig, "provider" | "cwd">>;
-export interface PaseoAgentCreateOptions extends PaseoAgentConfigOverrides {
-    config?: PaseoAgentSessionConfig;
-    provider?: CreateAgentRequestMessage["config"]["provider"];
-    cwd?: string;
-    workspaceId?: string;
-    callerAgentId?: string;
-    initialPrompt?: string;
+export type PaseoAgentProvider = PaseoAgentSessionConfig["provider"];
+export type PaseoProviderFeatureValues = Record<string, unknown>;
+export interface PaseoAgentConfig {
+    /** Provider and model in `provider/model` format. */
+    provider: string;
+    modeId?: PaseoAgentSessionConfig["modeId"];
+    thinkingOptionId?: PaseoAgentSessionConfig["thinkingOptionId"];
+    featureValues?: PaseoProviderFeatureValues;
+    /** JSON-safe provider-native settings, validated by the selected provider. */
+    options?: PaseoAgentSessionConfig["providerOptions"];
+    systemPrompt?: PaseoAgentSessionConfig["systemPrompt"];
+    toolPolicy?: PaseoAgentSessionConfig["toolPolicy"];
+    mcpServers?: PaseoAgentSessionConfig["mcpServers"];
+}
+export interface PaseoAgentCreateOptions {
+    config: PaseoAgentConfig;
+    cwd: string;
+    parent?: string | PaseoAgentHandle;
+    title?: PaseoAgentSessionConfig["title"];
+    env?: CreateAgentRequestMessage["env"];
+    prompt?: string;
     clientMessageId?: string;
     outputSchema?: Record<string, unknown>;
     images?: CreateAgentRequestMessage["images"];
     attachments?: CreateAgentRequestMessage["attachments"];
     git?: CreateAgentRequestMessage["git"];
+    worktree?: CreateAgentRequestMessage["worktree"];
+    autoArchive?: CreateAgentRequestMessage["autoArchive"];
     requestId?: string;
     labels?: Record<string, string>;
 }
+export type PaseoWorkspaceAgentCreateOptions = Omit<PaseoAgentCreateOptions, "cwd">;
 export interface PaseoAgentRefetchResult {
     agent: PaseoAgent;
     project: ProjectPlacementPayload | null;
@@ -148,6 +162,10 @@ export interface PaseoAgentSendOptions {
     }>;
     attachments?: SendAgentMessageRequest["attachments"];
 }
+export interface PaseoAgentRunOptions extends PaseoAgentSendOptions {
+    timeoutMs?: number;
+}
+export type PaseoAgentRunResult = WaitForFinishResult;
 export type PaseoAgentUpdate = Extract<SessionOutboundMessage, {
     type: "agent_update";
 }>["payload"];
@@ -158,8 +176,8 @@ export type PaseoAgentUpdateHandler = (update: PaseoAgentUpdate) => void;
 export interface PaseoAgentTimelineHandle {
     /**
      * Fetches a fresh timeline page through the existing daemon RPC. If the daemon
-     * includes an agent snapshot in the response, the parent handle's `latest()`
-     * is updated to that snapshot.
+     * includes an agent snapshot in the response, the parent handle is updated to
+     * that value.
      */
     refetch(options?: PaseoAgentTimelineRefetchOptions): Promise<FetchAgentTimelinePayload>;
     /**
@@ -168,18 +186,19 @@ export interface PaseoAgentTimelineHandle {
      */
     subscribe(handler: (event: PaseoAgentStream) => void): () => void;
 }
-/**
- * Agent handles follow the same identity/snapshot rule as workspace handles:
- * `id` is stable, while `latest()` is only the newest snapshot observed by this
- * handle through construction, `refetch()`, timeline refetch, archive, or local
- * agent_update subscription.
- */
 export interface PaseoAgentHandle {
     readonly id: string;
+    readonly workspaceId: string | null;
+    readonly cwd: string | null;
+    readonly status: PaseoAgent["status"] | null;
     readonly timeline: PaseoAgentTimelineHandle;
-    latest(): PaseoAgent | null;
-    refetch(requestId?: string): Promise<PaseoAgentRefetchResult | null>;
+    current(): PaseoAgent | null;
+    refresh(requestId?: string): Promise<PaseoAgentRefetchResult | null>;
     send(text: string, options?: PaseoAgentSendOptions): Promise<void>;
+    /** Sends a prompt and resolves when that turn finishes or needs attention. */
+    run(text: string, options?: PaseoAgentRunOptions): Promise<PaseoAgentRunResult>;
+    /** Waits for the current turn, including one started with `prompt`. */
+    waitForFinish(timeoutMs?: number): Promise<PaseoAgentRunResult>;
     archive(): Promise<{
         archivedAt: string;
     }>;
@@ -187,6 +206,7 @@ export interface PaseoAgentHandle {
     subscribe(handler: (update: PaseoAgentUpdate) => void): () => void;
 }
 export interface PaseoAgentActions {
+    list(options?: PaseoAgentListOptions): Promise<PaseoAgentListResult>;
     ref(agent: string | PaseoAgent): PaseoAgentHandle;
     create(options: PaseoAgentCreateOptions): Promise<PaseoAgentHandle>;
     /**
@@ -195,19 +215,13 @@ export interface PaseoAgentActions {
      */
     subscribe(handler: PaseoAgentUpdateHandler): () => void;
 }
-export interface PaseoProviderConfig extends PaseoProviderConfigInput {
-    provider: PaseoAgentProvider;
-}
-export type PaseoProviderFeatureValues = Record<string, unknown>;
-export interface PaseoProviderConfigInput {
-    model?: string;
-    modeId?: string;
-    thinkingOptionId?: string;
-    featureValues?: PaseoProviderFeatureValues;
-}
 export type PaseoProviderModelsResult = ListProviderModelsResponseMessage["payload"];
 export type PaseoProviderModesResult = ListProviderModesResponseMessage["payload"];
-export type PaseoProviderFeaturesInput = ListProviderFeaturesRequestMessage["draftConfig"];
+type PaseoProviderFeaturesDraft = ListProviderFeaturesRequestMessage["draftConfig"];
+export interface PaseoProviderFeaturesInput extends Omit<PaseoProviderFeaturesDraft, "provider" | "model"> {
+    /** Provider and model in `provider/model` format. */
+    provider: string;
+}
 export type PaseoProviderFeaturesResult = ListProviderFeaturesResponseMessage["payload"];
 export type PaseoProviderAvailabilityResult = ListAvailableProvidersResponse["payload"];
 export type PaseoProviderSnapshotResult = GetProvidersSnapshotResponseMessage["payload"];
@@ -225,12 +239,10 @@ export interface PaseoProviderRefreshOptions {
     providers?: PaseoAgentProvider[];
     requestId?: string;
 }
+export interface PaseoProviderWaitOptions extends PaseoProviderListOptions {
+    timeoutMs?: number;
+}
 export interface PaseoProviderActions {
-    codex(input?: PaseoProviderConfigInput): PaseoProviderConfig;
-    claude(input?: PaseoProviderConfigInput): PaseoProviderConfig;
-    opencode(input?: PaseoProviderConfigInput): PaseoProviderConfig;
-    copilot(input?: PaseoProviderConfigInput): PaseoProviderConfig;
-    config(provider: PaseoAgentProvider, input?: PaseoProviderConfigInput): PaseoProviderConfig;
     listModels(provider: PaseoAgentProvider, options?: PaseoProviderListOptions): Promise<PaseoProviderModelsResult>;
     listModes(provider: PaseoAgentProvider, options?: PaseoProviderListOptions): Promise<PaseoProviderModesResult>;
     listFeatures(draftConfig: PaseoProviderFeaturesInput, options?: {
@@ -240,6 +252,8 @@ export interface PaseoProviderActions {
         requestId?: string;
     }): Promise<PaseoProviderAvailabilityResult>;
     snapshot(options?: PaseoProviderListOptions): Promise<PaseoProviderSnapshotResult>;
+    /** Resolves after the daemon's lazy provider discovery has finished. */
+    waitForReady(options?: PaseoProviderWaitOptions): Promise<PaseoProviderSnapshotResult>;
     refresh(options?: PaseoProviderRefreshOptions): Promise<PaseoProviderRefreshResult>;
     diagnostic(provider: PaseoAgentProvider, options?: {
         requestId?: string;
@@ -279,4 +293,5 @@ export interface PaseoClient {
     getConnectionState(): ConnectionState;
 }
 export declare function createPaseoClient(config: PaseoClientConfig): PaseoClient;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,45 +1,73 @@
 import { DaemonClient } from "./daemon-client.js";
-export { DaemonClient };
+/**
+ * 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",
     });
-    const createWorkspaceHandle = createWorkspaceHandleFactory(daemonClient);
     const createAgentHandle = createAgentHandleFactory(daemonClient);
+    const createAgent = async (options, placement) => {
+        const { config: agentConfig, cwd, parent, title, prompt, ...requestOptions } = options;
+        const { provider: providerModel, options: providerOptions, ...runtimeConfig } = agentConfig;
+        const { provider, model } = parseProviderModel(providerModel);
+        const effectiveCwd = placement?.cwd ?? cwd;
+        const agent = await daemonClient.createAgent({
+            ...requestOptions,
+            config: {
+                ...runtimeConfig,
+                provider,
+                model,
+                cwd: effectiveCwd,
+                ...(title !== undefined ? { title } : {}),
+                ...(providerOptions !== undefined ? { providerOptions } : {}),
+            },
+            ...(placement ? { workspaceId: placement.workspaceId } : {}),
+            ...(parent ? { callerAgentId: resolveAgentId(parent) } : {}),
+            ...(prompt !== undefined ? { initialPrompt: prompt } : {}),
+        });
+        return createAgentHandle(agent);
+    };
+    const createWorkspaceHandle = createWorkspaceHandleFactory(daemonClient, createAgent);
     return {
         workspaces: {
             list: (options) => daemonClient.fetchWorkspaces(options),
             ref: (workspace) => createWorkspaceHandle(workspace),
             open: (input, requestId) => openWorkspace(daemonClient, createWorkspaceHandle, input, requestId),
-            create: (input, requestId) => openWorkspace(daemonClient, createWorkspaceHandle, input, requestId),
+            create: async ({ requestId, ...options }) => {
+                const result = await daemonClient.createWorkspace(options, 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: async (options) => {
-                const agent = await daemonClient.createAgent(options);
-                return createAgentHandle(agent);
-            },
+            create: (options) => createAgent(options),
             subscribe: (handler) => daemonClient.on("agent_update", (message) => {
                 handler(message.payload);
             }),
         },
         providers: {
-            codex: (input) => providerConfig("codex", input),
-            claude: (input) => providerConfig("claude", input),
-            opencode: (input) => providerConfig("opencode", input),
-            copilot: (input) => providerConfig("copilot", input),
-            config: (provider, input) => providerConfig(provider, input),
             listModels: (provider, options) => daemonClient.listProviderModels(provider, options),
             listModes: (provider, options) => daemonClient.listProviderModes(provider, options),
-            listFeatures: (draftConfig, options) => daemonClient.listProviderFeatures(draftConfig, 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),
             subscribe: (handler) => daemonClient.on("providers_snapshot_update", (message) => {
@@ -56,39 +84,69 @@ export function createPaseoClient(config) {
         getConnectionState: () => daemonClient.getConnectionState(),
     };
 }
-function createWorkspaceHandleFactory(daemonClient) {
+function createWorkspaceHandleFactory(daemonClient, createAgent) {
     return (workspace) => {
         const id = typeof workspace === "string" ? workspace : workspace.id;
-        let latest = typeof workspace === "string" ? null : workspace;
-        return {
-            id,
-            latest: () => latest,
-            refetch: async (options) => {
-                // Best-effort: fetches one page and matches by id client-side, so a workspace beyond
-                // the first page won't be found. TODO: add a "get workspace by id" lookup and resolve
-                // by exact id instead of paging.
+        let current = typeof workspace === "string" ? null : workspace;
+        const refresh = async (options) => {
+            let cursor;
+            let requestId = options?.requestId;
+            do {
                 const result = await daemonClient.fetchWorkspaces({
-                    requestId: options?.requestId,
-                    page: { limit: 25 },
+                    requestId,
+                    page: { limit: 200, ...(cursor ? { cursor } : {}) },
                 });
-                latest = result.entries.find((entry) => entry.id === id) ?? null;
-                return latest;
+                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 });
+                },
             },
+            current: () => current,
+            refresh,
             archive: async (requestId) => {
                 const result = await daemonClient.archiveWorkspace(id, requestId);
-                if (latest) {
-                    latest = { ...latest, archivingAt: result.archivedAt };
+                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) {
-                    latest = update.workspace;
+                    current = update.workspace;
                     handler(update);
                 }
                 if (update.kind === "remove" && update.id === id) {
-                    latest = null;
+                    current = null;
                     handler(update);
                 }
             }),
@@ -98,14 +156,14 @@ function createWorkspaceHandleFactory(daemonClient) {
 function createAgentHandleFactory(daemonClient) {
     return (agent) => {
         const id = typeof agent === "string" ? agent : agent.id;
-        let latest = typeof agent === "string" ? null : agent;
+        let current = typeof agent === "string" ? null : agent;
         const handle = {
             id,
             timeline: {
                 refetch: async (options) => {
                     const result = await daemonClient.fetchAgentTimeline(id, options);
                     if (result.agent) {
-                        latest = result.agent;
+                        current = result.agent;
                     }
                     return result;
                 },
@@ -115,19 +173,44 @@ function createAgentHandleFactory(daemonClient) {
                     }
                 }),
             },
-            latest: () => latest,
-            refetch: async (requestId) => {
+            get workspaceId() {
+                return current?.workspaceId ?? null;
+            },
+            get cwd() {
+                return current?.cwd ?? null;
+            },
+            get status() {
+                return current?.status ?? null;
+            },
+            current: () => current,
+            refresh: async (requestId) => {
                 const result = await daemonClient.fetchAgent({ agentId: id, requestId });
-                latest = result?.agent ?? null;
+                current = result?.agent ?? null;
                 return result;
             },
             send: async (text, options) => {
                 await daemonClient.sendAgentMessage(id, text, options);
             },
+            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;
+            },
             archive: async () => {
                 const result = await daemonClient.archiveAgent(id);
-                if (latest) {
-                    latest = { ...latest, archivedAt: result.archivedAt };
+                if (current) {
+                    current = { ...current, archivedAt: result.archivedAt };
                 }
                 return result;
             },
@@ -137,11 +220,11 @@ function createAgentHandleFactory(daemonClient) {
             subscribe: (handler) => daemonClient.on("agent_update", (message) => {
                 const update = message.payload;
                 if (update.kind === "upsert" && update.agent.id === id) {
-                    latest = update.agent;
+                    current = update.agent;
                     handler(update);
                 }
                 if (update.kind === "remove" && update.agentId === id) {
-                    latest = null;
+                    current = null;
                     handler(update);
                 }
             }),
@@ -152,23 +235,99 @@ function createAgentHandleFactory(daemonClient) {
 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);
-    return {
-        ...result,
-        workspace: result.workspace ? createWorkspaceHandle(result.workspace) : null,
-    };
+    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 providerConfig(provider, input = {}) {
+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,
-        ...(input.model !== undefined ? { model: input.model } : {}),
-        ...(input.modeId !== undefined ? { modeId: input.modeId } : {}),
-        ...(input.thinkingOptionId !== undefined ? { thinkingOptionId: input.thinkingOptionId } : {}),
-        ...(input.featureValues !== undefined ? { featureValues: input.featureValues } : {}),
+        provider: selection.slice(0, separator),
+        model: selection.slice(separator + 1),
     };
 }
+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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/client",
-  "version": "0.3.0",
+  "version": "0.4.0-beta.1",
   "description": "Paseo client SDK package",
   "files": [
     "dist",
@@ -39,8 +39,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@getpaseo/protocol": "0.3.0",
-    "@getpaseo/relay": "0.3.0",
+    "@getpaseo/protocol": "0.4.0-beta.1",
+    "@getpaseo/relay": "0.4.0-beta.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {