@bastani/atomic 0.8.27 → 0.8.28-alpha.2

package/dist/core/agent-session.js

@@ -20,9 +20,9 @@ import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
 import { sleep } from "../utils/sleep.js";
 import { ATOMIC_GUIDE_COMMAND_NAME, ATOMIC_GUIDE_HELP_CHOICES, atomicGuideModeForChoice, getAtomicGuideMessage, isAtomicGuideHelpChoice, normalizeAtomicGuideMode, } from "./atomic-guide-command.js";
-import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
+import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage, formatUnresolvedModelMessage, } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, contextCompact as runContextCompact, estimateContextTokens, generateBranchSummary, prepareContextCompaction, shouldCompact, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, contextCompact as runContextCompact, estimateContextTokens, generateBranchSummary, prepareContextCompaction, shouldCompact, validateContextDeletionRequest, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
@@ -34,7 +34,17 @@ import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { createAllToolDefinitions, defaultToolNames } from "./tools/index.js";
+import { redirectOversizedToolResult } from "./tools/oversized-tool-result.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        Object.freeze(value);
+        for (const nested of Object.values(value)) {
+            deepFreeze(nested);
+        }
+    }
+    return value;
+}
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -149,6 +159,7 @@ export class AgentSession {
         this._pendingBashMessages = [];
         this._turnIndex = 0;
         this._baseToolDefinitions = new Map();
+        this._extensionMode = "print";
         // Tool registry for extension getTools/setTools
         this._toolRegistry = new Map();
         this._toolDefinitions = new Map();
@@ -253,26 +264,43 @@ export class AgentSession {
         };
         this.agent.afterToolCall = async ({ toolCall, args, result, isError }) => {
             const runner = this._extensionRunner;
-            if (!runner.hasHandlers("tool_result")) {
-                return undefined;
-            }
-            const hookResult = await runner.emitToolResult({
-                type: "tool_result",
+            const hookResult = runner.hasHandlers("tool_result")
+                ? await runner.emitToolResult({
+                    type: "tool_result",
+                    toolName: toolCall.name,
+                    toolCallId: toolCall.id,
+                    input: args,
+                    content: result.content,
+                    details: result.details,
+                    isError,
+                })
+                : undefined;
+            const extensionReplacement = hookResult
+                ? {
+                    content: hookResult.content,
+                    details: hookResult.details,
+                    isError: hookResult.isError ?? isError,
+                }
+                : undefined;
+            const finalResult = hookResult
+                ? {
+                    content: hookResult.content ?? result.content,
+                    // Preserve original details when an extension hook rewrites only content;
+                    // the redirect check only replaces model-visible content blocks.
+                    details: hookResult.details ?? result.details,
+                }
+                : result;
+            const finalIsError = hookResult?.isError ?? isError;
+            const redirectReplacement = await redirectOversizedToolResult({
                 toolName: toolCall.name,
                 toolCallId: toolCall.id,
-                input: args,
-                content: result.content,
-                details: result.details,
-                isError,
+                result: finalResult,
+                isError: finalIsError,
+                sessionId: this.sessionManager.getSessionId(),
+                sessionDir: this.sessionManager.getSessionDir() || undefined,
+                maxResultSizeChars: this.getToolDefinition(toolCall.name)?.maxResultSizeChars,
             });
-            if (!hookResult) {
-                return undefined;
-            }
-            return {
-                content: hookResult.content,
-                details: hookResult.details,
-                isError: hookResult.isError ?? isError,
-            };
+            return redirectReplacement ?? extensionReplacement;
         };
     }
     // =========================================================================
@@ -357,7 +385,7 @@ export class AgentSession {
                 // Regular LLM message - persist as SessionMessageEntry
                 this.sessionManager.appendMessage(event.message);
             }
-            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
+            // Other message types (bashExecution, branchSummary) are persisted elsewhere
             // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
                 this._lastAssistantMessage = event.message;
@@ -624,6 +652,7 @@ export class AgentSession {
             name: definition.name,
             description: definition.description,
             parameters: definition.parameters,
+            promptGuidelines: definition.promptGuidelines,
             sourceInfo,
         }));
     }
