@camerontaylor/paseo-client 0.8.0-fork.3 → 0.9.0-beta.2.fork.1

package/dist/connection/index.d.ts

@@ -30,6 +30,7 @@ export declare const DEFAULT_CLIENT_CAPABILITIES: {
     terminal_reflowable_snapshot: true;
     provider_subagents: true;
     side_conversations: true;
+    projected_subagent_timeline: true;
     project_updates: true;
     compact_provider_snapshots: true;
     provider_snapshot_references: true;

package/dist/connection/index.js

@@ -103,6 +103,7 @@ export const DEFAULT_CLIENT_CAPABILITIES = {
     // 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.projectedSubagentTimeline]: true,
     [CLIENT_CAPS.projectUpdates]: true,
     [CLIENT_CAPS.compactProviderSnapshots]: true,
     [CLIENT_CAPS.providerSnapshotReferences]: true,

package/dist/creation/index.d.ts

@@ -0,0 +1,40 @@
+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: (feature: "creationLifecycle" | "agentRequestReceipts") => boolean;
+    requestId: () => string;
+    request: (kind: Kind, input: Record<string, unknown>) => Promise<CreationResult>;
+    observe: (kind: Kind, key: string, next: (snapshot: CreationSnapshot | null) => void, error: (error: unknown) => void) => () => void;
+    legacyAgent: (input: CreateAgentRequestOptions) => Promise<AgentSnapshotPayload>;
+    legacyWorkspace: (input: CreateWorkspaceRequestOptions) => Promise<WorkspaceCreateResponse["payload"]>;
+}
+/** 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;
+    reconnect(): void;
+    close(): void;
+    private finish;
+    private fail;
+    private notify;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/creation/index.js

@@ -0,0 +1,197 @@
+/** 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 sourceCwd = request.source.kind === "directory" ? request.source.path : request.source.cwd;
+            const relativeCwd = agent && sourceCwd ? relativeDirectory(agent.config.cwd, sourceCwd) : undefined;
+            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 cwd = `${workspace.workspace.workspaceDirectory.replace(/[\\/]+$/, "")}${relativeCwd ?? relativeDirectory(agent.config.cwd, workspace.workspace.projectRootPath)}`;
+            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.");
+        const { idempotencyKey: _key, ...unkeyed } = input;
+        const hasPrompt = Boolean(input.initialPrompt || input.images?.length || input.attachments?.length);
+        // COMPAT(creationLifecycle): added in v0.8.0, remove after 2027-03-11 once the daemon floor supports creationLifecycle.
+        // Preserve the original create-and-prompt RPC: old hosts use its prompt for
+        // titles, creation context and startup. Their keyed create cannot accept it.
+        const request = !hasPrompt && this.deps.supports("agentRequestReceipts") ? input : unkeyed;
+        return { agent: await this.deps.legacyAgent(request), 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("creationLifecycle"),
+            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 ||
+                (error instanceof Error && "code" in error && error.code === "DAEMON_CONNECTION_LOST"))
+                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;
+        if (operation.snapshot?.revision !== snapshot.revision) {
+            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,
+            });
+        }
+    }
+    reconnect() {
+        for (const operation of this.operations.values()) {
+            if (operation.settled || !operation.modern || operation.recovering)
+                continue;
+            operation.recovering = true;
+            operation.stopObserving = this.deps.observe(operation.kind, operation.key, (snapshot) => {
+                if (!snapshot)
+                    void this.submit(operation);
+                else {
+                    // Re-subscription is authoritative even if its revision matches the last live event.
+                    this.receive(snapshot);
+                }
+            }, (error) => 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;
+        operation.stopObserving?.();
+        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.stopObserving?.();
+        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 relativeDirectory(cwd, source) {
+    const normalize = (value) => value.replace(/\\/g, "/").replace(/\/+$/, "");
+    const normalized = normalize(cwd), root = normalize(source);
+    // Parent traversal must never survive mapping into the newly created checkout.
+    if ([normalized, root].some((path) => path.split("/").includes("..")))
+        throw new Error("Agent directory must be inside the workspace source");
+    if (normalized === root)
+        return "";
+    if (!normalized.startsWith(`${root}/`))
+        throw new Error("Agent directory must be inside the workspace source");
+    return normalized.slice(root.length);
+}
+//# sourceMappingURL=index.js.map

package/dist/daemon-client.d.ts

@@ -1,11 +1,12 @@
 import { type TimelineMessage } from "./timeline-subscription/index.js";
 import { type OwnedSubscription, type TimelineSubscription } from "./connection/index.js";
+import type { CreationSnapshot } from "@camerontaylor/paseo-protocol/messages";
 import type { z } from "zod";
 import type { SessionEventSubscription } from "@camerontaylor/paseo-protocol/messages";
 import type { ClientCapability } from "@camerontaylor/paseo-protocol/client-capabilities";
 import type { AgentAttentionNotificationPayload } from "@camerontaylor/paseo-protocol/agent-attention-notification";
 import { AgentRefreshedStatusPayloadSchema, CheckoutRenameBranchResponseSchema, RenameTerminalResponseSchema, RestartRequestedStatusPayloadSchema, ShutdownRequestedStatusPayloadSchema, DaemonUpdateResponseSchema, type ActiveTurnBehavior, type ServerInfoStatusPayload } from "@camerontaylor/paseo-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, DaemonConfigReloadResponse, DiagnosticsResponse, AgentRewindResponseMessage, ListTerminalsResponse, CreateTerminalResponse, SubscribeTerminalResponse, SubscribeTerminalRequest, CloseItemsResponse, KillTerminalResponse, CaptureTerminalResponse, TerminalInput, SessionInboundMessage, SessionOutboundMessage, SendAgentMessageRequest, PaseoConfigRaw, PaseoConfigRevision, WorkspaceCreateRequest, WorkspaceRecoveryState, PluginListItem, PluginLogEntry, PluginSourceStatusItem, PluginSourceUpdateItem, AgentSkillSelection, AgentSkillsStatus, AgentSkillsSaveResult } from "@camerontaylor/paseo-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, DaemonConfigReloadResponse, DiagnosticsResponse, AgentRewindResponseMessage, ListTerminalsResponse, CreateTerminalResponse, SubscribeTerminalResponse, SubscribeTerminalRequest, CloseItemsResponse, KillTerminalResponse, CaptureTerminalResponse, TerminalInput, SessionInboundMessage, SessionOutboundMessage, SendAgentMessageRequest, PaseoConfigRaw, PaseoConfigRevision, WorkspaceCreateRequest, WorkspaceRecoveryState, PluginListItem, PluginLogEntry, PluginSourceStatusItem, PluginSourceUpdateItem, PluginUpdateSelection, PluginUpdateProposal, PluginUpdatePreview, PluginUpdateResult, AgentSkillSelection, AgentSkillsStatus, AgentSkillsSaveResult } from "@camerontaylor/paseo-protocol/messages";
 import type { AgentPermissionRequest, AgentPermissionResponse, AgentPersistenceHandle, AgentProviderNotice, AgentProvider, AgentSessionConfig } from "@camerontaylor/paseo-protocol/agent-types";
 import type { AgentConfigApply, MutableDaemonConfig, MutableDaemonConfigPatch } from "@camerontaylor/paseo-protocol/messages";
 import { type DaemonTransportFactory, type WebSocketFactory } from "./daemon-client-transport.js";
@@ -156,6 +157,8 @@ export interface AgentAttentionRequiredNotification {
 }
 type AgentConfigOverrides = Partial<Omit<AgentSessionConfig, "provider" | "cwd">>;
 export interface CreateAgentRequestOptions extends AgentConfigOverrides {
+    agentId?: string;
+    onEvent?: (snapshot: CreationSnapshot) => void;
     config?: AgentSessionConfig;
     provider?: AgentProvider;
     cwd?: string;
@@ -175,6 +178,16 @@ export interface CreateAgentRequestOptions extends AgentConfigOverrides {
     requestId?: string;
     labels?: Record<string, string>;
 }
+export interface CreateWorkspaceRequestOptions {
+    source: WorkspaceCreateRequest["source"];
+    title?: string;
+    idempotencyKey?: string;
+    workspaceId?: string;
+    agent?: Omit<CreateAgentRequestOptions, "workspaceId" | "onEvent" | "worktree" | "git" | "worktreeName" | "idempotencyKey" | "requestId">;
+    onEvent?: (snapshot: CreationSnapshot) => void;
+    firstAgentContext?: WorkspaceCreateRequest["firstAgentContext"];
+    requestId?: string;
+}
 export interface CreatePaseoWorktreeInput extends Pick<CreatePaseoWorktreeRequest, "cwd" | "projectId" | "worktreeSlug" | "firstAgentContext" | "refName" | "action" | "checkoutSource" | "githubPrNumber"> {
 }
 type CheckoutStatusPayload = CheckoutStatusResponse["payload"];
@@ -325,6 +338,14 @@ export interface FetchAgentTimelineOptions {
     requestId?: string;
     timeout?: number;
 }
+export interface AgentTimelineSearchOptions {
+    agentId: string;
+    query: string;
+    cursor?: number;
+}
+export type AgentTimelineSearchPayload = Extract<SessionOutboundMessage, {
+    type: "agent.timeline.search.response";
+}>["payload"];
 export type AgentTimelinePromptIndexPayload = Extract<SessionOutboundMessage, {
     type: "agent.timeline.list_prompts.response";
 }>["payload"];
@@ -588,6 +609,7 @@ export declare class DaemonClient {
     private runtimeMetricsInterval;
     private runtimeMetrics;
     private pingProbe;
+    private connectionVerification;
     private livenessHeartbeatTimer;
     private lastLivenessRttMs;
     private consecutiveLivenessFailures;
@@ -597,7 +619,10 @@ export declare class DaemonClient {
     private resolveConnect;
     private rejectConnect;
     close(): Promise<void>;
-    ensureConnected(): void;
+    ensureConnected(options?: {
+        verify?: boolean;
+    }): void;
+    private verifyConnection;
     getConnectionState(): ConnectionState;
     subscribeConnectionStatus(listener: (status: ConnectionState) => void): () => void;
     get isConnected(): boolean;
@@ -770,8 +795,9 @@ export declare class DaemonClient {
     fetchAgent(options: FetchAgentOptions): Promise<FetchAgentResult | null>;
     fetchAgent(agentId: string, requestId?: string): Promise<FetchAgentResult | null>;
     fetchAgent(agentId: string, options?: LegacyFetchAgentOptions): Promise<FetchAgentResult | null>;
+    private readonly creations;
     createAgent(options: CreateAgentRequestOptions): Promise<AgentSnapshotPayload>;
-    private requireAgentRequestReceipts;
+    private createLegacyAgent;
     deleteAgent(agentId: string): Promise<void>;
     archiveAgent(agentId: string): Promise<{
         archivedAt: string;
@@ -804,6 +830,7 @@ export declare class DaemonClient {
         seq: number;
         epoch: string;
     }>;
+    searchAgentTimeline({ agentId, query, cursor, }: AgentTimelineSearchOptions): Promise<AgentTimelineSearchPayload>;
     listAgentTimelinePrompts(agentId: string, options?: {
         requestId?: string;
         timeout?: number;
@@ -965,11 +992,8 @@ export declare class DaemonClient {
         scope?: "workspace" | "worktree";
     }, requestId?: string): Promise<PaseoWorktreeArchivePayload>;
     createPaseoWorktree(input: CreatePaseoWorktreeInput, requestId?: string): Promise<CreatePaseoWorktreePayload>;
-    createWorkspace(input: {
-        source: WorkspaceCreateRequest["source"];
-        title?: string;
-        firstAgentContext?: WorkspaceCreateRequest["firstAgentContext"];
-    }, requestId?: string): Promise<WorkspaceCreatePayload>;
+    createWorkspace(input: CreateWorkspaceRequestOptions, requestId?: string): Promise<WorkspaceCreatePayload>;
+    private createLegacyWorkspace;
     validateBranch(options: {
         cwd: string;
         branchName: string;
@@ -1171,6 +1195,12 @@ export declare class DaemonClient {
         ref?: string;
     }): Promise<PluginListItem>;
     getPluginSourceStatus(pluginId?: string): Promise<PluginSourceStatusItem[]>;
+    private requirePluginUpdates;
+    previewPluginUpdates(input?: {
+        pluginId?: string;
+        target?: PluginUpdateSelection;
+    }): Promise<PluginUpdatePreview[]>;
+    applyPluginUpdates(proposals: PluginUpdateProposal[]): Promise<PluginUpdateResult[]>;
     updatePluginSources(pluginId?: string): Promise<PluginSourceUpdateItem[]>;
     inspectDirectoryPlugin(path: string): Promise<{
         id: string;

package/dist/daemon-client.js

@@ -1,8 +1,8 @@
 import { subscribeTimeline } from "./timeline-subscription/index.js";
 import { ProviderSnapshotUpdates } from "./provider-snapshots/index.js";
 import { ConnectionSubscriptions, DEFAULT_CLIENT_CAPABILITIES, } from "./connection/index.js";
+import { CreationClient } from "./creation/index.js";
 import { CLIENT_CAPS } from "@camerontaylor/paseo-protocol/client-capabilities";
-import { parsePluginSourceReference } from "@camerontaylor/paseo-protocol/plugin-source-reference";
 import { AgentCreateFailedStatusPayloadSchema, AgentCreatedStatusPayloadSchema, AgentRefreshedStatusPayloadSchema, AgentResumedStatusPayloadSchema, parseServerInfoStatusPayload, RestartRequestedStatusPayloadSchema, ShutdownRequestedStatusPayloadSchema, DaemonUpdateResponseSchema, SessionInboundMessageSchema, } from "@camerontaylor/paseo-protocol/messages";
 import { validateWSOutboundMessage } from "@camerontaylor/paseo-protocol/validation/ws-outbound";
 import { isRelayClientWebSocketUrl } from "@camerontaylor/paseo-protocol/daemon-endpoints";
@@ -289,9 +289,50 @@ export class DaemonClient {
         this.runtimeMetricsInterval = null;
         this.runtimeMetrics = null;
         this.pingProbe = null;
+        this.connectionVerification = null;
         this.livenessHeartbeatTimer = null;
         this.lastLivenessRttMs = null;
         this.consecutiveLivenessFailures = 0;
+        // ============================================================================
+        // Agent Lifecycle
+        // ============================================================================
+        this.creations = new CreationClient({
+            supports: (feature) => this.lastServerInfoMessage?.features?.[feature] === true,
+            requestId: () => this.createRequestId(),
+            request: (kind, input) => kind === "workspace"
+                ? this.sendCorrelatedSessionRequest({
+                    requestId: input.requestId,
+                    message: { ...input, type: "workspace.create.request" },
+                    responseType: "workspace.create.response",
+                    timeout: 0,
+                })
+                : this.sendCorrelatedSessionRequest({
+                    requestId: input.requestId,
+                    message: { ...input, type: "agent.create.request" },
+                    responseType: "agent.create.response",
+                    timeout: 0,
+                }),
+            observe: (kind, idempotencyKey, next, error) => {
+                const observation = this.observe("creation.subscribe.response", {
+                    type: "creation.subscribe.request",
+                    kind,
+                    idempotencyKey,
+                });
+                observation.subscribe({
+                    snapshot: (result) => next(result.snapshot),
+                    update: (message) => {
+                        if (message.type === "workspace.create.update" || message.type === "agent.create.update")
+                            next(message.payload);
+                    },
+                    error,
+                });
+                return () => {
+                    void observation.release().catch(error);
+                };
+            },
+            legacyAgent: (input) => this.createLegacyAgent(input),
+            legacyWorkspace: (input) => this.createLegacyWorkspace(input, input.requestId),
+        });
         this.logger = config.logger ?? consoleLogger;
         this.logConnectionPath = isRelayClientWebSocketUrl(this.config.url) ? "relay" : "direct";
         let parsedUrlForLog = null;
@@ -364,6 +405,12 @@ export class DaemonClient {
         if (this.connectionState.status === "connecting") {
             return;
         }
+        // This attempt supersedes any retry the last disconnect scheduled. Left
+        // armed, that retry would tear down the connection this attempt opens.
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
         const headers = {};
         const password = normalizePassword(this.config.password);
         if (password) {
@@ -530,6 +577,7 @@ export class DaemonClient {
         this.providerSnapshotUpdates.clear();
         this.clearWaiters(new Error("Daemon client closed"));
         await this.owned.close();
+        this.creations.close();
         this.rejectPendingSendQueue(new Error("Daemon client closed"));
         this.rejectPingProbe(new Error("Daemon client closed"));
         this.terminalStreams.clearSlots();
@@ -542,27 +590,50 @@ export class DaemonClient {
         }
         this.updateConnectionState({ status: "disposed" }, { event: "DISPOSE", reason: "Client closed", reasonCode: "disposed" });
     }
-    ensureConnected() {
+    ensureConnected(options) {
         if (this.connectionState.status === "disposed") {
             return;
         }
         if (!this.shouldReconnect) {
             this.shouldReconnect = true;
         }
-        if (this.connectionState.status === "connected" ||
-            this.connectionState.status === "connecting") {
+        if (this.connectionState.status === "connected") {
+            if (options?.verify)
+                this.verifyConnection();
             return;
         }
-        if (this.reconnectTimeout) {
-            clearTimeout(this.reconnectTimeout);
-            this.reconnectTimeout = null;
-        }
+        if (this.connectionState.status === "connecting")
+            return;
         if (this.connectPromise) {
             this.attemptConnect();
             return;
         }
         void this.connect();
     }
+    verifyConnection() {
+        const transport = this.transport;
+        if (!transport || this.connectionVerification === transport)
+            return;
+        this.connectionVerification = transport;
+        // A session probe has its own deadline, independent of a heartbeat that the OS
+        // may have suspended. A successful response also proves the session can serve RPCs.
+        void this.ping({ timeoutMs: 3000 })
+            .catch((error) => {
+            if (this.transport !== transport || this.connectionState.status !== "connected")
+                return;
+            this.disposeTransport(1001, "Connection verification failed");
+            this.scheduleReconnect({
+                reason: error instanceof Error ? error.message : String(error),
+                event: "CONNECTION_VERIFICATION_FAILED",
+                reasonCode: "liveness_timeout",
+            });
+            this.ensureConnected();
+        })
+            .finally(() => {
+            if (this.connectionVerification === transport)
+                this.connectionVerification = null;
+        });
+    }
     getConnectionState() {
         return this.connectionState;
     }
@@ -1479,12 +1550,16 @@ export class DaemonClient {
         }
         return { agent: payload.agent, project: payload.project ?? null };
     }
-    // ============================================================================
-    // Agent Lifecycle
-    // ============================================================================
     async createAgent(options) {
-        if (options.idempotencyKey !== undefined)
-            this.requireAgentRequestReceipts();
+        const result = await this.creations.createAgent({
+            ...options,
+            config: resolveAgentConfig(options),
+        });
+        if (result.error || !result.agent)
+            throw new Error(result.error ?? "Agent creation failed");
+        return result.agent;
+    }
+    async createLegacyAgent(options) {
         const requestId = this.createRequestId(options.requestId);
         const config = resolveAgentConfig(options);
         const message = SessionInboundMessageSchema.parse({
@@ -1534,12 +1609,6 @@ export class DaemonClient {
         }
         return status.agent;
     }
-    requireAgentRequestReceipts() {
-        // COMPAT(agentRequestReceipts): added in v0.7.3; remove gate after 2027-03-05.
-        if (this.lastServerInfoMessage?.features?.agentRequestReceipts !== true) {
-            throw new Error("Update the host to use retry-safe agent creation.");
-        }
-    }
     async deleteAgent(agentId) {
         const requestId = this.createRequestId();
         const message = SessionInboundMessageSchema.parse({
@@ -1839,6 +1908,17 @@ export class DaemonClient {
         });
         return { seq: payload.seq, epoch: payload.epoch };
     }
+    async searchAgentTimeline({ agentId, query, cursor, }) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "agent.timeline.search.request", requestId, agentId, query, cursor },
+            responseType: "agent.timeline.search.response",
+        });
+        if (payload.error)
+            throw new Error(payload.error);
+        return payload;
+    }
     async listAgentTimelinePrompts(agentId, options = {}) {
         const requestId = this.createRequestId(options.requestId);
         const message = SessionInboundMessageSchema.parse({
@@ -1884,6 +1964,10 @@ export class DaemonClient {
         return payload;
     }
     async fetchProviderSubagentTimeline(parentAgentId, subagentId, options = {}) {
+        // COMPAT(projectedSubagentTimeline): added after v0.8.0, remove after 2027-03-14.
+        if (this.lastServerInfoMessage?.features?.projectedSubagentTimeline !== true) {
+            throw new Error("Update the host to view subagent conversations.");
+        }
         const requestId = this.createRequestId(options.requestId);
         const message = SessionInboundMessageSchema.parse({
             type: "agent.provider_subagents.timeline.get.request",
@@ -2892,11 +2976,33 @@ export class DaemonClient {
         });
     }
     async createWorkspace(input, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId ?? input.requestId);
+        const result = await this.creations.createWorkspace({
+            ...input,
+            requestId: resolvedRequestId,
+            ...(input.agent
+                ? { agent: { ...input.agent, config: resolveAgentConfig(input.agent) } }
+                : {}),
+        });
+        return {
+            ...result,
+            workspace: result.workspace ?? null,
+            agent: result.agent ?? undefined,
+            setupTerminalId: result.setupTerminalId ?? null,
+            requestId: result.requestId ?? resolvedRequestId,
+        };
+    }
+    async createLegacyWorkspace(input, requestId) {
         return this.sendCorrelatedSessionRequest({
             requestId,
             message: {
                 type: "workspace.create.request",
                 source: input.source,
+                // COMPAT(workspaceRequestReceipts): added in v0.8.0; remove after 2027-03-15 once the daemon floor supports workspace receipts.
+                ...(this.lastServerInfoMessage?.features?.workspaceRequestReceipts &&
+                    input.idempotencyKey !== undefined
+                    ? { idempotencyKey: input.idempotencyKey }
+                    : {}),
                 ...(input.title !== undefined ? { title: input.title } : {}),
                 ...(input.firstAgentContext !== undefined
                     ? { firstAgentContext: input.firstAgentContext }
@@ -3080,6 +3186,7 @@ export class DaemonClient {
         if (!bytes) {
             throw new Error("File bytes are required.");
         }
+        const uploadTransport = this.transport;
         const resolvedRequestId = this.createRequestId(input.requestId);
         const modifiedAt = input.modifiedAt ?? new Date().toISOString();
         const responsePromise = this.sendCorrelatedRequest({
@@ -3095,29 +3202,51 @@ export class DaemonClient {
             responseType: "file.upload.response",
             options: { skipQueue: true },
         });
-        this.sendBinaryFrame(encodeFileTransferFrame({
-            opcode: FileTransferOpcode.FileBegin,
-            requestId: resolvedRequestId,
-            metadata: {
-                mime: input.mimeType,
-                size: bytes.byteLength,
-                encoding: "binary",
-                modifiedAt,
-                fileName: input.fileName,
-            },
-        }));
-        const chunkSize = input.chunkSize ?? 1024 * 1024;
-        for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+        let settled = false;
+        void responsePromise.then(() => {
+            settled = true;
+            return undefined;
+        }, () => {
+            settled = true;
+            return undefined;
+        });
+        try {
+            this.sendBinaryFrame(encodeFileTransferFrame({
+                opcode: FileTransferOpcode.FileBegin,
+                requestId: resolvedRequestId,
+                metadata: {
+                    mime: input.mimeType,
+                    size: bytes.byteLength,
+                    encoding: "binary",
+                    modifiedAt,
+                    fileName: input.fileName,
+                },
+            }));
+            const chunkSize = input.chunkSize ?? 128 * 1024;
+            for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+                // Native WebSocket.send encodes binary synchronously. Let rendering and
+                // incoming messages run between bounded pieces on every platform.
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                if (settled)
+                    return await responsePromise;
+                if (this.transport !== uploadTransport || this.connectionState.status !== "connected") {
+                    throw new DaemonConnectionError("Connection changed during file upload");
+                }
+                this.sendBinaryFrame(encodeFileTransferFrame({
+                    opcode: FileTransferOpcode.FileChunk,
+                    requestId: resolvedRequestId,
+                    payload: bytes.subarray(offset, Math.min(offset + chunkSize, bytes.byteLength)),
+                }));
+            }
             this.sendBinaryFrame(encodeFileTransferFrame({
-                opcode: FileTransferOpcode.FileChunk,
+                opcode: FileTransferOpcode.FileEnd,
                 requestId: resolvedRequestId,
-                payload: bytes.subarray(offset, Math.min(offset + chunkSize, bytes.byteLength)),
             }));
         }
-        this.sendBinaryFrame(encodeFileTransferFrame({
-            opcode: FileTransferOpcode.FileEnd,
-            requestId: resolvedRequestId,
-        }));
+        catch (error) {
+            this.rejectWaitersForRequestId(resolvedRequestId, error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
         return responsePromise;
     }
     async requestDownloadToken(cwd, path, requestId) {
@@ -3467,18 +3596,21 @@ export class DaemonClient {
     }
     async installPluginSource(input) {
         const requestId = this.createRequestId();
-        const reference = parsePluginSourceReference(input.source);
+        // COMPAT(pluginSourceInstallation): added in v0.8.0; remove after 2027-03-16 once daemon floor supports source identifiers.
+        if (this.getLastServerInfoMessage()?.features?.pluginSourceInstallation !== true) {
+            throw new Error("Update the host to install plugin sources.");
+        }
         const payload = await this.sendCorrelatedSessionRequest({
             requestId,
             message: {
                 type: "plugin.source.install.request",
                 requestId,
-                source: reference.source,
-                ...(reference.pluginPath ? { pluginPath: reference.pluginPath } : {}),
+                source: input.source,
                 ...(input.id ? { id: input.id } : {}),
                 ...(input.ref ? { ref: input.ref } : {}),
             },
             responseType: "plugin.source.install.response",
+            timeout: 5 * 60 * 1000,
         });
         return payload.plugin;
     }
@@ -3495,6 +3627,33 @@ export class DaemonClient {
         });
         return payload.plugins;
     }
+    requirePluginUpdates() {
+        // COMPAT(pluginSourceUpdates): added in v0.8.0; remove after 2027-03-16 once daemon floor supports reviewed updates.
+        if (this.getLastServerInfoMessage()?.features?.pluginSourceUpdates !== true)
+            throw new Error("Update the host to review plugin updates.");
+    }
+    async previewPluginUpdates(input = {}) {
+        this.requirePluginUpdates();
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.source.update.preview.request", requestId, ...input },
+            responseType: "plugin.source.update.preview.response",
+            timeout: 300000,
+        });
+        return payload.plugins;
+    }
+    async applyPluginUpdates(proposals) {
+        this.requirePluginUpdates();
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.source.update.apply.request", requestId, proposals },
+            responseType: "plugin.source.update.apply.response",
+            timeout: 300000,
+        });
+        return payload.plugins;
+    }
     async updatePluginSources(pluginId) {
         const requestId = this.createRequestId();
         const payload = await this.sendCorrelatedSessionRequest({
@@ -4437,6 +4596,7 @@ export class DaemonClient {
                         ...DEFAULT_CLIENT_CAPABILITIES,
                         ...this.config.capabilities,
                     });
+                    this.creations.reconnect();
                     this.flushPendingSendQueue();
                     this.resolveConnect();
                 }
@@ -4469,6 +4629,11 @@ export class DaemonClient {
                 handler(event);
             }
         }
+        if (consumerMessage.type === "workspace.create.update" ||
+            consumerMessage.type === "agent.create.update") {
+            if (!consumerMessage.payload.subscriptionId)
+                this.creations.receive(consumerMessage.payload);
+        }
         this.resolveWaiters(consumerMessage);
         this.owned.receive(consumerMessage);
     }
@@ -4631,7 +4796,7 @@ export class DaemonClient {
     }
 }
 function resolveAgentConfig(options) {
-    const { config, provider, cwd, env: _env, workspaceId: _workspaceId, initialPrompt: _initialPrompt, images: _images, git: _git, worktreeName: _worktreeName, requestId: _requestId, labels: _labels, ...overrides } = options;
+    const { config, provider, cwd, agentId: _agentId, onEvent: _onEvent, idempotencyKey: _idempotencyKey, clientMessageId: _clientMessageId, callerAgentId: _callerAgentId, outputSchema: _outputSchema, attachments: _attachments, worktree: _worktree, autoArchive: _autoArchive, env: _env, workspaceId: _workspaceId, initialPrompt: _initialPrompt, images: _images, git: _git, worktreeName: _worktreeName, requestId: _requestId, labels: _labels, ...overrides } = options;
     const baseConfig = {
         ...(provider ? { provider } : {}),
         ...(cwd ? { cwd } : {}),

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { OwnedSubscription } from "./connection/index.js";
 export type { OwnedSubscription, SubscriptionObserver } from "./connection/index.js";
 import type { DaemonClientConfig } from "./daemon-client.js";
 import type { AgentPermissionResponse } from "@camerontaylor/paseo-protocol/agent-types";
-import type { AgentSnapshotPayload, CreateAgentRequestMessage, FetchWorkspacesRequestMessage, FetchWorkspacesResponseMessage, GetProvidersSnapshotResponseMessage, ListAvailableProvidersResponse, ListCommandsResponse, ListProviderFeaturesRequestMessage, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ProjectListRequestMessage, ProjectListResponseMessage, ListProviderModesResponseMessage, MutableDaemonConfig, MutableDaemonConfigPatch, ProviderDiagnosticResponseMessage, ProviderUsageListResponseMessage, ProjectPlacementPayload, WorkspaceProjectDescriptorPayload, RefreshProvidersSnapshotResponseMessage, SendAgentMessageRequest, SessionOutboundMessage, WorkspaceDescriptorPayload, WorkspaceCreateRequest } from "@camerontaylor/paseo-protocol/messages";
+import type { AgentSnapshotPayload, CreationSnapshot, CreateAgentRequestMessage, FetchWorkspacesRequestMessage, FetchWorkspacesResponseMessage, GetProvidersSnapshotResponseMessage, ListAvailableProvidersResponse, ListCommandsResponse, ListProviderFeaturesRequestMessage, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ProjectListRequestMessage, ProjectListResponseMessage, ListProviderModesResponseMessage, MutableDaemonConfig, MutableDaemonConfigPatch, ProviderDiagnosticResponseMessage, ProviderUsageListResponseMessage, ProjectPlacementPayload, WorkspaceProjectDescriptorPayload, RefreshProvidersSnapshotResponseMessage, SendAgentMessageRequest, SessionOutboundMessage, WorkspaceDescriptorPayload, WorkspaceCreateRequest } from "@camerontaylor/paseo-protocol/messages";
 import { DaemonClient } from "./daemon-client.js";
 import { type PaseoTerminalActions, type PaseoWorkspaceTerminalActions } from "./terminals/index.js";
 export type { PaseoTerminal, PaseoTerminalActions, PaseoTerminalHandle, PaseoTerminalCreateOptions, PaseoTerminalListOptions, PaseoTerminalListResult, PaseoTerminalCaptureOptions, PaseoTerminalCaptureResult, PaseoWorkspaceTerminalActions, } from "./terminals/index.js";
@@ -83,8 +83,10 @@ export interface PaseoWorkspaceOpenOptions {
     cwd: string;
     requestId?: string;
 }
-export type PaseoWorkspaceCreateOptions = Omit<WorkspaceCreateRequest, "type" | "requestId"> & {
+export type PaseoWorkspaceCreateOptions = Omit<WorkspaceCreateRequest, "type" | "requestId" | "agent" | "subscribe"> & {
     requestId?: string;
+    agent?: Omit<PaseoAgentCreateOptions, "worktree" | "git" | "onEvent" | "idempotencyKey" | "requestId">;
+    onEvent?: (snapshot: CreationSnapshot) => void;
 };
 export interface PaseoWorkspaceArchiveResult {
     requestId: string;
@@ -160,6 +162,9 @@ export interface PaseoAgentConfig {
     mcpServers?: PaseoAgentSessionConfig["mcpServers"];
 }
 export interface PaseoAgentCreateOptions {
+    idempotencyKey?: string;
+    agentId?: string;
+    onEvent?: (snapshot: CreationSnapshot) => void;
     config: PaseoAgentConfig;
     cwd: string;
     parent?: string | PaseoAgentHandle;

package/dist/index.js

@@ -27,6 +27,25 @@ export function createPaseoClient(config) {
         getConnectionState: () => daemonClient.getConnectionState(),
     };
 }
+function toDaemonAgentCreateOptions(options, placement) {
+    const { config: agentConfig, cwd, parent, title, prompt, ...requestOptions } = options;
+    const { provider: providerModel, options: providerOptions, ...runtimeConfig } = agentConfig;
+    const { provider, model } = parseProviderModel(providerModel);
+    return {
+        ...requestOptions,
+        config: {
+            ...runtimeConfig,
+            provider,
+            model,
+            cwd: placement?.cwd ?? cwd,
+            ...(title !== undefined ? { title } : {}),
+            ...(providerOptions !== undefined ? { providerOptions } : {}),
+        },
+        ...(placement ? { workspaceId: placement.workspaceId } : {}),
+        ...(parent ? { callerAgentId: resolveAgentId(parent) } : {}),
+        ...(prompt !== undefined ? { initialPrompt: prompt } : {}),
+    };
+}
 export function createPaseoApi(daemonClient, scopeOptions) {
     const handles = new Set();
     const agentListeners = new Set();
@@ -62,24 +81,7 @@ export function createPaseoApi(daemonClient, scopeOptions) {
     };
     const createAgentHandle = createAgentHandleFactory(daemonClient, listenAgents, (agentId, handler) => own(() => daemonClient.subscribeAgentTimeline(agentId, handler)));
     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 } : {}),
-        });
+        const agent = await daemonClient.createAgent(toDaemonAgentCreateOptions(options, placement));
         return createAgentHandle(agent);
     };
     const terminals = createTerminalActions(daemonClient, async (workspaceId) => {
@@ -173,8 +175,8 @@ export function createPaseoApi(daemonClient, scopeOptions) {
             list: listWorkspaces,
             ref: (workspace) => createWorkspaceHandle(workspace),
             open: (input, requestId) => openWorkspace(daemonClient, createWorkspaceHandle, input, requestId),
-            create: async ({ requestId, ...options }) => {
-                const result = await daemonClient.createWorkspace(options, requestId);
+            create: async ({ requestId, agent, ...options }) => {
+                const result = await daemonClient.createWorkspace({ ...options, ...(agent ? { agent: toDaemonAgentCreateOptions(agent) } : {}) }, requestId);
                 if (result.error || !result.workspace) {
                     throw new Error(result.error ?? "The daemon did not create a workspace");
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camerontaylor/paseo-client",
-  "version": "0.8.0-fork.3",
+  "version": "0.9.0-beta.2.fork.1",
   "description": "Paseo client SDK package",
   "files": [
     "dist",
@@ -39,8 +39,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@camerontaylor/paseo-protocol": "0.8.0-fork.3",
-    "@camerontaylor/paseo-relay": "0.8.0-fork.3",
+    "@camerontaylor/paseo-protocol": "0.9.0-beta.2.fork.1",
+    "@camerontaylor/paseo-relay": "0.9.0-beta.2.fork.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {