apex-code 0.5.1 → 0.6.0

package/dist/core/agent-session.js

@@ -27,6 +27,7 @@ import { generateBugReportSummary } from "./bug-report.js";
 import { createSessionCheckpoints } from "./checkpoints/session-checkpoints.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { evictionBudget, installContextPipeline, isDefaultStreamFunction } from "./context/pipeline.js";
+import { configuredDefaultToolNames } from "./default-tool-names.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
 import { RESUME_CHILD_PROMPT, runDelegation } from "./delegation/runtime.js";
 import { SessionEvidenceSink } from "./evidence.js";
@@ -51,6 +52,7 @@ import { buildSystemPrompt, buildSystemPromptSections, diffSystemPromptSections,
 import { createLocalBashOperations } from "./tools/bash.js";
 import { buildToolContractSnapshot, isUnclassifiedTool, } from "./tools/contract-snapshot.js";
 import { createAllToolDefinitions } from "./tools/index.js";
+import { createPlanPresentToolDefinition, defaultPlanPresenter } from "./tools/plan-present.js";
 import { createSkillSearchToolDefinition } from "./tools/skill-search.js";
 import { createTodoWriteToolDefinition } from "./tools/todo-write.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
@@ -165,9 +167,13 @@ export class AgentSession {
     _initialActiveToolNames;
     _allowedToolNames;
     _excludedToolNames;
+    _implicitDefaultToolNames;
     _baseToolsOverride;
     _sessionStartEvent;
     _permissionGate;
+    _interactivePermissionMode;
+    _interactivePermissionModeGeneration = 0;
+    _startupPermissionMode;
     _evidenceSink;
     _diagnosticsOperations;
     _lspOperations;
@@ -206,6 +212,13 @@ export class AgentSession {
     _baseSystemPromptOptions;
     /** Prompt options after before_agent_start mutations for the active run. */
     _runSystemPromptOptions;
+    _requestedToolNames = [];
+    _runRequestedToolNames;
+    _planToolMode;
+    _planToolSyncGeneration = 0;
+    _pendingPlanToolSync;
+    _planToolSyncChange = new AbortController();
+    _planPresentationGeneration = 0;
     constructor(config) {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
@@ -224,8 +237,26 @@ export class AgentSession {
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
         this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
+        this._implicitDefaultToolNames = config.implicitDefaultToolNames
+            ? [...config.implicitDefaultToolNames]
+            : undefined;
         this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
-        this._permissionGate = config.permissionGate;
+        if (config.permissionGate) {
+            const configuredGate = config.permissionGate;
+            try {
+                const startupMode = configuredGate.getMode();
+                if (typeof startupMode === "string")
+                    this._planToolMode = startupMode;
+                this._startupPermissionMode = Promise.resolve(startupMode).then((mode) => ({ ok: true, mode }), (error) => ({ ok: false, error }));
+            }
+            catch (error) {
+                this._startupPermissionMode = Promise.resolve({ ok: false, error });
+            }
+            this._permissionGate = {
+                ...configuredGate,
+                getMode: () => this._interactivePermissionMode ?? configuredGate.getMode(),
+            };
+        }
         this._evidenceSink = config.evidenceSink ?? new SessionEvidenceSink(this.sessionManager);
         this._diagnosticsOperations = config.diagnosticsOperations;
         this._lspOperations = config.lspOperations;
@@ -280,6 +311,15 @@ export class AgentSession {
         });
         if (this._initialActiveToolNames === undefined)
             this._restoreToolsFromTranscript();
+        const generation = this._planToolSyncGeneration;
+        void this._startupPermissionMode
+            ?.then((startup) => {
+            if (startup.ok && generation === this._planToolSyncGeneration && this._lifecycle !== "closed") {
+                this._planToolMode = startup.mode;
+                this._applyRequestedTools();
+            }
+        })
+            .catch(() => { });
     }
     get modelRuntime() {
         return this._modelRuntime;
@@ -547,6 +587,7 @@ export class AgentSession {
                 ? async (_turn, signal) => await this.agent.prepareNextTurn?.(signal)
                 : undefined);
         this.agent.prepareNextTurnWithContext = async (turn, signal) => {
+            await this._syncPlanToolMode();
             const context = await this._compactBeforeNextAssistantResponse({
                 ...turn.context,
                 messages: this.sessionManager.buildSessionProjection().messages,
@@ -556,7 +597,7 @@ export class AgentSession {
             const runOptions = this._runSystemPromptOptions ?? this._baseSystemPromptOptions;
             const options = normalizeBuildSystemPromptOptions({
                 ...runOptions,
-                selectedTools: this.getActiveToolNames(),
+                selectedTools: this._projectToolNames(this._runRequestedToolNames ?? this._requestedToolNames),
                 toolSnippets: { ...this._baseSystemPromptOptions.toolSnippets, ...runOptions.toolSnippets },
                 toolGuidelines: { ...this._baseSystemPromptOptions.toolGuidelines, ...runOptions.toolGuidelines },
             });
@@ -1262,6 +1303,10 @@ export class AgentSession {
         if (this._lifecycle === "closed")
             return;
         this._lifecycle = "closed";
+        this._planPresentationGeneration++;
+        this._planToolSyncGeneration++;
+        this._setPendingPlanToolSync();
+        this._interactivePermissionModeGeneration++;
         try {
             this.abortRetry();
             this.abortCompaction();
@@ -1332,6 +1377,14 @@ export class AgentSession {
     get retryAttempt() {
         return this._retryAttempt;
     }
+    getImplicitDefaultToolNames() {
+        return this._implicitDefaultToolNames
+            ? [...this._implicitDefaultToolNames]
+            : configuredDefaultToolNames({
+                baseNames: this._baseToolsOverride ? Object.keys(this._baseToolsOverride) : undefined,
+                lsp: Boolean(this._lspOperations),
+            });
+    }
     /**
      * Get the names of currently active tools.
      * Returns the names of tools currently set on the agent.
@@ -1372,17 +1425,90 @@ export class AgentSession {
      * Changes take effect on the next agent turn.
      */
     setActiveToolsByName(toolNames) {
-        const tools = [];
-        const validToolNames = [];
-        for (const name of toolNames) {
+        this._requestedToolNames = [...new Set(toolNames)].filter((name) => this._toolRegistry.has(name));
+        this._runRequestedToolNames = undefined;
+        this._applyRequestedTools();
+    }
+    _projectToolNames(names) {
+        const projected = [...new Set(names)].filter((name) => this._toolRegistry.has(name));
+        if (this._planToolMode === "plan" &&
+            this._toolRegistry.has("plan_present") &&
+            !projected.includes("plan_present"))
+            projected.push("plan_present");
+        return projected;
+    }
+    _applyRequestedTools() {
+        const names = this._projectToolNames(this._runRequestedToolNames ?? this._requestedToolNames);
+        this.agent.state.tools = names.flatMap((name) => {
             const tool = this._toolRegistry.get(name);
-            if (tool) {
-                tools.push(tool);
-                validToolNames.push(name);
+            return tool ? [tool] : [];
+        });
+        this._rebuildSystemPrompt(this._projectToolNames(this._requestedToolNames));
+    }
+    _setPendingPlanToolSync(task) {
+        this._pendingPlanToolSync = task;
+        const previous = this._planToolSyncChange;
+        this._planToolSyncChange = new AbortController();
+        previous.abort();
+    }
+    async _syncPlanToolMode() {
+        const generation = ++this._planToolSyncGeneration;
+        const task = (async () => {
+            const mode = await this._permissionGate?.getMode();
+            if (generation !== this._planToolSyncGeneration || this._lifecycle === "closed")
+                return;
+            this._planToolMode = mode;
+            this._applyRequestedTools();
+        })();
+        this._setPendingPlanToolSync(task);
+        let pending = task;
+        for (;;) {
+            const signal = this._planToolSyncChange.signal;
+            let wake;
+            const changed = new Promise((resolve) => {
+                wake = resolve;
+                signal.addEventListener("abort", wake, { once: true });
+            });
+            try {
+                await Promise.race([pending, changed]);
             }
-        }
-        this.agent.state.tools = tools;
-        this._rebuildSystemPrompt(validToolNames);
+            catch (error) {
+                if (pending === this._pendingPlanToolSync)
+                    throw error;
+            }
+            finally {
+                signal.removeEventListener("abort", wake);
+            }
+            if (!this._pendingPlanToolSync || pending === this._pendingPlanToolSync)
+                return;
+            pending = this._pendingPlanToolSync;
+        }
+    }
+    _schedulePlanToolSync() {
+        void this._syncPlanToolMode().catch(() => { });
+    }
+    async _presentPlan(plan, ctx, signal) {
+        const generation = this._planPresentationGeneration;
+        const modeGeneration = this._interactivePermissionModeGeneration;
+        const obsolete = () => signal?.aborted ||
+            this._lifecycle === "closed" ||
+            generation !== this._planPresentationGeneration ||
+            modeGeneration !== this._interactivePermissionModeGeneration;
+        const decision = await defaultPlanPresenter.present(plan, ctx, signal);
+        if (obsolete())
+            throw new Error("Plan approval was cancelled because its dialog is obsolete.");
+        if (!decision.approved)
+            return decision;
+        if (!this._permissionGate)
+            throw new Error("Cannot apply the approved plan mode without a permission gate.");
+        const resolution = await this._setInteractivePermissionMode(decision.nextMode, () => !signal?.aborted && this._lifecycle !== "closed" && generation === this._planPresentationGeneration);
+        if (signal?.aborted ||
+            generation !== this._planPresentationGeneration ||
+            modeGeneration + 1 !== this._interactivePermissionModeGeneration ||
+            resolution?.mode !== decision.nextMode ||
+            resolution.origin !== "interactive")
+            throw new Error("Plan approval was cancelled because its dialog is obsolete.");
+        return decision;
     }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
@@ -1483,7 +1609,7 @@ export class AgentSession {
      * {@link _installAgentForcedPromptProjection}.
      */
     _preparePromptAndToolLoadout(options, messages = this.agent.state.messages) {
-        options.selectedTools = [...new Set(options.selectedTools)].filter((name) => this._toolRegistry.has(name));
+        options.selectedTools = this._projectToolNames(options.selectedTools);
         this.agent.state.tools = options.selectedTools.flatMap((name) => {
             const tool = this._toolRegistry.get(name);
             return tool ? [tool] : [];
@@ -1523,14 +1649,13 @@ export class AgentSession {
         const current = getCurrentSystemMessage(this.sessionManager.buildSessionContext().messages);
         if (!current)
             return;
-        const toolNames = (current.toolsAdded ?? [])
+        const explicitPlanTool = this._requestedToolNames.includes("plan_present");
+        this._requestedToolNames = (current.toolsAdded ?? [])
             .map((tool) => tool.name)
-            .filter((name) => this._toolRegistry.has(name));
-        this.agent.state.tools = toolNames.flatMap((name) => {
-            const registered = this._toolRegistry.get(name);
-            return registered ? [registered] : [];
-        });
-        this._rebuildSystemPrompt(toolNames);
+            .filter((name) => this._toolRegistry.has(name) && (name !== "plan_present" || explicitPlanTool));
+        if (explicitPlanTool && !this._requestedToolNames.includes("plan_present"))
+            this._requestedToolNames.push("plan_present");
+        this._applyRequestedTools();
     }
     // =========================================================================
     // Prompting
@@ -1558,6 +1683,8 @@ export class AgentSession {
             if (this._agentRunAbortRequested)
                 this._finishCancelledRetry();
             this._runSystemPromptOptions = undefined;
+            this._runRequestedToolNames = undefined;
+            this._applyRequestedTools();
             this._flushPendingBashMessages();
             this._flushPendingCustomMessages();
             await this._emitAgentSettled();
@@ -1768,6 +1895,7 @@ export class AgentSession {
             if (lastAssistant) {
                 await this._checkCompaction(lastAssistant, false);
             }
+            await this._syncPlanToolMode();
             // Emit before_agent_start before normalizing images so extension-driven model
             // selection determines the resize profile used for the request and history.
             const selectedToolsBefore = this._baseSystemPromptOptions.selectedTools;
@@ -1777,8 +1905,11 @@ export class AgentSession {
             // loadout is authoritative, so a setActiveTools() call is not undone here.
             const handlerEditedTools = result.systemPromptOptions.selectedTools.length !== selectedToolsBefore.length ||
                 result.systemPromptOptions.selectedTools.some((name, index) => name !== selectedToolsBefore[index]);
-            if (!handlerEditedTools)
-                result.systemPromptOptions.selectedTools = this.getActiveToolNames();
+            const inheritedImplicitPlanTool = selectedToolsBefore.includes("plan_present") && !this._requestedToolNames.includes("plan_present");
+            this._runRequestedToolNames = handlerEditedTools
+                ? result.systemPromptOptions.selectedTools.filter((name) => name !== "plan_present" || !inheritedImplicitPlanTool)
+                : undefined;
+            result.systemPromptOptions.selectedTools = this._projectToolNames(this._runRequestedToolNames ?? this._requestedToolNames);
             const normalized = await this._normalizePromptImages(currentImages);
             const userText = normalized.hints.length > 0 ? `${expandedText}\n\n${normalized.hints.join("\n")}` : expandedText;
             // Build messages only after hooks and image normalization have completed.
@@ -2108,6 +2239,8 @@ export class AgentSession {
      * Abort current operation and wait for agent to become idle.
      */
     async abort() {
+        this._planPresentationGeneration++;
+        this._interactivePermissionModeGeneration++;
         if (this._activePrompt && this._lifecycle !== "closed")
             this._lifecycle = "interrupted";
         if (this._isAgentRunActive) {
@@ -2152,9 +2285,60 @@ export class AgentSession {
     async getPermissionMode() {
         if (!this._permissionGate)
             return undefined;
+        if (this._interactivePermissionMode !== undefined) {
+            return { mode: this._interactivePermissionMode, origin: "interactive" };
+        }
         const snapshot = await this._permissionGate.store.snapshot();
+        if (this._interactivePermissionMode !== undefined) {
+            return { mode: this._interactivePermissionMode, origin: "interactive" };
+        }
         return resolveEffectiveModeWithOrigin(this._permissionGate.flagMode, snapshot.modesBySource);
     }
+    getInteractivePermissionMode() {
+        return this._interactivePermissionMode;
+    }
+    async getInteractivePermissionModeCycle() {
+        if (!this._permissionGate)
+            return [];
+        const modes = ["default", "acceptEdits", "plan"];
+        const startup = await this._startupPermissionMode;
+        if (startup?.ok === false)
+            throw startup.error;
+        if (startup?.mode === "bypassPermissions")
+            modes.push("bypassPermissions");
+        return modes;
+    }
+    async setInteractivePermissionMode(mode) {
+        return this._setInteractivePermissionMode(mode);
+    }
+    async _setInteractivePermissionMode(mode, canApply) {
+        if (!this._permissionGate)
+            return undefined;
+        const generation = ++this._interactivePermissionModeGeneration;
+        const startup = await this._startupPermissionMode;
+        if (startup?.ok === false)
+            throw startup.error;
+        if (generation !== this._interactivePermissionModeGeneration)
+            return this.getPermissionMode();
+        if (mode === "bypassPermissions" && startup?.mode !== "bypassPermissions") {
+            throw new Error("Interactive bypassPermissions requires a session that started with bypassPermissions.");
+        }
+        if (canApply && !canApply())
+            throw new Error("Plan approval was cancelled because its dialog is obsolete.");
+        this._interactivePermissionMode = mode;
+        this._planToolSyncGeneration++;
+        this._planToolMode = mode;
+        this._applyRequestedTools();
+        this._setPendingPlanToolSync();
+        return { mode, origin: "interactive" };
+    }
+    clearInteractivePermissionMode() {
+        this._interactivePermissionModeGeneration++;
+        this._interactivePermissionMode = undefined;
+        this._planToolMode = undefined;
+        this._applyRequestedTools();
+        this._schedulePlanToolSync();
+    }
     /**
      * Persist a permission mode to user scope (`~/.apex-code/agent/permissions.json`).
      * Returns the resolution that is actually in force afterwards, which is *not*
@@ -2165,6 +2349,7 @@ export class AgentSession {
         if (!this._permissionGate)
             return undefined;
         await this._permissionGate.store.apply({ type: "setMode", destination: "user", mode });
+        await this._syncPlanToolMode();
         return this.getPermissionMode();
     }
     /**
@@ -3095,6 +3280,7 @@ export class AgentSession {
     }
     async bindExtensions(bindings) {
         if (bindings.uiContext !== undefined) {
+            this._planPresentationGeneration++;
             this._extensionUIContext = bindings.uiContext;
         }
         if (bindings.mode !== undefined) {
@@ -3293,7 +3479,7 @@ export class AgentSession {
     }
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
-        const previousActiveToolNames = this.getActiveToolNames();
+        const previousActiveToolNames = this._requestedToolNames;
         const allowedToolNames = this._allowedToolNames;
         const excludedToolNames = this._excludedToolNames;
         const isAllowedTool = (name) => (!allowedToolNames || allowedToolNames.has(name)) && !excludedToolNames?.has(name);
@@ -3374,7 +3560,8 @@ export class AgentSession {
         if (hasDeferredActiveTool && this._toolRegistry.has("tool_schema")) {
             nextActiveToolNames.push("tool_schema");
         }
-        this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
+        this._requestedToolNames = [...new Set(nextActiveToolNames)].filter((name) => this._toolRegistry.has(name));
+        this._applyRequestedTools();
     }
     _buildRuntime(options) {
         const autoResizeImages = this.settingsManager.getImageAutoResize();
@@ -3409,6 +3596,9 @@ export class AgentSession {
                 this._loadedDeferredSchemas.add(name);
             },
         });
+        baseToolDefinitions.plan_present = createPlanPresentToolDefinition({
+            present: (plan, ctx, signal) => this._presentPlan(plan, ctx, signal),
+        });
         baseToolDefinitions.todo_write = createTodoWriteToolDefinition({
             write: (todos) => {
                 this.sessionManager.appendCustomEntry(TODO_CUSTOM_ENTRY_TYPE, todos);
@@ -3433,11 +3623,10 @@ export class AgentSession {
         }
         this._bindExtensionCore(this._extensionRunner);
         this._applyExtensionBindings(this._extensionRunner);
-        const defaultActiveToolNames = this._baseToolsOverride
-            ? Object.keys(this._baseToolsOverride)
-            : this._lspOperations
-                ? ["read", "bash", "edit", "write", "lsp"]
-                : ["read", "bash", "edit", "write"];
+        const defaultActiveToolNames = configuredDefaultToolNames({
+            baseNames: this._baseToolsOverride ? Object.keys(this._baseToolsOverride) : undefined,
+            lsp: Boolean(this._lspOperations),
+        });
         const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
         this._refreshToolRegistry({
             activeToolNames: baseActiveToolNames,
@@ -3445,6 +3634,8 @@ export class AgentSession {
         });
     }
     async reload(options) {
+        this._planPresentationGeneration++;
+        this.clearInteractivePermissionMode();
         const oldRunner = this._extensionRunner;
         const previousFlagValues = oldRunner.getFlagValues();
         await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
@@ -3454,7 +3645,7 @@ export class AgentSession {
         resetApiProviders();
         await this._resourceLoader.reload();
         this._buildRuntime({
-            activeToolNames: this.getActiveToolNames(),
+            activeToolNames: this._requestedToolNames,
             flagValues: previousFlagValues,
             includeAllExtensionTools: true,
         });
@@ -3519,6 +3710,7 @@ export class AgentSession {
             success: false,
             attempt,
             finalError: "Retry cancelled",
+            aborted: true,
         });
     }
     /**
@@ -3868,51 +4060,63 @@ export class AgentSession {
             this._resolveIdleWaitIfIdle();
         }
     }
-    /**
-     * WS.6: resolve what navigation may do to the workspace before the
-     * conversation moves. `keep` never touches files; `restore` overwrites
-     * only through the engine's pinned pre-restore checkpoint; `fail-if-
-     * drifted` and `cancel` refuse when the workspace moved; a missing
-     * checkpoint leaves the workspace unchanged and says so. Never throws.
-     */
-    async _resolveTreeWorkspaceStep(targetId, policy) {
-        const unchanged = { policy, outcome: "unchanged", warnings: [] };
-        if (policy === "keep")
-            return { outcome: unchanged };
+    async previewTreeWorkspace(targetId) {
+        const inspection = await this._inspectTreeWorkspace(targetId);
+        return inspection.state === "unavailable"
+            ? { state: inspection.state, reason: inspection.reason }
+            : { state: inspection.state };
+    }
+    async _inspectTreeWorkspace(targetId) {
         try {
             const engine = await this._checkpoints.engine();
             if (!engine) {
                 return {
-                    outcome: {
-                        policy,
-                        outcome: "missing-checkpoint",
-                        warnings: ["checkpoints are unavailable; workspace left unchanged"],
-                    },
+                    state: "unavailable",
+                    reason: "checkpoints are unavailable; workspace left unchanged",
+                    navigationOutcome: "missing-checkpoint",
                 };
             }
             const checkpoint = await engine.lookup(targetId);
             if (!checkpoint)
-                return { outcome: { policy, outcome: "missing-checkpoint", warnings: [] } };
+                return { state: "no-checkpoint" };
             const matches = await engine.matchesWorktree(checkpoint);
             if (matches === undefined) {
                 return {
-                    outcome: {
-                        policy,
-                        outcome: "failed",
-                        warnings: ["could not compare the workspace against the checkpoint"],
-                    },
+                    state: "unavailable",
+                    reason: "could not compare the workspace against the checkpoint",
+                    navigationOutcome: "failed",
                 };
             }
-            if (matches)
-                return { outcome: unchanged };
-            if (policy === "fail-if-drifted" || policy === "cancel") {
-                return { cancelled: true, outcome: { policy, outcome: "refused-drifted", warnings: [] } };
-            }
-            const preRestore = await engine.restore(checkpoint);
+            return { state: matches ? "matches" : "differs", engine, checkpoint };
+        }
+        catch (error) {
+            return {
+                state: "unavailable",
+                reason: `workspace policy check failed: ${error instanceof Error ? error.message : String(error)}`,
+                navigationOutcome: "failed",
+            };
+        }
+    }
+    async _resolveTreeWorkspaceStep(targetId, policy) {
+        const unchanged = { policy, outcome: "unchanged", warnings: [] };
+        if (policy === "keep")
+            return { outcome: unchanged };
+        const inspection = await this._inspectTreeWorkspace(targetId);
+        if (inspection.state === "no-checkpoint") {
+            return { outcome: { policy, outcome: "missing-checkpoint", warnings: [] } };
+        }
+        if (inspection.state === "unavailable") {
+            return { outcome: { policy, outcome: inspection.navigationOutcome, warnings: [inspection.reason] } };
+        }
+        if (inspection.state === "matches")
+            return { outcome: unchanged };
+        if (policy === "fail-if-drifted" || policy === "cancel") {
+            return { cancelled: true, outcome: { policy, outcome: "refused-drifted", warnings: [] } };
+        }
+        try {
+            const preRestore = await inspection.engine.restore(inspection.checkpoint);
             if (!preRestore) {
-                return {
-                    outcome: { policy, outcome: "failed", warnings: ["restore failed; workspace left unchanged"] },
-                };
+                return { outcome: { policy, outcome: "failed", warnings: ["restore failed; workspace left unchanged"] } };
             }
             return {
                 outcome: {