@hyperdrive.bot/fleet-client 0.3.218 → 0.3.221

package/dist/index.d.ts

@@ -1,6 +1,13 @@
-import type { AgentSnapshotPayload, CreateAgentRequestMessage, FetchWorkspacesRequestMessage, FetchWorkspacesResponseMessage, GetProvidersSnapshotResponseMessage, ListAvailableProvidersResponse, ListProviderFeaturesRequestMessage, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ListProviderModesResponseMessage, MutableDaemonConfig, MutableDaemonConfigPatch, ProviderDiagnosticResponseMessage, ProjectPlacementPayload, RefreshProvidersSnapshotResponseMessage, SendAgentMessageRequest, ProvidersReloadConfigPayload, SessionOutboundMessage, WorkspaceDescriptorPayload } from "@hyperdrive.bot/fleet-protocol/messages";
+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 "@hyperdrive.bot/fleet-protocol/agent-types";
+import type { AgentSnapshotPayload, CreationSnapshot, CreateAgentRequestMessage, FetchWorkspacesRequestMessage, FetchWorkspacesResponseMessage, GetProvidersSnapshotResponseMessage, ListAvailableProvidersResponse, ListCommandsResponse, ListProviderFeaturesRequestMessage, ListProviderFeaturesResponseMessage, ListProviderModelsResponseMessage, ProjectListRequestMessage, ProjectListResponseMessage, ListProviderModesResponseMessage, MutableDaemonConfig, MutableDaemonConfigPatch, ProviderDiagnosticResponseMessage, ProviderUsageListResponseMessage, ProjectPlacementPayload, WorkspaceProjectDescriptorPayload, RefreshProvidersSnapshotResponseMessage, ProvidersReloadConfigPayload, SessionOutboundMessage, WorkspaceDescriptorPayload, WorkspaceCreateRequest } from "@hyperdrive.bot/fleet-protocol/messages";
 import { DaemonClient } from "./daemon-client.js";
-import type { FetchAgentTimelineCursor, FetchAgentTimelineDirection, FetchAgentTimelinePayload, FetchAgentTimelineProjection } 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";
+import type { PluginTimelineItem } from "@hyperdrive.bot/fleet-protocol/agent-types";
+import type { FetchAgentsEntry, FetchAgentsOptions, FetchAgentsPageInfo, FetchAgentTimelineCursor, FetchAgentTimelineDirection, FetchAgentTimelinePayload, FetchAgentTimelineProjection, SendMessageOptions, WaitForFinishResult } from "./daemon-client.js";
 export { DaemonClient };
 export { DirectorySuggestionsSupersededError, UploadCancelledError, UploadCapExceededError, UploadFailedError, } from "./daemon-client.js";
 export type { DaemonClientConfig, DaemonEvent, DaemonRequestCompletion, BrowserAutomationExecuteRequestMessage, BrowserAutomationExecuteResponseMessage, WebSocketFactory, WebSocketLike, } from "./daemon-client.js";
@@ -24,6 +31,7 @@ export interface PaseoLogger {
     error(obj: object, msg?: string): void;
 }
 export interface PaseoClientConfig {
+    capabilities?: DaemonClientConfig["capabilities"];
     url: string;
     clientId?: string;
     appVersion?: string;
@@ -47,10 +55,28 @@ export interface PaseoClientConfig {
 }
 export type PaseoWorkspace = WorkspaceDescriptorPayload;
 export type PaseoAgent = AgentSnapshotPayload;
+export type PaseoAgentListOptions = FetchAgentsOptions;
+export type PaseoProject = WorkspaceProjectDescriptorPayload;
+export type PaseoProjectListOptions = Omit<ProjectListRequestMessage, "type" | "requestId"> & {
+    requestId?: string;
+};
+export type PaseoProjectListResult = ProjectListResponseMessage["payload"];
+export type PaseoProjectUpdate = Extract<SessionOutboundMessage, {
+    type: "project.update";
+}>["payload"];
+export type PaseoProjectUpdateHandler = (update: PaseoProjectUpdate) => void;
+export interface PaseoAgentListResult {
+    subscription?: OwnedSubscription<PaseoAgentListResult>;
+    requestId: string;
+    subscriptionId?: string | null;
+    entries: FetchAgentsEntry[];
+    pageInfo: FetchAgentsPageInfo;
+}
 export type PaseoWorkspaceListOptions = Omit<FetchWorkspacesRequestMessage, "type" | "requestId"> & {
     requestId?: string;
 };
 export interface PaseoWorkspaceListResult {
+    subscription?: OwnedSubscription<PaseoWorkspaceListResult>;
     requestId: string;
     subscriptionId?: string | null;
     entries: PaseoWorkspace[];
@@ -60,11 +86,11 @@ 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" | "agent" | "subscribe"> & {
+    requestId?: string;
+    agent?: Omit<PaseoAgentCreateOptions, "worktree" | "git" | "onEvent" | "idempotencyKey" | "requestId">;
+    onEvent?: (snapshot: CreationSnapshot) => void;
+};
 export interface PaseoWorkspaceArchiveResult {
     requestId: string;
     workspaceId: string;
@@ -75,21 +101,23 @@ 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>;
+    };
+    readonly terminals: PaseoWorkspaceTerminalActions;
+    current(): PaseoWorkspace | null;
+    refresh(options?: {
         requestId?: string;
     }): Promise<PaseoWorkspace | null>;
+    setTitle(title: string | null, requestId?: string): Promise<{
+        title: string | null;
+    }>;
     archive(requestId?: string): Promise<PaseoWorkspaceArchiveResult>;
     /**
      * Subscribes to already-emitted daemon workspace_update events for this id.
@@ -99,11 +127,21 @@ export interface PaseoWorkspaceHandle {
      */
     subscribe(handler: (update: PaseoWorkspaceUpdate) => void): () => void;
 }
