@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/agent/agent-manager.d.ts

@@ -0,0 +1,462 @@
+import { AGENT_LIFECYCLE_STATUSES, type AgentLifecycleStatus } from "@hyperdrive.bot/paseo-protocol/agent-lifecycle";
+import type { SessionDigest } from "../messages.js";
+import type { Logger } from "pino";
+import type { TerminalManager } from "../../terminal/terminal-manager.js";
+import { type AgentCapabilityFlags, type AgentClient, type AgentFeature, type AgentSlashCommand, type AgentMode, type AgentPermissionRequest, type AgentPermissionResponse, type AgentPermissionResult, type AgentPersistenceHandle, type AgentProviderNotice, type AgentPromptInput, type AgentProvider, type AgentRunOptions, type AgentRunResult, type AgentSession, type AgentSessionConfig, type AgentStreamEvent, type AgentTimelineItem, type AgentUsage, type AgentRuntimeInfo, type ImportableProviderSession, type ListImportableSessionsOptions } from "./agent-sdk-types.js";
+import type { StoredAgentRecord, AgentStorage } from "./agent-storage.js";
+import type { AgentTimelineFetchOptions, AgentTimelineFetchResult, AgentTimelineRow, AgentTimelineStore } from "./agent-timeline-store-types.js";
+import { type ForegroundTurnWaiter } from "./foreground-run-state.js";
+import { type RewindMode } from "./rewind/rewind.js";
+import type { PaseoToolCatalogFactory } from "./tools/types.js";
+export { AGENT_LIFECYCLE_STATUSES, type AgentLifecycleStatus };
+export type { AgentTimelineCursor, AgentTimelineFetchDirection, AgentTimelineFetchOptions, AgentTimelineFetchResult, AgentTimelineRow, AgentTimelineWindow, } from "./agent-timeline-store-types.js";
+export type AgentManagerEvent = {
+    type: "agent_state";
+    agent: ManagedAgent;
+} | {
+    type: "agent_stream";
+    agentId: string;
+    event: AgentStreamEvent;
+    seq?: number;
+    epoch?: string;
+    timestamp?: string;
+};
+export type AgentSubscriber = (event: AgentManagerEvent) => void;
+export interface SubscribeOptions {
+    agentId?: string;
+    replayState?: boolean;
+}
+interface HydrateTimelineOptions {
+    force?: boolean;
+    broadcast?: boolean;
+}
+export type ImportablePersistedAgentQueryOptions = ListImportableSessionsOptions & {
+    /**
+     * When set, only providers in this set are scanned, in addition to the
+     * built-in importable allowlist + enabled + non-derived rules.
+     */
+    providerFilter?: Set<string>;
+};
+export interface ManagedImportableProviderSession extends ImportableProviderSession {
+    provider: AgentProvider;
+}
+export type AgentAttentionCallback = (params: {
+    agentId: string;
+    provider: AgentProvider;
+    reason: "finished" | "error" | "permission";
+}) => void;
+export type AgentArchivedCallback = (agentId: string) => Promise<void> | void;
+export interface ProviderAvailability {
+    provider: AgentProvider;
+    available: boolean;
+    error: string | null;
+}
+interface AgentManagerRescueTimeouts {
+    reloadSessionCloseMs?: number;
+    interruptSessionMs?: number;
+}
+interface ProviderEnabledFlag {
+    enabled: boolean;
+    /** Wire-format family used for hot-swap eligibility checks. */
+    wireFamily?: "anthropic-messages" | "openai-compatible" | "generic-acp";
+    /**
+     * Effective hot-swap targets — provider IDs this provider can swap TO
+     * mid-session. Validated bidirectionally at registry build time.
+     */
+    compatibleProviders?: readonly string[];
+}
+type ProviderEnabledMap = Partial<Record<AgentProvider, ProviderEnabledFlag>>;
+type ProviderClientMap = Partial<Record<AgentProvider, AgentClient>>;
+export interface AgentManagerOptions {
+    clients?: ProviderClientMap;
+    providerDefinitions?: ProviderEnabledMap;
+    idFactory?: () => string;
+    registry?: AgentStorage;
+    onAgentAttention?: AgentAttentionCallback;
+    onWorkspaceStateMayHaveChanged?: (params: {
+        cwd: string;
+    }) => void;
+    durableTimelineStore?: AgentTimelineStore;
+    terminalManager?: TerminalManager | null;
+    mcpBaseUrl?: string;
+    mcpAuthToken?: string;
+    paseoToolsEnabled?: boolean;
+    paseoToolCatalogFactory?: PaseoToolCatalogFactory;
+    appendSystemPrompt?: string;
+    agentStreamCoalesceWindowMs?: number;
+    rescueTimeouts?: AgentManagerRescueTimeouts;
+    logger: Logger;
+}
+export interface WaitForAgentOptions {
+    signal?: AbortSignal;
+    waitForActive?: boolean;
+}
+export interface WaitForAgentResult {
+    status: AgentLifecycleStatus;
+    permission: AgentPermissionRequest | null;
+    lastMessage: string | null;
+}
+export interface WaitForAgentStartOptions {
+    signal?: AbortSignal;
+}
+type AttentionState = {
+    requiresAttention: false;
+} | {
+    requiresAttention: true;
+    attentionReason: "finished" | "error" | "permission";
+    attentionTimestamp: Date;
+};
+interface ManagedAgentBase {
+    id: string;
+    provider: AgentProvider;
+    cwd: string;
+    /**
+     * Workspace this agent belongs to, stamped at creation. Independent of cwd:
+     * cwd answers "where does it run", workspaceId answers "which workspace owns it".
+     * Null/undefined for legacy agents created before ownership stamping.
+     */
+    workspaceId?: string;
+    capabilities: AgentCapabilityFlags;
+    config: AgentSessionConfig;
+    runtimeInfo?: AgentRuntimeInfo;
+    createdAt: Date;
+    updatedAt: Date;
+    availableModes: AgentMode[];
+    features?: AgentFeature[];
+    currentModeId: string | null;
+    pendingPermissions: Map<string, AgentPermissionRequest>;
+    bufferedPermissionResolutions: Map<string, Extract<AgentStreamEvent, {
+        type: "permission_resolved";
+    }>>;
+    inFlightPermissionResponses: Set<string>;
+    pendingReplacement: boolean;
+    persistence: AgentPersistenceHandle | null;
+    historyPrimed: boolean;
+    lastUserMessageAt: Date | null;
+    lastUsage?: AgentUsage;
+    lastError?: string;
+    attention: AttentionState;
+    foregroundTurnWaiters: Set<ForegroundTurnWaiter>;
+    finalizedForegroundTurnIds: Set<string>;
+    unsubscribeSession: (() => void) | null;
+    /**
+     * Internal agents are hidden from listings and don't trigger notifications.
+     */
+    internal?: boolean;
+    /**
+     * User-defined labels for categorizing agents (e.g., { surface: "workspace" }).
+     */
+    labels: Record<string, string>;
+    /**
+     * Session digest — structured per-session metadata for orchestrator triage.
+     * Self-reported fields (goal/nextStep/blockers/links) are set via the
+     * set_session_digest MCP tool; keyFiles/summary/accomplishments are derived
+     * by the daemon on the running→idle transition. See docs/session-digest.md.
+     */
+    digest?: SessionDigest;
+}
+type ManagedAgentWithSession = ManagedAgentBase & {
+    session: AgentSession;
+};
+type ManagedAgentInitializing = ManagedAgentWithSession & {
+    lifecycle: "initializing";
+    activeForegroundTurnId: null;
+};
+type ManagedAgentIdle = ManagedAgentWithSession & {
+    lifecycle: "idle";
+    activeForegroundTurnId: null;
+};
+type ManagedAgentRunning = ManagedAgentWithSession & {
+    lifecycle: "running";
+    activeForegroundTurnId: string | null;
+};
+type ManagedAgentError = ManagedAgentWithSession & {
+    lifecycle: "error";
+    activeForegroundTurnId: null;
+    lastError: string;
+};
+type ManagedAgentClosed = ManagedAgentBase & {
+    lifecycle: "closed";
+    session: null;
+    activeForegroundTurnId: null;
+};
+export type ManagedAgent = ManagedAgentInitializing | ManagedAgentIdle | ManagedAgentRunning | ManagedAgentError | ManagedAgentClosed;
+export interface AgentMetricsSnapshot {
+    total: number;
+    byLifecycle: Record<string, number>;
+    withActiveForegroundTurn: number;
+    timelineStats: {
+        totalItems: number;
+        maxItemsPerAgent: number;
+    };
+}
+export declare class AgentManager {
+    private readonly clients;
+    private readonly providerEnabled;
+    /**
+     * Per-provider hot-swap metadata indexed by provider id. Populated by
+     * {@link updateProviderRegistry} from the daemon's ProviderEnabledMap.
+     * Empty when callers (mostly tests) pass only the bare `{enabled}` shape.
+     */
+    private readonly providerSwapMetadata;
+    private readonly agents;
+    private readonly timelineStore;
+    private readonly agentsAwaitingInitialSnapshotPersist;
+    private readonly sessionEventTails;
+    private readonly foregroundRuns;
+    private readonly subscribers;
+    private readonly idFactory;
+    private readonly registry?;
+    private readonly durableTimelineStore?;
+    private readonly previousStatuses;
+    private readonly backgroundTasks;
+    private readonly agentStreamCoalescer;
+    private mcpBaseUrl;
+    private readonly attentionListeners;
+    private readonly mcpAuthToken;
+    private paseoToolsEnabled;
+    private paseoToolCatalogFactory;
+    private onWorkspaceStateMayHaveChanged?;
+    private logger;
+    private readonly rescueTimeouts;
+    private appendSystemPrompt;
+    private onAgentArchived?;
+    constructor(options: AgentManagerOptions);
+    private configurePaseoTools;
+    registerClient(provider: AgentProvider, client: AgentClient): void;
+    updateProviderRegistry(input: {
+        providerDefinitions: ProviderEnabledMap;
+        clients: ProviderClientMap;
+    }): void;
+    getRegisteredProviderIds(): AgentProvider[];
+    /**
+     * @deprecated Use {@link addAgentAttentionListener} for multi-subscriber registration.
+     * Retained for back-compat: replaces all currently-registered listeners with `callback`.
+     */
+    setAgentAttentionCallback(callback: AgentAttentionCallback): void;
+    /**
+     * Register an additional attention listener. Returns an unsubscribe function.
+     * Multiple subscribers are supported (e.g. WebSocketServer + pushTrigger emitter).
+     */
+    addAgentAttentionListener(listener: AgentAttentionCallback): () => void;
+    setAgentArchivedCallback(callback: AgentArchivedCallback): void;
+    setMcpBaseUrl(url: string | null): void;
+    setPaseoToolsEnabled(enabled: boolean): void;
+    setPaseoToolCatalogFactory(factory: PaseoToolCatalogFactory | null): void;
+    /**
+     * Capability token the daemon's own MCP clients must present to the Agent MCP
+     * endpoint when a daemon password is configured. Read by the per-client
+     * session to authenticate its own MCP connection. Stays in the daemon — never
+     * sent to remote clients.
+     */
+    getMcpAuthToken(): string | null;
+    setAppendSystemPrompt(prompt: string | null | undefined): void;
+    getMetricsSnapshot(): AgentMetricsSnapshot;
+    private touchUpdatedAt;
+    private nextStoredUpdatedAt;
+    hasInFlightRun(agentId: string): boolean;
+    subscribe(callback: AgentSubscriber, options?: SubscribeOptions): () => void;
+    listAgents(): ManagedAgent[];
+    listImportableSessions(options?: ImportablePersistedAgentQueryOptions): Promise<ManagedImportableProviderSession[]>;
+    private isProviderImportable;
+    listProviderAvailability(): Promise<ProviderAvailability[]>;
+    getProviderAvailability(provider: AgentProvider): Promise<ProviderAvailability>;
+    listDraftCommands(config: AgentSessionConfig): Promise<AgentSlashCommand[]>;
+    listDraftFeatures(config: AgentSessionConfig): Promise<AgentFeature[]>;
+    getAgent(id: string): ManagedAgent | null;
+    getTimeline(id: string): AgentTimelineItem[];
+    getTimelineRows(id: string): Promise<AgentTimelineRow[]>;
+    fetchTimeline(id: string, options?: AgentTimelineFetchOptions): AgentTimelineFetchResult;
+    createAgent(config: AgentSessionConfig, agentId?: string, options?: {
+        labels?: Record<string, string>;
+        digest?: SessionDigest;
+        initialPrompt?: string;
+        initialTitle?: string | null;
+        env?: Record<string, string>;
+        persistSession?: boolean;
+        resumeSessionId?: string;
+        workspaceId?: string;
+    }): Promise<ManagedAgent>;
+    private buildCreateSessionOptions;
+    resumeAgentFromPersistence(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, agentId?: string, options?: {
+        createdAt?: Date;
+        updatedAt?: Date;
+        lastUserMessageAt?: Date | null;
+        labels?: Record<string, string>;
+        workspaceId?: string;
+        digest?: SessionDigest;
+    }): Promise<ManagedAgent>;
+    importProviderSession(input: {
+        provider: AgentProvider;
+        providerHandleId: string;
+        cwd: string;
+        workspaceId: string;
+        labels?: Record<string, string>;
+    }): Promise<ManagedAgent>;
+    /**
+     * Hot-swap a running agent's provider to a compatible alternative
+     * (e.g. Claude → Claude (Pool)). Compatibility is determined by the
+     * provider registry's effective `compatibleProviders` set — the swap is
+     * rejected if the target is not declared compatible.
+     *
+     * Preserves the session timeline, persistence handle, labels, and lifecycle
+     * metadata. Any in-flight turn is canceled first (best effort). On success,
+     * the session is recreated against the new provider's client using
+     * `resumeSession` with the existing persistence handle rewritten to the new
+     * provider, plus an optional model/mode override.
+     *
+     * Throws if the target provider has no registered client, is disabled, or
+     * is not in the current provider's compatible list.
+     */
+    swapAgentProvider(agentId: string, newProviderId: AgentProvider, overrides?: {
+        model?: string | null;
+        modeId?: string;
+    }): Promise<ManagedAgent>;
+    reloadAgentSession(agentId: string, overrides?: Partial<AgentSessionConfig>, options?: {
+        rehydrateFromDisk?: boolean;
+    }): Promise<ManagedAgent>;
+    private closeReloadedSession;
+    private waitWithTimeout;
+    closeAgent(agentId: string): Promise<void>;
+    archiveAgent(agentId: string): Promise<{
+        archivedAt: string;
+    }>;
+    private cascadeArchiveChildren;
+    private markRecordArchived;
+    private fireAgentArchived;
+    private dispatchArchivedStoredAgent;
+    setAgentMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null>;
+    setAgentModel(agentId: string, modelId: string | null): Promise<void>;
+    setAgentThinkingOption(agentId: string, thinkingOptionId: string | null): Promise<AgentProviderNotice | null>;
+    setAgentFeature(agentId: string, featureId: string, value: unknown): Promise<void>;
+    setTitle(agentId: string, title: string): Promise<void>;
+    setLabels(agentId: string, labels: Record<string, string>): Promise<void>;
+    private writeLabels;
+    private writeStoredMetadata;
+    detachAgent(agentId: string): Promise<{
+        record: StoredAgentRecord;
+        live: boolean;
+        previousParentAgentId: string | null;
+    }>;
+    /**
+     * Replace the session digest wholesale. Callers (the set_session_digest MCP
+     * tool and the daemon digest refresher) compute the merged digest and pass
+     * the full object. See docs/session-digest.md.
+     */
+    setDigest(agentId: string, digest: SessionDigest): Promise<void>;
+    notifyAgentState(agentId: string): void;
+    clearAgentAttention(agentId: string): Promise<void>;
+    archiveSnapshot(agentId: string, archivedAt: string): Promise<StoredAgentRecord>;
+    unarchiveSnapshot(agentId: string): Promise<boolean>;
+    unarchiveSnapshotByHandle(handle: AgentPersistenceHandle): Promise<void>;
+    updateAgentMetadata(agentId: string, updates: {
+        title?: string;
+        labels?: Record<string, string>;
+        digest?: SessionDigest;
+    }): Promise<void>;
+    runAgent(agentId: string, prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Try to run a prompt out-of-band — i.e. without allocating a foreground turn
+     * and without canceling any active turn. Returns true when the session
+     * accepted the prompt as a side-effect command (e.g. /goal pause). Events
+     * emitted by the handler flow through dispatchStream so they persist and
+     * broadcast like normal timeline events.
+     */
+    tryRunOutOfBand(agentId: string, prompt: AgentPromptInput): boolean;
+    appendTimelineItem(agentId: string, item: AgentTimelineItem): Promise<void>;
+    emitLiveTimelineItem(agentId: string, item: AgentTimelineItem): Promise<void>;
+    streamAgent(agentId: string, prompt: AgentPromptInput, options?: AgentRunOptions): AsyncGenerator<AgentStreamEvent>;
+    private finalizeForegroundTurn;
+    replaceAgentRun(agentId: string, prompt: AgentPromptInput, options?: AgentRunOptions): AsyncGenerator<AgentStreamEvent>;
+    waitForAgentRunStart(agentId: string, options?: WaitForAgentStartOptions): Promise<void>;
+    respondToPermission(agentId: string, requestId: string, response: AgentPermissionResponse): Promise<AgentPermissionResult | void>;
+    /**
+     * Dismiss a live background shell for an agent. Delegates to the provider
+     * session, which (for Claude Code over PTY) kills the shell inside the CLI
+     * via its own keybinding. Returns false if the provider doesn't support it.
+     */
+    dismissBackgroundTask(agentId: string, taskId: string): Promise<boolean>;
+    cancelAgentRun(agentId: string): Promise<boolean>;
+    private interruptSession;
+    getPendingPermissions(agentId: string): AgentPermissionRequest[];
+    private peekPendingPermission;
+    /**
+     * Hydrates the timeline from provider history if the agent's durable
+     * timeline is empty (e.g., imported agents that have provider history
+     * on disk but no persisted timeline rows). No-ops if already hydrated.
+     */
+    hydrateTimelineFromProvider(agentId: string, options?: HydrateTimelineOptions): Promise<void>;
+    rewind(agentId: string, messageId: string, mode: RewindMode): Promise<void>;
+    deleteCommittedTimeline(agentId: string): Promise<void>;
+    getLastAssistantMessage(agentId: string): Promise<string | null>;
+    private getLastAssistantMessageFromTimeline;
+    private getLastAssistantMessageSegmentFromTimeline;
+    private getLastAssistantMessageFromStores;
+    private getLastItemFromStores;
+    waitForAgentEvent(agentId: string, options?: WaitForAgentOptions): Promise<WaitForAgentResult>;
+    private registerSession;
+    private initializeAgentTimelineForRegister;
+    private buildManagedAgentForRegister;
+    private loadCommittedTimelineSeed;
+    private prepareAgentForClosure;
+    private emitClosedAgent;
+    private subscribeToSession;
+    private enqueueSessionEvent;
+    private dispatchSessionEvent;
+    private resolveInitialPersistedTitle;
+    private persistSnapshot;
+    private requireRegistry;
+    private refreshSessionState;
+    private refreshRuntimeInfo;
+    private hydrateTimelineFromLegacyProviderHistory;
+    private notifyForegroundTurnWaiters;
+    private handleStreamEvent;
+    private traceHandleStreamEventStart;
+    private traceCoalescerBuffered;
+    private traceHandleStreamEventEnd;
+    private dispatchStreamEventByType;
+    private onStreamThreadStarted;
+    private onStreamTimelineEvent;
+    private onStreamTurnCompleted;
+    private onStreamTurnFailed;
+    private onStreamTurnCanceled;
+    private onStreamTurnStarted;
+    private onStreamPermissionRequested;
+    private onStreamPermissionResolved;
+    private resolvePendingPermissionsForAgent;
+    private recordAndDispatchTimelineItem;
+    private appendSystemErrorTimelineMessage;
+    private formatTurnFailedMessage;
+    private recordTimeline;
+    private emitState;
+    private syncFeaturesFromSession;
+    private checkAndSetAttention;
+    private enqueueBackgroundPersist;
+    private enqueueDurableTimelineAppend;
+    private enqueueDurableTimelineBulkInsert;
+    private trackBackgroundTask;
+    /**
+     * Flush any background persistence work (best-effort).
+     * Used by daemon shutdown paths to avoid unhandled rejections after cleanup.
+     */
+    flush(): Promise<void>;
+    private broadcastAgentAttention;
+    private dispatchStream;
+    private dispatch;
+    private normalizeConfig;
+    private resolveDefaultModelId;
+    private prepareSessionConfig;
+    private applyDaemonAppendSystemPrompt;
+    private buildLaunchContext;
+    private resolveProviderLaunchConfig;
+    private requireAvailableClient;
+    private requireEnabledProvider;
+    private getConfiguredProviderIds;
+    private requireClient;
+    archiveNativeSessionBestEffort(provider: AgentProvider, persistence: AgentPersistenceHandle | null | undefined): Promise<void>;
+    private unarchiveNativeSession;
+    private requireAgent;
+    private requireSessionAgent;
+}
+export declare function commandMayHaveChangedExternalState(command: string): boolean;
+//# sourceMappingURL=agent-manager.d.ts.map