@vybestack/llxprt-code-core 0.4.8 → 0.5.0-nightly.251102.e5b51aa3

package/dist/src/core/subagent.d.ts

@@ -4,7 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Config } from '../config/config.js';
-import { Content, FunctionDeclaration } from '@google/genai';
+import { Content, Part, FunctionDeclaration } from '@google/genai';
+import type { AgentRuntimeContext, ReadonlySettingsSnapshot } from '../runtime/AgentRuntimeContext.js';
+import type { AgentRuntimeLoaderResult } from '../runtime/AgentRuntimeLoader.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import type { SubagentSchedulerFactory } from './subagentScheduler.js';
 /**
  * @fileoverview Defines the configuration interfaces for a subagent.
  *
@@ -44,6 +48,10 @@ export interface OutputObject {
      * during its execution. These variables can be used by the calling agent.
      */
     emitted_vars: Record<string, string>;
+    /**
+     * The final natural language response produced by the subagent (if any).
+     */
+    final_message?: string;
     /**
      * The reason for the subagent's termination, indicating whether it completed
      * successfully, timed out, or encountered an error.
@@ -85,6 +93,12 @@ export interface OutputConfig {
      */
     outputs: Record<string, string>;
 }
+export interface SubAgentRuntimeOverrides {
+    settingsSnapshot?: ReadonlySettingsSnapshot;
+    toolRegistry?: ToolRegistry;
+    environmentContextLoader?: (runtime: AgentRuntimeContext) => Promise<Part[]>;
+    runtimeBundle?: AgentRuntimeLoaderResult;
+}
 /**
  * Configures the generative model parameters for the subagent.
  * This interface specifies the model to be used and its associated generation settings,
@@ -155,53 +169,97 @@ export declare class ContextState {
  * Represents the scope and execution environment for a subagent.
  * This class orchestrates the subagent's lifecycle, managing its chat interactions,
  * runtime context, and the collection of its outputs.
+ *
+ * @plan PLAN-20251028-STATELESS6.P08
+ * @requirement REQ-STAT6-001.1, REQ-STAT6-001.2, REQ-STAT6-003.1, REQ-STAT6-003.2
+ * @pseudocode agent-runtime-context.md line 93 (step 007.1)
  */
 export declare class SubAgentScope {
     readonly name: string;
-    readonly runtimeContext: Config;
-    private readonly promptConfig;
+    readonly runtimeContext: AgentRuntimeContext;
     private readonly modelConfig;
     private readonly runConfig;
+    private readonly promptConfig;
+    private readonly contentGenerator;
+    private readonly toolExecutorContext;
+    private readonly environmentContextLoader;
+    private readonly config;
     private readonly toolConfig?;
     private readonly outputConfig?;
     output: OutputObject;
     private readonly subagentId;
+    private readonly logger;
+    private readonly textToolParser;
+    private activeAbortController;
     /** Optional callback for streaming text messages during execution */
     onMessage?: (message: string) => void;
     /**
      * Constructs a new SubAgentScope instance.
+     *
+     * @plan PLAN-20251028-STATELESS6.P08
+     * @requirement REQ-STAT6-001.1
+     * @pseudocode agent-runtime-context.md line 93 (step 007.1)
+     *
      * @param name - The name for the subagent, used for logging and identification.
-     * @param runtimeContext - The shared runtime configuration and services.
-     * @param promptConfig - Configuration for the subagent's prompt and behavior.
+     * @param runtimeContext - Immutable runtime context (replaces Config parameter).
      * @param modelConfig - Configuration for the generative model parameters.
      * @param runConfig - Configuration for the subagent's execution environment.
+     * @param promptConfig - Configuration for the subagent's prompt and behavior.
+     * @param contentGenerator - Pre-initialized content generator for this subagent.
+     * @param toolRegistry - Active tool registry for execution and validation.
+     * @param toolExecutorContext - Stateless execution context used for tool invocations.
+     * @param environmentContextLoader - Function that resolves environment context for prompts.
      * @param toolConfig - Optional configuration for tools available to the subagent.
      * @param outputConfig - Optional configuration for the subagent's expected outputs.
      */
     private constructor();
+    /**
+     * Returns the unique agent identifier assigned to this subagent scope.
+     */
+    getAgentId(): string;
     /**
      * Creates and validates a new SubAgentScope instance.
      * This factory method ensures that all tools provided in the prompt configuration
      * are valid for non-interactive use before creating the subagent instance.
+     *
+     * @plan PLAN-20251028-STATELESS6.P08
+     * @requirement REQ-STAT6-001.1, REQ-STAT6-003.1, REQ-STAT6-003.2
+     * @pseudocode agent-runtime-context.md lines 94-98 (steps 007.2-007.6)
+     *
      * @param {string} name - The name of the subagent.
-     * @param {Config} runtimeContext - The shared runtime configuration and services.
+     * @param {Config} foregroundConfig - Foreground configuration used for shared scheduler plumbing.
      * @param {PromptConfig} promptConfig - Configuration for the subagent's prompt and behavior.
      * @param {ModelConfig} modelConfig - Configuration for the generative model parameters.
      * @param {RunConfig} runConfig - Configuration for the subagent's execution environment.
      * @param {ToolConfig} [toolConfig] - Optional configuration for tools.
      * @param {OutputConfig} [outputConfig] - Optional configuration for expected outputs.
+     * @param {SubAgentRuntimeOverrides} [overrides] - Optional stateless runtime inputs (provider runtime, adapters, settings) to bypass Config usage.
      * @returns {Promise<SubAgentScope>} A promise that resolves to a valid SubAgentScope instance.
      * @throws {Error} If any tool requires user confirmation.
      */
-    static create(name: string, runtimeContext: Config, promptConfig: PromptConfig, modelConfig: ModelConfig, runConfig: RunConfig, toolConfig?: ToolConfig, outputConfig?: OutputConfig): Promise<SubAgentScope>;
+    static create(name: string, foregroundConfig: Config, promptConfig: PromptConfig, modelConfig: ModelConfig, runConfig: RunConfig, toolConfig?: ToolConfig, outputConfig?: OutputConfig, overrides?: SubAgentRuntimeOverrides): Promise<SubAgentScope>;
+    private buildInitialMessages;
+    /**
+     * Executes the subagent in interactive mode by routing tool calls through the
+     * shared CoreToolScheduler. Tests may supply a custom schedulerFactory to
+     * observe scheduling behaviour without touching the real scheduler.
+     */
+    runInteractive(context: ContextState, options?: {
+        schedulerFactory?: SubagentSchedulerFactory;
+    }): Promise<void>;
     /**
      * Runs the subagent in a non-interactive mode.
      * This method orchestrates the subagent's execution loop, including prompt templating,
      * tool execution, and termination conditions.
+     *
+     * @plan PLAN-20251028-STATELESS6.P08
+     * @requirement REQ-STAT6-001.1
+     *
      * @param {ContextState} context - The current context state containing variables for prompt templating.
      * @returns {Promise<void>} A promise that resolves when the subagent has completed its execution.
      */
     runNonInteractive(context: ContextState): Promise<void>;
+    cancel(reason?: string): void;
     /**
      * Processes a list of function calls, executing each one and collecting their responses.
      * This method iterates through the provided function calls, executes them using the
@@ -214,13 +272,34 @@ export declare class SubAgentScope {
      *          which are then used to update the chat history.
      */
     private processFunctionCalls;
+    private createSchedulerConfig;
+    private finalizeOutput;
+    private isFatalToolError;
+    private buildToolUnavailableMessage;
+    private extractToolDetail;
+    private handleEmitValueCall;
+    private buildPartsFromCompletedCalls;
+    private buildTodoCompletionPrompt;
+    /**
+     * Creates a GeminiChat instance for this subagent.
+     *
+     * @plan PLAN-20251028-STATELESS6.P08
+     * @requirement REQ-STAT6-001.1, REQ-STAT6-003.1
+     * @pseudocode agent-runtime-context.md line 99 (step 007.7)
+     *
+     * Step 007.7: Update GeminiChat instantiation to use AgentRuntimeContext
+     * Step 007.8: REMOVE Config mutation (no setModel call)
+     */
     private createChatObject;
+    private buildRuntimeFunctionDeclarations;
     /**
      * Returns an array of FunctionDeclaration objects for tools that are local to the subagent's scope.
      * Currently, this includes the `self.emitvalue` tool for emitting variables.
      * @returns An array of `FunctionDeclaration` objects.
      */
     private getScopeLocalFuncDefs;
+    private normalizeToolName;
+    private toSnakeCase;
     /**
      * Builds the system prompt for the chat based on the provided configurations.
      * It templates the base system prompt and appends instructions for emitting