+export interface PaseoProjectActions {
+    list(options?: PaseoProjectListOptions): Promise<PaseoProjectListResult>;
+    subscribe(handler: PaseoProjectUpdateHandler): () => void;
+}
 export interface PaseoWorkspaceActions {
+    list(options: PaseoWorkspaceListOptions & {
+        subscribe: {};
+    }): Promise<PaseoWorkspaceListResult & {
+        subscriptionId: string;
+        subscription: OwnedSubscription<PaseoWorkspaceListResult>;
+    }>;
     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 +150,41 @@ 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;
-    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 {
+    idempotencyKey?: string;
+    agentId?: string;
+    onEvent?: (snapshot: CreationSnapshot) => void;
+    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"];
-    worktreeName?: string;
+    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;
@@ -140,14 +196,20 @@ export interface PaseoAgentTimelineRefetchOptions {
     projection?: FetchAgentTimelineProjection;
     requestId?: string;
 }
-export interface PaseoAgentSendOptions {
-    messageId?: string;
-    images?: Array<{
-        data: string;
-        mimeType: string;
-    }>;
-    attachments?: SendAgentMessageRequest["attachments"];
+export type PaseoAgentSendOptions = SendMessageOptions;
+export interface PaseoAgentRunOptions extends PaseoAgentSendOptions {
+    timeoutMs?: number;
+}
+export type PaseoAgentRunResult = WaitForFinishResult;
+export type PaseoAgentPermissionResponse = AgentPermissionResponse;
+export interface PaseoAgentRespondToPermissionOptions {
+    requestId: string;
+    response: PaseoAgentPermissionResponse;
+}
+export interface PaseoAgentCommandsOptions {
+    requestId?: string;
 }
+export type PaseoAgentCommandsResult = ListCommandsResponse["payload"];
 export type PaseoAgentUpdate = Extract<SessionOutboundMessage, {
     type: "agent_update";
 }>["payload"];
@@ -155,31 +217,85 @@ export type PaseoAgentStream = Extract<SessionOutboundMessage, {
     type: "agent_stream";
 }>["payload"];
 export type PaseoAgentUpdateHandler = (update: PaseoAgentUpdate) => void;
+export type PaseoAgentTimelineEvent = PaseoAgentStream | {
+    agentId: string;
+    event: {
+        type: "replacement";
+        epoch: string;
+    };
+} | {
+    agentId: string;
+    subscriptionId: string;
+    event: {
+        type: "subscription_restored";
+    };
+} | {
+    agentId: string;
+    event: {
+        type: "error";
+        error: string;
+    };
+};
+export type PaseoAgentTimelineSubscription = ReturnType<DaemonClient["subscribeAgentTimeline"]>;
 export interface PaseoAgentTimelineHandle {
+    append(item: Omit<PluginTimelineItem, "pluginId">): Promise<{
+        seq: number;
+        epoch: string;
+    }>;
     /**
      * 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>;
     /**
-     * Local listener for agent_stream events matching this handle id. It does not
-     * retain timeline entries or own application cache state.
+     * Delivers live events only. After reconnect, subscription_restored precedes
+     * subsequent updates. History may have been missed; use refetch() to request
+     * the range you need. No history is fetched automatically. A replacement event
+     * invalidates the previous epoch. Subscription errors release this observation.
+     * Await the returned unsubscribe function's `ready` promise before starting
+     * work that must be observed. It rejects if establishment fails.
      */
-    subscribe(handler: (event: PaseoAgentStream) => void): () => void;
+    subscribe(handler: (event: PaseoAgentTimelineEvent) => void): PaseoAgentTimelineSubscription;
 }
-/**
- * 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;
+    /**
+     * `workspaceId` through `archivedAt` mirror the last snapshot this handle
+     * observed. A handle from `ref()` reads `null` for all of them until
+     * `refresh()`, `run()`, `waitForFinish()`, a timeline refetch, or
+     * `subscribe()` delivers a snapshot. Optional snapshot values also read as
+     * `null`; use `current()` when you need to distinguish those states.
+     */
+    readonly workspaceId: string | null;
+    readonly cwd: string | null;
+    readonly status: PaseoAgent["status"] | null;
+    readonly capabilities: PaseoAgent["capabilities"] | null;
+    readonly availableModes: PaseoAgent["availableModes"] | null;
+    readonly pendingPermissions: PaseoAgent["pendingPermissions"] | null;
+    readonly activeTurn: NonNullable<PaseoAgent["activeTurn"]> | null;
+    readonly lastUsage: NonNullable<PaseoAgent["lastUsage"]> | null;
+    readonly lastError: NonNullable<PaseoAgent["lastError"]> | null;
+    readonly features: NonNullable<PaseoAgent["features"]> | null;
+    readonly runtimeInfo: NonNullable<PaseoAgent["runtimeInfo"]> | null;
+    readonly archivedAt: NonNullable<PaseoAgent["archivedAt"]> | 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>;
+    respondToPermission(options: PaseoAgentRespondToPermissionOptions): 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>;
+    /**
+     * Asks the running session for the slash commands and skills it actually
+     * loaded. Providers answer from the live session, so this sees built-in and
+     * bundled entries that no directory scan can find. The payload carries its own
+     * `error` string; a provider that cannot answer reports it there rather than
+     * rejecting.
+     */
+    commands(options?: PaseoAgentCommandsOptions): Promise<PaseoAgentCommandsResult>;
     archive(): Promise<{
         archivedAt: string;
     }>;
@@ -187,6 +303,13 @@ export interface PaseoAgentHandle {
     subscribe(handler: (update: PaseoAgentUpdate) => void): () => void;
 }
 export interface PaseoAgentActions {
+    list(options: PaseoAgentListOptions & {
+        subscribe: {};
+    }): Promise<PaseoAgentListResult & {
+        subscriptionId: string;
+        subscription: OwnedSubscription<PaseoAgentListResult>;
+    }>;
+    list(options?: PaseoAgentListOptions): Promise<PaseoAgentListResult>;
     ref(agent: string | PaseoAgent): PaseoAgentHandle;
     create(options: PaseoAgentCreateOptions): Promise<PaseoAgentHandle>;
     /**
@@ -195,19 +318,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"];
@@ -216,6 +333,10 @@ export type PaseoProviderSnapshotUpdate = Extract<SessionOutboundMessage, {
 }>["payload"];
 export type PaseoProviderRefreshResult = RefreshProvidersSnapshotResponseMessage["payload"];
 export type PaseoProviderDiagnosticResult = ProviderDiagnosticResponseMessage["payload"];
+export type PaseoProviderUsageResult = ProviderUsageListResponseMessage["payload"];
+export interface PaseoProviderUsageOptions {
+    requestId?: string;
+}
 export interface PaseoProviderListOptions {
     cwd?: string;
     requestId?: string;
@@ -225,12 +346,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 +359,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>;
     /**
      * Re-read `agents.providers` from the daemon's config.json into its live
@@ -253,6 +374,7 @@ export interface PaseoProviderActions {
     diagnostic(provider: PaseoAgentProvider, options?: {
         requestId?: string;
     }): Promise<PaseoProviderDiagnosticResult>;
+    listUsage(options?: PaseoProviderUsageOptions): Promise<PaseoProviderUsageResult>;
     subscribe(handler: (update: PaseoProviderSnapshotUpdate) => void): () => void;
 }
 export interface PaseoConfigActions {
@@ -277,15 +399,24 @@ export interface PaseoConfigActions {
         config: MutableDaemonConfig;
     }>;
 }
-export interface PaseoClient {
+export interface PaseoApi {
+    dispose(): Promise<void>;
+    observeEvents: DaemonClient["observeEvents"];
+    readonly terminals: PaseoTerminalActions;
     readonly workspaces: PaseoWorkspaceActions;
+    readonly projects: PaseoProjectActions;
     readonly agents: PaseoAgentActions;
     readonly providers: PaseoProviderActions;
     readonly config: PaseoConfigActions;
+}
+export interface PaseoClient extends PaseoApi {
     connect(): Promise<void>;
     close(): Promise<void>;
     ensureConnected(): void;
     getConnectionState(): ConnectionState;
 }
 export declare function createPaseoClient(config: PaseoClientConfig): PaseoClient;
+export declare function createPaseoApi(daemonClient: DaemonClient, scopeOptions?: {
+    signal?: AbortSignal;
+}): PaseoApi;
 //# sourceMappingURL=index.d.ts.map