@getpaseo/server 0.1.97 → 0.1.99

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

@@ -1,7 +1,7 @@
 import { AGENT_LIFECYCLE_STATUSES, type AgentLifecycleStatus } from "@getpaseo/protocol/agent-lifecycle";
 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 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 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";
@@ -266,12 +266,19 @@ export declare class AgentManager {
     private markRecordArchived;
     private fireAgentArchived;
     private dispatchArchivedStoredAgent;
-    setAgentMode(agentId: string, modeId: string): Promise<void>;
+    setAgentMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null>;
     setAgentModel(agentId: string, modelId: string | null): Promise<void>;
-    setAgentThinkingOption(agentId: string, thinkingOptionId: 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;
+    }>;
     notifyAgentState(agentId: string): void;
     clearAgentAttention(agentId: string): Promise<void>;
     archiveSnapshot(agentId: string, archivedAt: string): Promise<StoredAgentRecord>;
@@ -373,6 +380,7 @@ export declare class AgentManager {
     private getConfiguredProviderIds;
     private requireClient;
     archiveNativeSessionBestEffort(provider: AgentProvider, persistence: AgentPersistenceHandle | null | undefined): Promise<void>;
+    private unarchiveNativeSession;
     private requireAgent;
     private requireSessionAgent;
 }

package/dist/server/server/agent/agent-manager.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { stat } from "node:fs/promises";
 import { AGENT_LIFECYCLE_STATUSES, } from "@getpaseo/protocol/agent-lifecycle";
-import { isDelegatedAgent, PARENT_AGENT_ID_LABEL } from "@getpaseo/protocol/agent-labels";
+import { getParentAgentIdFromLabels, isDelegatedAgent, PARENT_AGENT_ID_LABEL, } from "@getpaseo/protocol/agent-labels";
 import { z } from "zod";
 import { getAgentStreamEventTurnId, } from "./agent-sdk-types.js";
 import { buildArchivedAgentRecord } from "./agent-archive.js";
@@ -109,6 +109,18 @@ function validateAgentId(agentId, source) {
     }
     return result.data;
 }