@@ -788,7 +817,7 @@ export class AgentSession {
             let currentText = text;
             let currentImages = options?.images;
             if (this._extensionRunner.hasHandlers("input")) {
-                const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive");
+                const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive", this.isStreaming ? options?.streamingBehavior : undefined);
                 if (inputResult.action === "handled") {
                     preflightResult?.(true);
                     return;
@@ -824,6 +853,15 @@ export class AgentSession {
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
+            // Defensive guard: a model that never resolved to a real provider
+            // (for example an unknown/unresolved model id that reached this path
+            // as a bare string) has no `provider`, which would otherwise fail deep
+            // in auth resolution as the confusing "No API key found for undefined".
+            // Surface a clear, accurate "unknown model" error instead.
+            const resolvedProvider = this.model.provider;
+            if (typeof resolvedProvider !== "string" || resolvedProvider.length === 0) {
+                throw new Error(formatUnresolvedModelMessage(this.model));
+            }
             if (!this._modelRegistry.hasConfiguredAuth(this.model)) {
                 const isOAuth = this._modelRegistry.isUsingOAuth(this.model);
                 if (isOAuth) {
@@ -887,8 +925,20 @@ export class AgentSession {
             return;
         }
         preflightResult?.(true);
+        await this._runAgentPrompt(messages);
+    }
+    async _runAgentPrompt(messages) {
         await this.agent.prompt(messages);
         await this.waitForRetry();
+        await this._continueQueuedAgentMessages();
+    }
+    async _continueQueuedAgentMessages() {
+        await this._agentEventQueue;
+        while (this.agent.hasQueuedMessages()) {
+            await this.agent.continue();
+            await this.waitForRetry();
+            await this._agentEventQueue;
+        }
     }
     /**
      * Try to execute a built-in slash command. Returns true if command was found and executed.
@@ -1092,7 +1142,7 @@ export class AgentSession {
             this._queueAgentMessage(appMessage, options?.deliverAs === "followUp" ? "followUp" : "steer");
         }
         else if (options?.triggerTurn) {
-            await this.agent.prompt(appMessage);
+            await this._runAgentPrompt(appMessage);
         }
         else {
             this._appendCustomMessage(appMessage);
@@ -1483,6 +1533,9 @@ export class AgentSession {
         if (!this.model) {
             throw new Error(formatNoModelSelectedMessage());
         }
+        // Capture the narrowed model now (control-flow narrowing holds immediately after the
+        // guard) so the lazy planner-fallback closure below can use a non-undefined model.
+        const model = this.model;
         const pathEntries = this.sessionManager.getBranch();
         const settings = this.settingsManager.getCompactionSettings();
         const mode = options.mode ?? "standard";
@@ -1490,28 +1543,118 @@ export class AgentSession {
         if (!preparation) {
             return undefined;
         }
-        const validated = await runContextCompact(preparation, this.model, options.apiKey, options.headers, options.abortController.signal, this.thinkingLevel, mode);
+        // Planner fallback used when no extension supplies a deletionRequest. Auth is resolved
+        // lazily here so extension-provided deletion requests keep working offline. Returns
+        // undefined when auth is unavailable (auto-mode resolvers), signaling a no-op compaction.
+        const runPlanner = async () => {
+            const auth = await options.resolvePlannerAuth();
+            if (!auth)
+                return undefined;
+            return runContextCompact(preparation, model, auth.apiKey, auth.headers, options.abortController.signal, this.thinkingLevel, mode);
+        };
+        // Emit session_before_compact to allow extensions to cancel or provide a deletion request.
+        // This happens BEFORE any auth resolution so local extension deletion requests work
+        // without configured API credentials.
+        let fromExtension = false;
+        let validated;
+        if (this._extensionRunner.hasHandlers("session_before_compact")) {
+            // Deep-clone the preparation only when a before-compact handler actually exists. Extensions
+            // receive an isolated, frozen snapshot so they cannot mutate protection metadata
+            // (protectedEntryIds, entry .protected flags, etc.) on the internal preparation used for
+            // validation. Building it lazily avoids deep-cloning the transcript — largest exactly when
+            // compaction fires — on the common no-extension path.
+            let extensionPreparation;
+            try {
+                extensionPreparation = deepFreeze(structuredClone(preparation));
+            }
+            catch (error) {
+                // structuredClone only throws if an entry carries a non-cloneable value (a function or a
+                // class instance). Transcript entries are plain data today, so this guards a latent
+                // invariant: surface a clear error instead of letting a raw DataCloneError abort an
+                // otherwise-viable compaction.
+                throw new Error(`Failed to snapshot transcript for compaction extensions: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const hookResult = (await this._extensionRunner.emit({
+                type: "session_before_compact",
+                reason: options.reason,
+                mode,
+                preparation: extensionPreparation,
+                branchEntries: pathEntries,
+                signal: options.abortController.signal,
+            }));
+            if (hookResult?.cancel) {
+                throw new Error("Compaction cancelled");
+            }
+            if (hookResult?.deletionRequest) {
+                const extensionDeletionRequest = hookResult.deletionRequest;
+                // Reject empty deletion requests before any side effects (backup, append, rebuild).
+                if (!Array.isArray(extensionDeletionRequest.deletions) || extensionDeletionRequest.deletions.length === 0) {
+                    throw new Error("No safe context deletions proposed by extension");
+                }
+                // Validate against the internal transcript snapshot, not the extension-facing clone.
+                // Auth is NOT resolved here — local extension deletion requests work offline.
+                validated = validateContextDeletionRequest(extensionDeletionRequest, preparation.transcript, { mode });
+                // Reject if reconciliation reduced deletions to zero.
+                if (validated.deletedTargets.length === 0) {
+                    throw new Error("No safe context deletions proposed by extension");
+                }
+                fromExtension = true;
+            }
+        }
+        // Planner fallback shared by both paths: no before-compact handler at all, or a handler that
+        // observed without supplying a deletionRequest. Resolves auth lazily; undefined means auth is
+        // unavailable (auto-mode resolvers), so compaction is a no-op.
+        if (!validated) {
+            const plannerResult = await runPlanner();
+            if (!plannerResult) {
+                return undefined;
+            }
+            validated = plannerResult;
+        }
         if (options.abortController.signal.aborted) {
             throw new Error("Compaction cancelled");
         }
         const backupPath = this.sessionManager.writeBackupSnapshot(options.backupLabel);
-        this.sessionManager.appendContextCompaction(validated.deletedTargets, validated.protectedEntryIds, validated.stats, backupPath);
+        const compactionEntryId = this.sessionManager.appendContextCompaction(validated.deletedTargets, validated.protectedEntryIds, validated.stats, backupPath);
         const sessionContext = this.sessionManager.buildSessionContext();
         this.agent.state.messages = sessionContext.messages;
-        return {
+        const result = {
             ...validated,
             promptVersion: 1,
             ...(backupPath ? { backupPath } : {}),
         };
+        // Emit session_compact so extensions can observe the validated result. This is a pure
+        // observation hook fired AFTER the compaction has been committed (backup written,
+        // context_compaction entry persisted, active context rebuilt). A misbehaving observer must
+        // never turn a successful, already-persisted compaction into a reported failure, so any
+        // throw is routed to the non-fatal extension-error channel and compaction still reports
+        // success.
+        const contextCompactionEntry = this.sessionManager.getEntry(compactionEntryId);
+        try {
+            await this._extensionRunner.emit({
+                type: "session_compact",
+                reason: options.reason,
+                mode,
+                result,
+                contextCompactionEntry,
+                fromExtension,
+            });
+        }
+        catch (error) {
+            this._extensionRunner.emitError({
+                extensionPath: "<session_compact>",
+                event: "session_compact",
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+        }
+        return result;
     }
     /**
      * Manually compact the session context using deletion-only verbatim context compaction.
-     * Aborts current agent operation first. Custom summary instructions are not accepted.
+     * Aborts current agent operation first.
      */
-    async compact(customInstructions) {
-        if (customInstructions?.trim()) {
-            throw new Error("Custom compaction instructions are not supported; use /compact without arguments");
-        }
+    async compact() {
         this._disconnectFromAgent();
         await this.abort();
         this._compactionAbortController = new AbortController();
@@ -1520,12 +1663,14 @@ export class AgentSession {
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
-            const { apiKey, headers } = await this._getRequiredRequestAuth(this.model);
+            // Auth is resolved lazily: only called when the planner fallback is needed.
+            // Extensions that provide a deletionRequest work without configured credentials.
+            const model = this.model;
             const result = await this._applyContextVerbatimCompaction({
-                apiKey,
-                headers,
+                resolvePlannerAuth: () => this._getRequiredRequestAuth(model),
                 abortController: this._compactionAbortController,
                 backupLabel: "compact",
+                reason: "manual",
             });
             if (!result) {
                 throw new Error("Nothing to compact (session too small)");
@@ -1570,12 +1715,14 @@ export class AgentSession {
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
-            const { apiKey, headers } = await this._getRequiredRequestAuth(this.model);
+            // Auth is resolved lazily: only called when the planner fallback is needed.
+            // Extensions that provide a deletionRequest work without configured credentials.
+            const model = this.model;
             const result = await this._applyContextVerbatimCompaction({
-                apiKey,
-                headers,
+                resolvePlannerAuth: () => this._getRequiredRequestAuth(model),
                 abortController: this._compactionAbortController,
                 backupLabel: "context-compact",
+                reason: "manual",
             });
             if (!result) {
                 throw new Error("Nothing to context-compact (session too small)");
@@ -1754,23 +1901,24 @@ export class AgentSession {
                 });
                 return;
             }
-            const authResult = await this._modelRegistry.getApiKeyAndHeaders(this.model);
-            if (!authResult.ok || !authResult.apiKey) {
-                this._emit({
-                    type: "compaction_end",
-                    reason,
-                    result: undefined,
-                    aborted: false,
-                    willRetry: false,
-                });
-                return;
-            }
+            // Auth is resolved lazily: only called when the planner fallback is needed.
+            // This allows extension-provided deletion requests to run before auth is checked,
+            // enabling local extension compaction even when API credentials are unavailable.
+            // Auto-mode resolver returns undefined (rather than throwing) when auth is missing,
+            // so compaction silently no-ops if the planner would be needed but credentials are absent.
+            const model = this.model;
             const result = await this._applyContextVerbatimCompaction({
-                apiKey: authResult.apiKey,
-                headers: authResult.headers,
+                resolvePlannerAuth: async () => {
+                    const authResult = await this._modelRegistry.getApiKeyAndHeaders(model);
+                    if (!authResult.ok || !authResult.apiKey) {
+                        return undefined;
+                    }
+                    return { apiKey: authResult.apiKey, headers: authResult.headers };
+                },
                 abortController: this._autoCompactionAbortController,
                 backupLabel: reason === "overflow" ? "overflow-auto-compact" : "auto-compact",
                 mode: reason === "overflow" ? "critical_overflow" : "standard",
+                reason,
             });
             if (!result) {
                 this._emit({
@@ -1822,6 +1970,9 @@ export class AgentSession {
         if (bindings.uiContext !== undefined) {
             this._extensionUIContext = bindings.uiContext;
         }
+        if (bindings.mode !== undefined) {
+            this._extensionMode = bindings.mode;
+        }
         if (bindings.commandContextActions !== undefined) {
             this._extensionCommandContextActions = bindings.commandContextActions;
         }
@@ -1876,7 +2027,7 @@ export class AgentSession {
         return `extension:${name}`;
     }
     _applyExtensionBindings(runner) {
-        runner.setUIContext(this._extensionUIContext);
+        runner.setUIContext(this._extensionUIContext, this._extensionMode);
         runner.bindCommandContext(this._extensionCommandContextActions);
         this._extensionErrorUnsubscriber?.();
         this._extensionErrorUnsubscriber = this._extensionErrorListener
@@ -1964,6 +2115,7 @@ export class AgentSession {
         }, {
             getModel: () => this.model,
             isIdle: () => !this.isStreaming,
+            isProjectTrusted: () => this.settingsManager.isProjectTrusted(),
             getSignal: () => this.agent.signal,
             abort: () => this.abort(),
             hasPendingMessages: () => this.pendingMessageCount > 0,
@@ -1974,7 +2126,7 @@ export class AgentSession {
             compact: (options) => {
                 void (async () => {
                     try {
-                        const result = await this.compact(options?.customInstructions);
+                        const result = await this.compact();
                         options?.onComplete?.(result);
                     }
                     catch (error) {
@@ -1984,6 +2136,7 @@ export class AgentSession {
                 })();
             },
             getSystemPrompt: () => this.systemPrompt,
+            getSystemPromptOptions: () => this._baseSystemPromptOptions,
         }, {
             registerProvider: (name, config) => {
                 this._modelRegistry.registerProvider(name, config);
@@ -2442,6 +2595,7 @@ export class AgentSession {
                     customInstructions,
                     replaceInstructions,
                     reserveTokens: branchSummarySettings.reserveTokens,
+                    streamFn: this.agent.streamFn,
                 });
                 if (result.aborted) {
                     return { cancelled: true, aborted: true };