@bastani/atomic 0.8.27-alpha.1 → 0.8.28-alpha.1

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";
@@ -35,6 +35,15 @@ import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { createAllToolDefinitions, defaultToolNames } from "./tools/index.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.
@@ -357,7 +366,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;
@@ -824,6 +833,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) {
@@ -1483,6 +1501,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 +1511,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 +1631,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 +1683,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 +1869,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({
@@ -1974,7 +2090,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) {