+function applyLabelPatch(labels, patch) {
+    const nextLabels = { ...labels };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete nextLabels[key];
+        }
+        else {
+            nextLabels[key] = value;
+        }
+    }
+    return nextLabels;
+}
 function buildExplicitTimelineSeedForRegister(now, options) {
     const hasTimeline = Boolean(options?.timeline?.length);
     const hasTimelineRows = Boolean(options?.timelineRows?.length);
@@ -676,9 +688,8 @@ export class AgentManager {
     }
     // Children created via the MCP `create_agent` tool carry the parent-agent-id
     // label pointing back at the caller. Archiving the parent cascades to those
-    // children so subagent fleets don't outlive their orchestrator. Handoff agents
-    // launched the same way are caught by this cascade — see docs/agent-lifecycle.md
-    // for the accepted limitation.
+    // children so subagent fleets don't outlive their orchestrator. Detached
+    // handoff agents omit this label, so they stand outside the cascade.
     async cascadeArchiveChildren(parentAgentId) {
         const registry = this.registry;
         if (!registry) {
@@ -768,7 +779,7 @@ export class AgentManager {
     }
     async setAgentMode(agentId, modeId) {
         const agent = this.requireSessionAgent(agentId);
-        await agent.session.setMode(modeId);
+        const notice = (await agent.session.setMode(modeId)) ?? null;
         const currentMode = (await agent.session.getCurrentMode()) ?? modeId;
         agent.config.modeId = currentMode ?? undefined;
         agent.currentModeId = currentMode;
@@ -778,6 +789,7 @@ export class AgentManager {
         }
         this.touchUpdatedAt(agent);
         this.emitState(agent);
+        return notice;
     }
     async setAgentModel(agentId, modelId) {
         const agent = this.requireSessionAgent(agentId);
@@ -797,8 +809,9 @@ export class AgentManager {
         const normalizedThinkingOptionId = typeof thinkingOptionId === "string" && thinkingOptionId.trim().length > 0
             ? thinkingOptionId
             : null;
+        let notice = null;
         if (agent.session.setThinkingOption) {
-            await agent.session.setThinkingOption(normalizedThinkingOptionId);
+            notice = (await agent.session.setThinkingOption(normalizedThinkingOptionId)) ?? null;
         }
         agent.config.thinkingOptionId = normalizedThinkingOptionId ?? undefined;
         if (agent.runtimeInfo) {
@@ -809,6 +822,7 @@ export class AgentManager {
         }
         this.touchUpdatedAt(agent);
         this.emitState(agent);
+        return notice;
     }
     async setAgentFeature(agentId, featureId, value) {
         const agent = this.requireAgent(agentId);
@@ -837,10 +851,68 @@ export class AgentManager {
     }
     async setLabels(agentId, labels) {
         const agent = this.requireAgent(agentId);
-        agent.labels = { ...agent.labels, ...labels };
-        this.touchUpdatedAt(agent);
-        await this.persistSnapshot(agent);
-        this.emitState(agent, { persist: false });
+        await this.writeLabels(agent.id, labels);
+    }
+    async writeLabels(agentId, patch) {
+        const liveAgent = this.agents.get(agentId);
+        if (liveAgent) {
+            liveAgent.labels = applyLabelPatch(liveAgent.labels, patch);
+            this.touchUpdatedAt(liveAgent);
+            await this.persistSnapshot(liveAgent);
+            this.emitState(liveAgent, { persist: false });
+            const record = this.registry ? await this.registry.get(agentId) : null;
+            return { record, live: true };
+        }
+        const nextRecord = await this.writeStoredMetadata(agentId, { labels: patch });
+        return { record: nextRecord, live: false };
+    }
+    async writeStoredMetadata(agentId, patch) {
+        const registry = this.requireRegistry();
+        const record = await registry.get(agentId);
+        if (!record) {
+            throw new Error(`Agent not found: ${agentId}`);
+        }
+        const nextRecord = {
+            ...record,
+            ...(patch.title ? { title: patch.title } : {}),
+            ...(patch.labels ? { labels: applyLabelPatch(record.labels, patch.labels) } : {}),
+            updatedAt: this.nextStoredUpdatedAt(record),
+        };
+        await registry.upsert(nextRecord);
+        return nextRecord;
+    }
+    async detachAgent(agentId) {
+        const registry = this.requireRegistry();
+        const liveAgent = this.agents.get(agentId);
+        if (liveAgent) {
+            const previousParentAgentId = getParentAgentIdFromLabels(liveAgent.labels);
+            if (!previousParentAgentId) {
+                await this.persistSnapshot(liveAgent);
+                const record = await registry.get(agentId);
+                if (!record) {
+                    throw new Error(`Agent not found in storage after detach: ${agentId}`);
+                }
+                return { record, live: true, previousParentAgentId: null };
+            }
+            const { record } = await this.writeLabels(agentId, { [PARENT_AGENT_ID_LABEL]: null });
+            if (!record) {
+                throw new Error(`Agent not found in storage after detach: ${agentId}`);
+            }
+            return { record, live: true, previousParentAgentId };
+        }
+        const record = await registry.get(agentId);
+        if (!record) {
+            throw new Error(`Agent not found: ${agentId}`);
+        }
+        const previousParentAgentId = getParentAgentIdFromLabels(record.labels);
+        if (!previousParentAgentId) {
+            return { record, live: false, previousParentAgentId: null };
+        }
+        const result = await this.writeLabels(agentId, { [PARENT_AGENT_ID_LABEL]: null });
+        if (!result.record) {
+            throw new Error(`Agent not found in storage after detach: ${agentId}`);
+        }
+        return { record: result.record, live: false, previousParentAgentId };
     }
     notifyAgentState(agentId) {
         const agent = this.agents.get(agentId);
@@ -888,9 +960,11 @@ export class AgentManager {
         if (!record || !record.archivedAt) {
             return false;
         }
+        await this.unarchiveNativeSession(record.provider, record.persistence);
         await registry.upsert({
             ...record,
             archivedAt: null,
+            updatedAt: new Date().toISOString(),
         });
         if (this.getAgent(agentId)) {
             this.notifyAgentState(agentId);
@@ -914,21 +988,11 @@ export class AgentManager {
                 await this.setTitle(agentId, updates.title);
             }
             if (updates.labels) {
-                await this.setLabels(agentId, updates.labels);
+                await this.writeLabels(agentId, updates.labels);
             }
             return;
         }
-        const registry = this.requireRegistry();
-        const existing = await registry.get(agentId);
-        if (!existing) {
-            throw new Error(`Agent not found: ${agentId}`);
-        }
-        await registry.upsert({
-            ...existing,
-            ...(updates.title ? { title: updates.title } : {}),
-            ...(updates.labels ? { labels: { ...existing.labels, ...updates.labels } } : {}),
-            updatedAt: this.nextStoredUpdatedAt(existing),
-        });
+        await this.writeStoredMetadata(agentId, updates);
     }
     async runAgent(agentId, prompt, options) {
         const events = this.streamAgent(agentId, prompt, options);
@@ -2516,8 +2580,8 @@ export class AgentManager {
             const client = this.clients.get(normalized.provider);
             if (client) {
                 try {
-                    const models = await client.listModels({ cwd: normalized.cwd, force: false });
-                    const defaultModel = models.find((model) => model.isDefault) ?? models[0];
+                    const catalog = await client.fetchCatalog({ cwd: normalized.cwd, force: false });
+                    const defaultModel = catalog.models.find((model) => model.isDefault) ?? catalog.models[0];
                     if (defaultModel) {
                         normalized.model = defaultModel.id;
                     }
@@ -2619,6 +2683,14 @@ export class AgentManager {
             this.logger.warn({ error, provider, sessionId: persistence.sessionId }, "Failed to archive native session (best-effort)");
         }
     }
+    async unarchiveNativeSession(provider, persistence) {
+        if (!persistence)
+            return;
+        const client = this.clients.get(provider);
+        if (!client?.unarchiveNativeSession)
+            return;
+        await client.unarchiveNativeSession(persistence);
+    }
     requireAgent(id) {
         const normalizedId = validateAgentId(id, "requireAgent");
         const agent = this.agents.get(normalizedId);

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

@@ -15,7 +15,7 @@ export declare function startAgentRun(agentManager: AgentRunController, agentId:
  * Shared across Session (app/WS), MCP, and CLI so every surface that acts on
  * an archived agent unarchives it the same way.
  */
-export declare function unarchiveAgentState(agentStorage: AgentStorage, agentManager: AgentManager, agentId: string): Promise<boolean>;
+export declare function unarchiveAgentState(_agentStorage: AgentStorage, agentManager: AgentManager, agentId: string): Promise<boolean>;
 /**
  * Wrap a body in <paseo-system>…</paseo-system> so the receiving agent
  * recognizes the prompt as system-injected context — not a user turn.

package/dist/server/server/agent/agent-prompt.js

@@ -55,17 +55,10 @@ export function startAgentRun(agentManager, agentId, prompt, logger, options) {
  * Shared across Session (app/WS), MCP, and CLI so every surface that acts on
  * an archived agent unarchives it the same way.
  */
-export async function unarchiveAgentState(agentStorage, agentManager, agentId) {
-    const record = await agentStorage.get(agentId);
-    if (!record || !record.archivedAt) {
+export async function unarchiveAgentState(_agentStorage, agentManager, agentId) {
+    const unarchived = await agentManager.unarchiveSnapshot(agentId);
+    if (!unarchived)
         return false;
-    }
-    const updatedAt = new Date().toISOString();
-    await agentStorage.upsert({
-        ...record,
-        archivedAt: null,
-        updatedAt,
-    });
     agentManager.notifyAgentState(agentId);
     return true;
 }

package/dist/server/server/agent/agent-sdk-types.d.ts

@@ -1,5 +1,7 @@
 import type { Options as ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentProviderNotice } from "@getpaseo/protocol/agent-types";
 import type { AgentAttachment } from "@getpaseo/protocol/messages";
+export type { AgentProviderNotice };
 export type AgentProvider = string;
 export interface AgentMetadata {
     [key: string]: unknown;
@@ -543,7 +545,7 @@ export interface AgentSession {
     getRuntimeInfo(): Promise<AgentRuntimeInfo>;
     getAvailableModes(): Promise<AgentMode[]>;
     getCurrentMode(): Promise<string | null>;
-    setMode(modeId: string): Promise<void>;
+    setMode(modeId: string): Promise<void | AgentProviderNotice>;
     getPendingPermissions(): AgentPermissionRequest[];
     respondToPermission(requestId: string, response: AgentPermissionResponse): Promise<AgentPermissionResult | void>;
     describePersistence(): AgentPersistenceHandle | null;
@@ -551,7 +553,7 @@ export interface AgentSession {
     close(): Promise<void>;
     listCommands?(): Promise<AgentSlashCommand[]>;
     setModel?(modelId: string | null): Promise<void>;
-    setThinkingOption?(thinkingOptionId: string | null): Promise<void>;
+    setThinkingOption?(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
     setFeature?(featureId: string, value: unknown): Promise<void>;
     revertConversation?(input: {
         messageId: string;
@@ -576,21 +578,26 @@ export interface AgentSession {
         }): Promise<void>;
     } | null;
 }
-export interface ListModelsOptions {
+export interface FetchCatalogOptions {
     cwd: string;
     force: boolean;
 }
-export interface ListModesOptions {
-    cwd: string;
-    force: boolean;
+export interface ProviderCatalog {
+    models: AgentModelDefinition[];
+    modes: AgentMode[];
 }
 export interface AgentClient {
     readonly provider: AgentProvider;
     readonly capabilities: AgentCapabilityFlags;
     createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext, options?: AgentCreateSessionOptions): Promise<AgentSession>;
     resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
-    listModels(options: ListModelsOptions): Promise<AgentModelDefinition[]>;
-    listModes?(options: ListModesOptions): Promise<AgentMode[]>;
+    /**
+     * Discover models and modes together. Implementations may use one upstream
+     * process, separate upstream calls, static modes, or private helpers; callers
+     * outside the provider do not get separate runtime model/mode probes.
+     * The registry is responsible for merging configured model overrides.
+     */
+    fetchCatalog(options: FetchCatalogOptions): Promise<ProviderCatalog>;
     resolveCreateConfig?(input: ResolveAgentCreateConfigInput): ResolveAgentCreateConfigResult;
     isCreateConfigUnattended?(input: AgentCreateConfigUnattendedInput): boolean;
     listCommands?(config: AgentSessionConfig): Promise<AgentSlashCommand[]>;
@@ -610,6 +617,11 @@ export interface AgentClient {
      * Called when Paseo archives an agent so the provider's own UI reflects the same state.
      */
     archiveNativeSession?(handle: AgentPersistenceHandle): Promise<void>;
+    /**
+     * Unarchive a persisted session in the native provider.
+     * Called before Paseo clears its archived flag so provider resume can succeed.
+     */
+    unarchiveNativeSession?(handle: AgentPersistenceHandle): Promise<void>;
     /**
      * Release any provider-owned resources held by this client (background
      * processes, sockets, cached subprocesses, etc.). Called when the daemon
@@ -617,5 +629,4 @@ export interface AgentClient {
      */
     shutdown?(): Promise<void>;
 }
-export {};
 //# sourceMappingURL=agent-sdk-types.d.ts.map

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

@@ -48,6 +48,7 @@ export interface CreateAgentFromMcpInput {
     title: string;
     initialPrompt: string;
     cwd?: string;
+    workspaceId?: string;
     thinking?: string;
     features?: Record<string, unknown>;
     labels?: Record<string, string>;
@@ -63,6 +64,7 @@ export interface CreateAgentFromMcpInput {
     } | null;
     worktree?: {
         worktreeName?: string;
+        branchName?: string;
         baseBranch?: string;
         refName?: string;
         action?: "branch-off" | "checkout";

package/dist/server/server/agent/create-agent/create.js

@@ -90,15 +90,15 @@ async function resolveMcpCreateAgent(dependencies, input) {
         worktree: input.worktree,
         initialPrompt: input.initialPrompt,
     });
-    // A child agent created in its parent's working tree belongs to the parent's
-    // workspace. When a new worktree is created the child lives in that fresh
-    // workspace, so it is stamped with the new worktree's workspaceId instead
-    // (mirrors the session path) — keeping the agent discoverable by
-    // workspaceId-scoped archive. With neither a parent nor a worktree, the agent
-    // mints its own workspace; ownership is never resolved from cwd.
+    // MCP callers resolve workspace ownership before this point. Worktree
+    // creation wins because the new agent lives in the fresh worktree workspace.
+    // Otherwise use the explicit workspace id, then the parent workspace for
+    // direct internal callers. Ownership is never resolved from cwd.
     const workspaceId = setupContinuation
         ? createdWorkspaceId
-        : (parentAgent?.workspaceId ?? (await ensureWorkspaceForMcpCreate(dependencies, resolvedCwd)));
+        : (input.workspaceId ??
+            parentAgent?.workspaceId ??
+            (await ensureWorkspaceForMcpCreate(dependencies, resolvedCwd)));
     const { modeId: resolvedMode, featureValues: resolvedFeatures } = await dependencies.providerSnapshotManager.resolveCreateConfig({
         cwd: resolvedCwd,
         provider,
@@ -224,6 +224,7 @@ async function resolveMcpCwd(params) {
         input: {
             cwd: params.cwd,
             worktreeSlug: worktree.worktreeName,
+            branchName: worktree.branchName,
             refName: worktree.refName,
             action: worktree.action,
             githubPrNumber: worktree.githubPrNumber,

package/dist/server/server/agent/lifecycle-command.d.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "pino";
 import type { ManagedAgent } from "./agent-manager.js";
 import type { StoredAgentRecord } from "./agent-storage.js";
+import type { AgentProviderNotice } from "./agent-sdk-types.js";
 export type LifecycleAgentSnapshot = Pick<ManagedAgent, "id" | "cwd" | "lifecycle">;
 export interface LifecycleAgentManager {
     getAgent(agentId: string): LifecycleAgentSnapshot | null;
@@ -13,8 +14,13 @@ export interface LifecycleAgentManager {
     archiveSnapshot(agentId: string, archivedAt: string): Promise<StoredAgentRecord>;
     closeAgent(agentId: string): Promise<void>;
     setLabels(agentId: string, labels: Record<string, string>): Promise<void>;
+    detachAgent(agentId: string): Promise<{
+        record: StoredAgentRecord;
+        live: boolean;
+        previousParentAgentId: string | null;
+    }>;
     notifyAgentState(agentId: string): void;
-    setAgentMode(agentId: string, modeId: string): Promise<void>;
+    setAgentMode(agentId: string, modeId: string): Promise<AgentProviderNotice | null>;
     updateAgentMetadata(agentId: string, updates: {
         title?: string;
         labels?: Record<string, string>;
@@ -50,10 +56,18 @@ export declare function updateAgentCommand(dependencies: Pick<AgentLifecycleComm
     name?: string;
     labels?: Record<string, string>;
 }): Promise<UpdateAgentResult>;
+export interface DetachAgentResult {
+    agentId: string;
+    record: StoredAgentRecord;
+    live: boolean;
+    previousParentAgentId: string | null;
+}
+export declare function detachAgentCommand(dependencies: Pick<AgentLifecycleCommandDependencies, "agentManager">, agentId: string): Promise<DetachAgentResult>;
 export declare function setAgentModeCommand(dependencies: Pick<AgentLifecycleCommandDependencies, "agentManager">, input: {
     agentId: string;
     modeId: string;
 }): Promise<{
     modeId: string;
+    notice: AgentProviderNotice | null;
 }>;
 //# sourceMappingURL=lifecycle-command.d.ts.map

package/dist/server/server/agent/lifecycle-command.js

@@ -67,9 +67,16 @@ export async function updateAgentCommand(dependencies, input) {
         error: null,
     };
 }
+export async function detachAgentCommand(dependencies, agentId) {
+    const result = await dependencies.agentManager.detachAgent(agentId);
+    return {
+        agentId,
+        ...result,
+    };
+}
 export async function setAgentModeCommand(dependencies, input) {
-    await dependencies.agentManager.setAgentMode(input.agentId, input.modeId);
-    return { modeId: input.modeId };
+    const notice = await dependencies.agentManager.setAgentMode(input.agentId, input.modeId);
+    return { modeId: input.modeId, notice };
 }
 async function archiveStoredAgent(dependencies, agentId) {
     const existing = await dependencies.agentStorage.get(agentId);