@hoilab/ada-cli 0.85.0 → 0.85.3

package/dist/core/agent-session.d.ts

@@ -14,6 +14,7 @@
  */
 import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { ImageContent, Model, TextContent } from "@earendil-works/pi-ai/compat";
+import { AsidesBuffer } from "./banco/asides.ts";
 import { type BashResult } from "./bash-executor.ts";
 import { type CompactionResult } from "./compaction/index.ts";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, type ExtensionMode, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
@@ -232,6 +233,8 @@ export declare class AgentSession {
     private _followUpMessages;
     /** Messages queued to be included with the next user prompt as context ("asides"). */
     private _pendingNextTurnMessages;
+    /** Buffer para asides no interruptores: se acumulan y se drenan al final del turno. */
+    private _asidesBuffer;
     private _compactionAbortController;
     private _autoCompactionAbortController;
     private _overflowRecoveryAttempted;
@@ -305,6 +308,7 @@ export declare class AgentSession {
     private _confirmWorkflowLaunch;
     /** Respuesta a una confirmación pendiente (la UI la llama). */
     resolveWorkflowConfirmation(prompt: string, ok: boolean): boolean;
+    /** Si hay un goal activo aprobado, avanza un turno del bucle. */
     private _maybeContinueGoal;
     /**
      * Replace vault-expanded secrets with the redacted form for UI events and
@@ -330,6 +334,7 @@ export declare class AgentSession {
     /** Find the last assistant message in agent state (including aborted ones) */
     private _findLastAssistantMessage;
     private _replaceMessageInPlace;
+    /** Emit extension events based on agent events */
     private _emitExtensionEvent;
     /**
      * Subscribe to agent events.
@@ -421,6 +426,9 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
+    /**
+     * Try to execute an extension command. Returns true if command was found and executed.
+     */
     private _tryExecuteExtensionCommand;
     /**
      * Expand skill commands (/skill:name args) to their full content.
@@ -445,7 +453,13 @@ export declare class AgentSession {
      * @throws Error if text is an extension command
      */
     followUp(text: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Internal: Queue a steering message (already expanded, no extension command check).
+     */
     private _queueSteer;
+    /**
+     * Internal: Queue a follow-up message (already expanded, no extension command check).
+     */
     private _queueFollowUp;
     /**
      * Throw an error if the text is an extension command.
@@ -479,6 +493,10 @@ export declare class AgentSession {
         deliverAs?: "steer" | "followUp";
         expandPromptTemplates?: boolean;
     }): Promise<void>;
+    /**
+     * Ejecuta el optimizador con el modelo de la sesión. Timeout de 12s,
+     * nunca lanza (devuelve undefined → fail-open).
+     */
     private _runPromptOptimizer;
     /** Últimos prompts de usuario (para dar contexto al optimizador). */
     private _recentUserPrompts;
@@ -558,6 +576,7 @@ export declare class AgentSession {
      * Saves to settings.
      */
     setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
     private _runDefaultCompaction;
     /**
      * Manually compact the session context.
@@ -583,7 +602,38 @@ export declare class AgentSession {
      * Cancel in-progress branch summarization.
      */
     abortBranchSummary(): void;
+    /**
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
+     *
+     * Automatic cases:
+     * 1. Overflow with retry: a context-overflow error or recoverable length stop;
+     *    remove the failed assistant message, compact, and retry the turn once.
+     * 2. Overflow without retry: a successful response exceeded the configured
+     *    context window; compact but preserve the completed response.
+     * 3. Threshold without retry: valid or estimated context usage crossed the
+     *    configured threshold; compact without retrying the completed response.
+     *
+     * Each case calls `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, that method calls the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
+     */
     private _checkCompaction;
+    /**
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts` after preparation and extension
+     * interception.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
+     */
     private _runAutoCompaction;
     /**
      * Toggle auto-compaction setting.
@@ -615,6 +665,10 @@ export declare class AgentSession {
      * the TUI needs to render the retry and recreate the underlying indicator.
      */
     private _summarizationRetryCallbacks;
+    /**
+     * Prepare a retryable error for continuation with exponential backoff.
+     * @returns true if the caller should continue the agent, false otherwise
+     */
     private _prepareRetry;
     /**
      * Cancel in-progress retry.
@@ -662,6 +716,19 @@ export declare class AgentSession {
      * Called after agent turn completes to maintain proper message ordering.
      */
     private _flushPendingBashMessages;
+    /** Buffer vivo de asides; útil para tests y para inyección externa. */
+    get asidesBuffer(): AsidesBuffer;
+    /** ¿Hay asides pendientes de drenar? */
+    get hasPendingAsides(): boolean;
+    /** Acumula un aside sin interrumpir tools en vuelo. */
+    pushAside(text: string): void;
+    /** Acumula asides extraídos de un texto con marcas `<aside>`. */
+    pushAsidesFromText(text: string): number;
+    /**
+     * Drena todos los asides acumulados hasta ahora. Se llama al final del
+     * turno para inyectarlos como mensajes laterales; no cuenta como tool.
+     */
+    drainAsides(): string[];
     /**
      * Set a display name for the current session.
      */