@getpaseo/client 0.2.0-beta.1 → 0.2.0-beta.2

package/dist/daemon-client.d.ts

@@ -1,7 +1,8 @@
 import type { z } from "zod";
 import { type ClientCapability } from "@getpaseo/protocol/client-capabilities";
+import type { AgentAttentionNotificationPayload } from "@getpaseo/protocol/agent-attention-notification";
 import { AgentRefreshedStatusPayloadSchema, CheckoutRenameBranchResponseSchema, RenameTerminalResponseSchema, RestartRequestedStatusPayloadSchema, ShutdownRequestedStatusPayloadSchema, DaemonUpdateResponseSchema, type ServerInfoStatusPayload } from "@getpaseo/protocol/messages";
-import type { AgentStreamEventPayload, AgentSnapshotPayload, ProjectPlacementPayload, AgentPermissionResolvedMessage, CreateAgentRequestMessage, CreatePaseoWorktreeRequest, FileDownloadTokenResponse, FileUploadResponse, FileExplorerResponse, 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, ProjectIconResponse, 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 { 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, ProjectIconResponse, 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 DaemonTransportFactory, type WebSocketFactory } from "./daemon-client-transport.js";
@@ -52,6 +53,11 @@ export type DaemonEvent = {
     payload: Extract<SessionOutboundMessage, {
         type: "workspace_update";
     }>["payload"];
+} | {
+    type: "project.update";
+    payload: Extract<SessionOutboundMessage, {
+        type: "project.update";
+    }>["payload"];
 } | {
     type: "workspace_setup_progress";
     workspaceId: string;
@@ -128,6 +134,13 @@ export interface SendMessageOptions {
     }>;
     attachments?: SendAgentMessageRequest["attachments"];
 }
+export interface AgentAttentionRequiredNotification {
+    agentId: string;
+    reason: "finished" | "error" | "permission";
+    timestamp: string;
+    shouldNotify: boolean;
+    notification?: AgentAttentionNotificationPayload;
+}
 type AgentConfigOverrides = Partial<Omit<AgentSessionConfig, "provider" | "cwd">>;
 export interface CreateAgentRequestOptions extends AgentConfigOverrides {
     config?: AgentSessionConfig;
@@ -135,6 +148,7 @@ export interface CreateAgentRequestOptions extends AgentConfigOverrides {
     cwd?: string;
     env?: CreateAgentRequestMessage["env"];
     workspaceId?: string;
+    callerAgentId?: string;
     initialPrompt?: string;
     clientMessageId?: string;
     outputSchema?: Record<string, unknown>;
@@ -196,6 +210,7 @@ export interface FileReadResult {
     path: string;
     kind: LegacyFileExplorerFilePayload["kind"];
     modifiedAt: string;
+    revision?: string;
 }
 export interface FileUploadInput {
     fileName: string;
@@ -477,9 +492,6 @@ export interface CreateScheduleOptions {
     prompt: string;
     name?: string | null;
     cadence: {
-        type: "every";
-        everyMs: number;
-    } | {
         type: "cron";
         expression: string;
         timezone?: string;
@@ -533,9 +545,6 @@ export interface UpdateScheduleOptions {
     name?: string | null;
     prompt?: string;
     cadence?: {
-        type: "every";
-        everyMs: number;
-    } | {
         type: "cron";
         expression: string;
         timezone?: string;
@@ -594,6 +603,7 @@ export declare class DaemonClient {
     private connectionState;
     private checkoutDiffSubscriptions;
     private terminalDirectorySubscriptions;
+    private fileSubscriptions;
     private readonly terminalStreams;
     private pendingBinaryFileReads;
     private activeBinaryFileTransfers;
@@ -630,6 +640,7 @@ export declare class DaemonClient {
         type: TType;
     }>) => void): () => void;
     on(handler: DaemonEventHandler): () => void;
+    onAgentAttentionRequired(handler: (notification: AgentAttentionRequiredNotification) => void): () => void;
     /**
      * Send a session message. For fire-and-forget messages (heartbeats, etc.),
      * failures are suppressed if `suppressSendErrors` is configured.
@@ -715,6 +726,7 @@ export declare class DaemonClient {
     fetchAgent(agentId: string, options?: LegacyFetchAgentOptions): Promise<FetchAgentResult | null>;
     private resubscribeCheckoutDiffSubscriptions;
     private resubscribeTerminalDirectorySubscriptions;
+    private resubscribeFileSubscriptions;
     createAgent(options: CreateAgentRequestOptions): Promise<AgentSnapshotPayload>;
     deleteAgent(agentId: string): Promise<void>;
     archiveAgent(agentId: string): Promise<{
@@ -748,6 +760,7 @@ export declare class DaemonClient {
         timeout?: number;
     }): Promise<ProviderSubagentListPayload>;
     fetchProviderSubagentTimeline(parentAgentId: string, subagentId: string, options?: FetchProviderSubagentTimelineOptions): Promise<ProviderSubagentTimelinePayload>;
+    setAgentTimelineSubscription(agentIds: string[]): Promise<void>;
     buildAgentForkContext(agentId: string, options?: AgentForkContextOptions): Promise<AgentForkContextPayload>;
     sendAgentMessage(agentId: string, text: string, options?: SendMessageOptions): Promise<void>;
     sendMessage(agentId: string, text: string, options?: SendMessageOptions): Promise<void>;
@@ -912,6 +925,20 @@ export declare class DaemonClient {
     private requestFileExplorer;
     listDirectory(cwd: string, path: string, requestId?: string): Promise<FileExplorerDirectoryPayload>;
     readFile(cwd: string, path: string, requestId?: string): Promise<FileReadResult>;
+    subscribeFile(input: {
+        cwd: string;
+        path: string;
+    }, onUpdate: (version: FileVersion) => void): Promise<{
+        initial: FileVersion;
+        unsubscribe: () => void;
+    }>;
+    writeFile(input: {
+        cwd: string;
+        path: string;
+        content: string;
+        expectedModifiedAt: string;
+        expectedRevision?: string;
+    }): Promise<FileWriteResult>;
     uploadFile(input: FileUploadInput): Promise<FileUploadResult>;
     requestDownloadToken(cwd: string, path: string, requestId?: string): Promise<FileDownloadTokenPayload>;
     requestProjectIcon(cwd: string, requestId?: string): Promise<ProjectIconResponse["payload"]>;
@@ -938,6 +965,40 @@ export declare class DaemonClient {
         config: MutableDaemonConfig;
     }>;
     getDaemonStatus(options?: DaemonStatusOptions): Promise<DaemonStatusPayload>;
+    connectHub(hubUrl: string, token: string, requestId?: string): Promise<{
+        requestId: string;
+        status: {
+            state: "connecting" | "connected" | "not_connected" | "reconnecting" | "disconnecting" | "revoked";
+            daemonId: string | null;
+            hubOrigin: string | null;
+            scopes: string[];
+            connectedAt: string | null;
+            lastError: string | null;
+        };
+    }>;
+    getHubStatus(requestId?: string): Promise<{
+        requestId: string;
+        status: {
+            state: "connecting" | "connected" | "not_connected" | "reconnecting" | "disconnecting" | "revoked";
+            daemonId: string | null;
+            hubOrigin: string | null;
+            scopes: string[];
+            connectedAt: string | null;
+            lastError: string | null;
+        };
+    }>;
+    disconnectHub(force?: boolean, requestId?: string): Promise<{
+        requestId: string;
+        status: {
+            state: "connecting" | "connected" | "not_connected" | "reconnecting" | "disconnecting" | "revoked";
+            daemonId: string | null;
+            hubOrigin: string | null;
+            scopes: string[];
+            connectedAt: string | null;
+            lastError: string | null;
+        };
+        warning?: string | undefined;
+    }>;
     getDaemonPairingOffer(options?: DaemonPairingOfferOptions): Promise<DaemonPairingOfferPayload>;
     collectDiagnostics(requestId?: string): Promise<DiagnosticsPayload>;
     patchDaemonConfig(config: MutableDaemonConfigPatch, requestId?: string): Promise<{
@@ -1028,6 +1089,7 @@ export declare class DaemonClient {
     waitForTerminalStreamEvent(predicate: (event: TerminalStreamEvent) => boolean, timeout?: number): Promise<TerminalStreamEvent>;
     private createRequestId;
     getLastServerInfoMessage(): ServerInfoStatusPayload | null;
+    private requireHubRelationshipSupport;
     private resolveTransportUrlForAttempt;
     private sendHelloMessage;
     private disposeTransport;

package/dist/daemon-client.js

@@ -158,6 +158,7 @@ function legacyExplorerFileToBytes(file) {
         path: file.path,
         kind: file.kind,
         modifiedAt: file.modifiedAt,
+        revision: file.revision,
     };
 }
 function binaryFileKind(mime, encoding) {
@@ -230,6 +231,7 @@ export class DaemonClient {
         this.connectionState = { status: "idle" };
         this.checkoutDiffSubscriptions = new Map();
         this.terminalDirectorySubscriptions = new Map();
+        this.fileSubscriptions = new Map();
         this.terminalStreams = new TerminalStreamRouter();
         this.pendingBinaryFileReads = new Map();
         this.activeBinaryFileTransfers = new Map();
@@ -478,6 +480,7 @@ export class DaemonClient {
         this.rejectPendingSendQueue(new Error("Daemon client closed"));
         this.rejectPingProbe(new Error("Daemon client closed"));
         this.terminalStreams.clearSlots();
+        this.fileSubscriptions.clear();
         this.lastServerInfoMessage = null;
         if (this.runtimeMetricsInterval) {
             clearInterval(this.runtimeMetricsInterval);
@@ -556,6 +559,28 @@ export class DaemonClient {
             }
         };
     }
+    onAgentAttentionRequired(handler) {
+        const unsubscribeLegacy = this.on("agent_stream", (message) => {
+            if (message.payload.event.type !== "attention_required") {
+                return;
+            }
+            const event = message.payload.event;
+            handler({
+                agentId: message.payload.agentId,
+                reason: event.reason,
+                timestamp: event.timestamp,
+                shouldNotify: event.shouldNotify,
+                ...(event.notification ? { notification: event.notification } : {}),
+            });
+        });
+        const unsubscribeDedicated = this.on("agent_attention_required", (message) => {
+            handler(message.payload);
+        });
+        return () => {
+            unsubscribeLegacy();
+            unsubscribeDedicated();
+        };
+    }
     // ============================================================================
     // Core Send Helpers
     // ============================================================================
@@ -1183,6 +1208,21 @@ export class DaemonClient {
             });
         }
     }
+    resubscribeFileSubscriptions() {
+        for (const [subscriptionId, subscription] of this.fileSubscriptions) {
+            void this.sendCorrelatedSessionRequest({
+                message: {
+                    type: "fs.file.subscribe.request",
+                    cwd: subscription.cwd,
+                    path: subscription.path,
+                    subscriptionId,
+                },
+                responseType: "fs.file.subscribe.response",
+            })
+                .then((payload) => subscription.onUpdate(payload.initial))
+                .catch(() => undefined);
+        }
+    }
     // ============================================================================
     // Agent Lifecycle
     // ============================================================================
@@ -1195,6 +1235,7 @@ export class DaemonClient {
             config,
             ...(options.env ? { env: options.env } : {}),
             ...(options.workspaceId !== undefined ? { workspaceId: options.workspaceId } : {}),
+            ...(options.callerAgentId !== undefined ? { callerAgentId: options.callerAgentId } : {}),
             ...(options.initialPrompt ? { initialPrompt: options.initialPrompt } : {}),
             ...(options.clientMessageId ? { clientMessageId: options.clientMessageId } : {}),
             ...(options.outputSchema ? { outputSchema: options.outputSchema } : {}),
@@ -1563,6 +1604,32 @@ export class DaemonClient {
         }
         return payload;
     }
+    async setAgentTimelineSubscription(agentIds) {
+        // COMPAT(selectiveAgentTimeline): added in v0.1.106. Old daemons keep their
+        // legacy global stream and do not understand this RPC. Remove after
+        // 2027-01-12 once the supported daemon floor is >= v0.1.106.
+        if (!this.lastServerInfoMessage?.features?.selectiveAgentTimeline) {
+            return;
+        }
+        const requestId = this.createRequestId();
+        const normalizedAgentIds = [...new Set(agentIds)].sort();
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.timeline.set_subscription.request",
+            agentIds: normalizedAgentIds,
+            requestId,
+        });
+        await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (response) => {
+                if (response.type !== "agent.timeline.set_subscription.response") {
+                    return null;
+                }
+                return response.payload.requestId === requestId ? response.payload : null;
+            },
+        });
+    }
     async buildAgentForkContext(agentId, options = {}) {
         const resolvedRequestId = this.createRequestId(options.requestId);
         const message = SessionInboundMessageSchema.parse({
@@ -2616,6 +2683,43 @@ export class DaemonClient {
             this.activeBinaryFileTransfers.delete(resolvedRequestId);
         }
     }
+    async subscribeFile(input, onUpdate) {
+        const subscriptionId = this.createRequestId();
+        this.fileSubscriptions.set(subscriptionId, { ...input, onUpdate });
+        try {
+            const payload = await this.sendCorrelatedSessionRequest({
+                message: {
+                    type: "fs.file.subscribe.request",
+                    cwd: input.cwd,
+                    path: input.path,
+                    subscriptionId,
+                },
+                responseType: "fs.file.subscribe.response",
+            });
+            return {
+                initial: payload.initial,
+                unsubscribe: () => {
+                    if (!this.fileSubscriptions.delete(subscriptionId))
+                        return;
+                    void this.sendCorrelatedSessionRequest({
+                        message: { type: "fs.file.unsubscribe.request", subscriptionId },
+                        responseType: "fs.file.unsubscribe.response",
+                    }).catch(() => undefined);
+                },
+            };
+        }
+        catch (error) {
+            this.fileSubscriptions.delete(subscriptionId);
+            throw error;
+        }
+    }
+    async writeFile(input) {
+        const payload = await this.sendCorrelatedSessionRequest({
+            message: { type: "fs.file.write.request", ...input },
+            responseType: "fs.file.write.response",
+        });
+        return payload.result;
+    }
     async uploadFile(input) {
         const bytes = asUint8Array(input.bytes);
         if (!bytes) {
@@ -2761,6 +2865,30 @@ export class DaemonClient {
             timeout: options?.timeout,
         });
     }
+    async connectHub(hubUrl, token, requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "hub.management.daemon.connect.request", hubUrl, token },
+            responseType: "hub.management.daemon.connect.response",
+        });
+    }
+    async getHubStatus(requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "hub.management.daemon.get_status.request" },
+            responseType: "hub.management.daemon.get_status.response",
+        });
+    }
+    async disconnectHub(force = false, requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "hub.management.daemon.disconnect.request", force },
+            responseType: "hub.management.daemon.disconnect.response",
+        });
+    }
     async getDaemonPairingOffer(options) {
         return this.sendCorrelatedSessionRequest({
             requestId: options?.requestId,
@@ -3449,6 +3577,12 @@ export class DaemonClient {
     getLastServerInfoMessage() {
         return this.lastServerInfoMessage;
     }
+    requireHubRelationshipSupport() {
+        // COMPAT(hubRelationship): added in v0.1.X, drop the gate when floor >= v0.1.X.
+        if (this.lastServerInfoMessage?.features?.hubRelationship !== true) {
+            throw new Error("Update the host to use Hub relationship management.");
+        }
+    }
     resolveTransportUrlForAttempt() {
         return this.config.url;
     }
@@ -3472,6 +3606,7 @@ export class DaemonClient {
                     [CLIENT_CAPS.reasoningMergeEnum]: true,
                     [CLIENT_CAPS.terminalReflowableSnapshot]: true,
                     [CLIENT_CAPS.providerSubagents]: true,
+                    [CLIENT_CAPS.projectUpdates]: true,
                     ...this.config.capabilities,
                 },
                 ...(this.config.appVersion ? { appVersion: this.config.appVersion } : {}),
@@ -3628,6 +3763,7 @@ export class DaemonClient {
                 size: frame.metadata.size,
                 encoding: frame.metadata.encoding,
                 modifiedAt: frame.metadata.modifiedAt,
+                revision: frame.metadata.revision,
                 chunks: [],
             });
             return;
@@ -3649,6 +3785,7 @@ export class DaemonClient {
             path: transfer.path,
             kind: binaryFileKind(transfer.mime, transfer.encoding),
             modifiedAt: transfer.modifiedAt,
+            revision: transfer.revision,
         });
         this.handleSessionMessage({
             type: "file_explorer_response",
@@ -3797,6 +3934,7 @@ export class DaemonClient {
                     this.startLivenessHeartbeat();
                     this.resubscribeCheckoutDiffSubscriptions();
                     this.resubscribeTerminalDirectorySubscriptions();
+                    this.resubscribeFileSubscriptions();
                     this.flushPendingSendQueue();
                     this.resolveConnect();
                 }
@@ -3805,6 +3943,11 @@ export class DaemonClient {
         if (consumerMessage.type === "terminal_stream_exit") {
             this.terminalStreams.removeTerminal(consumerMessage.payload.terminalId);
         }
+        if (consumerMessage.type === "fs.file.update") {
+            this.fileSubscriptions
+                .get(consumerMessage.payload.subscriptionId)
+                ?.onUpdate(consumerMessage.payload.version);
+        }
         if (this.rawMessageListeners.size > 0) {
             for (const handler of this.rawMessageListeners) {
                 try {
@@ -3881,6 +4024,8 @@ export class DaemonClient {
                     workspaceId: msg.payload.kind === "upsert" ? msg.payload.workspace.id : msg.payload.id,
                     payload: msg.payload,
                 };
+            case "project.update":
+                return { type: "project.update", payload: msg.payload };
             case "workspace_setup_progress":
                 return {
                     type: "workspace_setup_progress",

package/dist/index.d.ts

@@ -118,13 +118,13 @@ export interface PaseoAgentCreateOptions extends PaseoAgentConfigOverrides {
     provider?: CreateAgentRequestMessage["config"]["provider"];
     cwd?: string;
     workspaceId?: string;
+    callerAgentId?: string;
     initialPrompt?: string;
     clientMessageId?: string;
     outputSchema?: Record<string, unknown>;
     images?: CreateAgentRequestMessage["images"];
     attachments?: CreateAgentRequestMessage["attachments"];
     git?: CreateAgentRequestMessage["git"];
-    worktreeName?: string;
     requestId?: string;
     labels?: Record<string, string>;
 }

package/package.json

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