@vybestack/llxprt-code-agents 0.10.0-nightly.260613.1adad3b34

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @plan:PLAN-20260610-ISSUE1592.P02
+ * @requirement:REQ-PKG-001
+ */
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from './src/index.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @plan:PLAN-20260610-ISSUE1592.P02
+ * @requirement:REQ-PKG-001
+ */
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from './src/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC"}

package/dist/src/agents/executor-prompt-builder.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '@vybestack/llxprt-code-core/config/config.js';
+import type { AgentInputs } from './types.js';
+/**
+ * Build the system prompt for an agent execution.
+ */
+export declare function buildAgentSystemPrompt(inputs: AgentInputs, runtimeContext: Config, systemPromptTemplate: string): Promise<string>;
+/**
+ * Apply template strings to initial messages.
+ */
+export declare function applyTemplateToInitialMessages<T extends {
+    parts?: Array<{
+        text?: string;
+    } | object>;
+}>(initialMessages: T[], inputs: AgentInputs): T[];

package/dist/src/agents/executor-prompt-builder.js

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getDirectoryContextString } from '@vybestack/llxprt-code-core/utils/environmentContext.js';
+import { templateString } from './utils.js';
+const TASK_COMPLETE_TOOL_NAME = 'complete_task';
+/**
+ * Build the system prompt for an agent execution.
+ */
+export async function buildAgentSystemPrompt(inputs, runtimeContext, systemPromptTemplate) {
+    // Inject user inputs into the prompt template.
+    let finalPrompt = templateString(systemPromptTemplate, inputs);
+    // Append environment context (CWD and folder structure).
+    const dirContext = await getDirectoryContextString(runtimeContext);
+    finalPrompt += `\n\n# Environment Context\n${dirContext}`;
+    // Append standard rules for non-interactive execution.
+    finalPrompt += `
+Important Rules:
+* You are running in a non-interactive mode. You CANNOT ask the user for input or clarification.
+* Work systematically using available tools to complete your task.
+* Always use absolute paths for file operations. Construct them using the provided "Environment Context".`;
+    finalPrompt += `
+* When you have completed your task, you MUST call the \`${TASK_COMPLETE_TOOL_NAME}\` tool.
+* Do not call any other tools in the same turn as \`${TASK_COMPLETE_TOOL_NAME}\`.
+* This is the ONLY way to complete your mission. If you stop calling tools without calling this, you have failed.`;
+    return finalPrompt;
+}
+/**
+ * Apply template strings to initial messages.
+ */
+export function applyTemplateToInitialMessages(initialMessages, inputs) {
+    return initialMessages.map((content) => {
+        const newParts = (content.parts ?? []).map((part) => {
+            if ('text' in part && part.text !== undefined) {
+                return { text: templateString(part.text, inputs) };
+            }
+            return part;
+        });
+        return { ...content, parts: newParts };
+    });
+}
+//# sourceMappingURL=executor-prompt-builder.js.map

package/dist/src/agents/executor-prompt-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-prompt-builder.js","sourceRoot":"","sources":["../../../src/agents/executor-prompt-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAC;AAEpG,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAmB,EACnB,cAAsB,EACtB,oBAA4B;IAE5B,+CAA+C;IAC/C,IAAI,WAAW,GAAG,cAAc,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAE/D,yDAAyD;IACzD,MAAM,UAAU,GAAG,MAAM,yBAAyB,CAAC,cAAc,CAAC,CAAC;IACnE,WAAW,IAAI,8BAA8B,UAAU,EAAE,CAAC;IAE1D,uDAAuD;IACvD,WAAW,IAAI;;;;0GAIyF,CAAC;IAEzG,WAAW,IAAI;2DAC0C,uBAAuB;sDAC5B,uBAAuB;kHACqC,CAAC;IAEjH,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAE5C,eAAoB,EAAE,MAAmB;IACzC,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACrC,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YAClD,IAAI,MAAM,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9C,OAAO,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;YACrD,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAO,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/agents/executor-termination.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AgentTerminateMode } from './types.js';
+/**
+ * Checks if the agent should terminate due to exceeding configured limits.
+ *
+ * @param runConfig The run configuration with max_turns and max_time_minutes.
+ * @param startTime The timestamp (ms) when execution started.
+ * @param turnCounter The current turn number.
+ * @param recoveryDeadlineMs If in a recovery turn, the absolute deadline (ms)
+ *   that overrides the normal max_time_minutes timeout. When provided, the
+ *   max_turns limit is also bypassed since recovery turns are exempt from turn
+ *   counting. Pass `undefined` when not in recovery mode.
+ * @returns The reason for termination, or `null` if execution can continue.
+ */
+export declare function checkAgentTermination(runConfig: {
+    max_turns?: number;
+    max_time_minutes: number;
+}, startTime: number, turnCounter: number, recoveryDeadlineMs?: number): AgentTerminateMode | null;

package/dist/src/agents/executor-termination.js

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AgentTerminateMode } from './types.js';
+/** Whether the given max_turns value represents a real, positive limit. */
+function hasMaxTurnsLimit(maxTurns) {
+    return (typeof maxTurns === 'number' && maxTurns > 0 && !Number.isNaN(maxTurns));
+}
+/**
+ * Checks if the agent should terminate due to exceeding configured limits.
+ *
+ * @param runConfig The run configuration with max_turns and max_time_minutes.
+ * @param startTime The timestamp (ms) when execution started.
+ * @param turnCounter The current turn number.
+ * @param recoveryDeadlineMs If in a recovery turn, the absolute deadline (ms)
+ *   that overrides the normal max_time_minutes timeout. When provided, the
+ *   max_turns limit is also bypassed since recovery turns are exempt from turn
+ *   counting. Pass `undefined` when not in recovery mode.
+ * @returns The reason for termination, or `null` if execution can continue.
+ */
+export function checkAgentTermination(runConfig, startTime, turnCounter, recoveryDeadlineMs) {
+    const inRecovery = recoveryDeadlineMs !== undefined;
+    if (!inRecovery &&
+        hasMaxTurnsLimit(runConfig.max_turns) &&
+        turnCounter >= runConfig.max_turns) {
+        return AgentTerminateMode.MAX_TURNS;
+    }
+    const now = Date.now();
+    if (inRecovery) {
+        if (now >= recoveryDeadlineMs) {
+            return AgentTerminateMode.TIMEOUT;
+        }
+    }
+    else {
+        const elapsedMinutes = (now - startTime) / (1000 * 60);
+        if (elapsedMinutes >= runConfig.max_time_minutes) {
+            return AgentTerminateMode.TIMEOUT;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=executor-termination.js.map

package/dist/src/agents/executor-termination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-termination.js","sourceRoot":"","sources":["../../../src/agents/executor-termination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,2EAA2E;AAC3E,SAAS,gBAAgB,CAAC,QAA4B;IACpD,OAAO,CACL,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CACxE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAA2D,EAC3D,SAAiB,EACjB,WAAmB,EACnB,kBAA2B;IAE3B,MAAM,UAAU,GAAG,kBAAkB,KAAK,SAAS,CAAC;IAEpD,IACE,CAAC,UAAU;QACX,gBAAgB,CAAC,SAAS,CAAC,SAAS,CAAC;QACrC,WAAW,IAAI,SAAS,CAAC,SAAS,EAClC,CAAC;QACD,OAAO,kBAAkB,CAAC,SAAS,CAAC;IACtC,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,GAAG,IAAI,kBAAkB,EAAE,CAAC;YAC9B,OAAO,kBAAkB,CAAC,OAAO,CAAC;QACpC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,cAAc,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;QACvD,IAAI,cAAc,IAAI,SAAS,CAAC,gBAAgB,EAAE,CAAC;YACjD,OAAO,kBAAkB,CAAC,OAAO,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/agents/executor-validation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ToolRegistry } from '@vybestack/llxprt-code-tools';
+/**
+ * Tools that are currently approved for non-interactive execution while
+ * subagent confirmation handling remains restricted to this allowlist.
+ */
+export declare const NON_INTERACTIVE_TOOL_ALLOWLIST: Set<string>;
+/**
+ * Validates that all tools in a registry are safe for non-interactive use.
+ *
+ * @throws An error if a tool is not on the allow-list for non-interactive execution.
+ */
+export declare function validateToolsForNonInteractiveUse(toolRegistry: ToolRegistry, agentName: string): Promise<void>;

package/dist/src/agents/executor-validation.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GlobTool, GrepTool, LSTool, ReadFileTool, ReadManyFilesTool, RipGrepTool, MemoryTool, GoogleWebSearchTool, } from '@vybestack/llxprt-code-tools';
+/**
+ * Tools that are currently approved for non-interactive execution while
+ * subagent confirmation handling remains restricted to this allowlist.
+ */
+export const NON_INTERACTIVE_TOOL_ALLOWLIST = new Set([
+    LSTool.Name,
+    ReadFileTool.Name,
+    GrepTool.Name,
+    RipGrepTool.Name,
+    GlobTool.Name,
+    ReadManyFilesTool.Name,
+    MemoryTool.Name,
+    GoogleWebSearchTool.Name,
+]);
+/**
+ * Validates that all tools in a registry are safe for non-interactive use.
+ *
+ * @throws An error if a tool is not on the allow-list for non-interactive execution.
+ */
+export async function validateToolsForNonInteractiveUse(toolRegistry, agentName) {
+    for (const tool of toolRegistry.getAllTools()) {
+        if (!NON_INTERACTIVE_TOOL_ALLOWLIST.has(tool.name)) {
+            throw new Error(`Tool "${tool.name}" is not on the allow-list for non-interactive ` +
+                `execution in agent "${agentName}". Only tools that do not require user ` +
+                `confirmation can be used in subagents.`);
+        }
+    }
+}
+//# sourceMappingURL=executor-validation.js.map

package/dist/src/agents/executor-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor-validation.js","sourceRoot":"","sources":["../../../src/agents/executor-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC;IACpD,MAAM,CAAC,IAAI;IACX,YAAY,CAAC,IAAI;IACjB,QAAQ,CAAC,IAAI;IACb,WAAW,CAAC,IAAI;IAChB,QAAQ,CAAC,IAAI;IACb,iBAAiB,CAAC,IAAI;IACtB,UAAU,CAAC,IAAI;IACf,mBAAmB,CAAC,IAAI;CACzB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,YAA0B,EAC1B,SAAiB;IAEjB,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,WAAW,EAAE,EAAE,CAAC;QAC9C,IAAI,CAAC,8BAA8B,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CACb,SAAS,IAAI,CAAC,IAAI,iDAAiD;gBACjE,uBAAuB,SAAS,yCAAyC;gBACzE,wCAAwC,CAC3C,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/src/agents/executor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '@vybestack/llxprt-code-core/config/config.js';
+import type { MessageBus } from '@vybestack/llxprt-code-core/confirmation-bus/message-bus.js';
+import type { AgentDefinition, AgentInputs, OutputObject, SubagentActivityEvent } from './types.js';
+import { type z } from 'zod';
+/** A callback function to report on agent activity. */
+export type ActivityCallback = (activity: SubagentActivityEvent) => void;
+/**
+ * Executes an agent loop based on an {@link AgentDefinition}.
+ *
+ * This executor runs the agent in a loop, calling tools until it calls the
+ * mandatory `complete_task` tool to signal completion.
+ */
+export declare class AgentExecutor<TOutput extends z.ZodTypeAny> {
+    readonly definition: AgentDefinition<TOutput>;
+    private readonly agentId;
+    private readonly toolRegistry;
+    private readonly runtimeContext;
+    private readonly messageBus;
+    private readonly onActivity?;
+    /**
+     * Creates and validates a new `AgentExecutor` instance.
+     *
+     * This method ensures that all tools specified in the agent's definition are
+     * safe for non-interactive use before creating the executor.
+     *
+     * @param definition The definition object for the agent.
+     * @param runtimeContext The global runtime configuration.
+     * @param onActivity An optional callback to receive activity events.
+     * @returns A promise that resolves to a new `AgentExecutor` instance.
+     */
+    /**
+     * @plan PLAN-20260309-MESSAGEBUS-DI-REMEDIATION.P05
+     * @requirement REQ-D01-001.2
+     * @pseudocode lines 56-72
+     */
+    static create<TOutput extends z.ZodTypeAny>(definition: AgentDefinition<TOutput>, runtimeContext: Config, messageBus: MessageBus, onActivity?: ActivityCallback): Promise<AgentExecutor<TOutput>>;
+    /**
+     * Constructs a new AgentExecutor instance.
+     *
+     * @private This constructor is private. Use the static `create` method to
+     * instantiate the class.
+     */
+    private constructor();
+    /**
+     * Runs the agent.
+     *
+     * @param inputs The validated input parameters for this invocation.
+     * @param signal An `AbortSignal` for cancellation.
+     * @returns A promise that resolves to the agent's final output.
+     */
+    run(inputs: AgentInputs, signal: AbortSignal): Promise<OutputObject>;
+    /** Runs the agent loop until termination, returning the reason and result. */
+    private runAgentLoop;
+    /** Single iteration of the agent loop. */
+    private runAgentLoopIteration;
+    /** Body of the agent loop iteration (after termination checks). */
+    private runAgentLoopIterationBody;
+    /** Check tool calls during recovery: non-complete_task = recovery failure. */
+    private checkRecoveryToolCalls;
+    /** Handle termination-reason checks: enter recovery or return immediately. */
+    private handleTerminationReason;
+    /** Handle the protocol-violation path (model stopped calling tools). */
+    private handleProtocolViolation;
+    private isAborted;
+    /** Create an AbortController that fires when the recovery deadline passes. */
+    private createRecoveryAbortController;
+    /** Emit a RECOVERY_OUTCOME telemetry event. */
+    private emitRecoveryOutcome;
+    /**
+     * Calls the generative model with the current context and tools.
+     *
+     * @returns The model's response, including any tool calls or text.
+     */
+    private callModel;
+    /** Consumes a response stream, accumulating function calls and text. */
+    private consumeStream;
+    /** Processes a single stream chunk, extracting thoughts, function calls, and text. */
+    private processStreamChunk;
+    /** Initializes a `ChatSession` instance for the agent run. */
+    private createChatObject;
+    /** Builds the generation config from model config and optional system instruction. */
+    private buildGenerationConfig;
+    /** Builds the runtime bundle for the ChatSession instance. */
+    private buildRuntimeBundle;
+    /** Resolves the settings snapshot from ephemeral config. */
+    private resolveSettingsSnapshot;
+    /** Attempts to get the content generator from the runtime context. */
+    private tryGetContentGenerator;
+    /**
+     * Executes function calls requested by the model and returns the results.
+     *
+     * @returns A new `Content` object for history, any submitted output, and completion status.
+     */
+    private processFunctionCalls;
+    /** Handles a `complete_task` function call, returning updated state and response parts. */
+    private handleCompleteTaskCall;
+    /** Processes the output argument of a `complete_task` call when outputConfig is present. */
+    private processCompleteTaskOutput;
+    /** Handles an unauthorized tool call by pushing an error response. */
+    private handleUnauthorizedToolCall;
+    /** Creates an async promise that executes a standard tool call. */
+    private createToolExecutionPromise;
+    /** Assembles all tool response parts and returns the final result. */
+    private assembleToolResponses;
+    /**
+     * Prepares the list of tool function declarations to be sent to the model.
+     */
+    private prepareToolsList;
+    /** Builds the system prompt from the agent definition and inputs. */
+    private buildSystemPrompt;
+    /**
+     * Applies template strings to initial messages.
+     *
+     * @param initialMessages The initial messages from the prompt config.
+     * @param inputs The validated input parameters for this invocation.
+     * @returns A new array of `Content` with templated strings.
+     */
+    private applyTemplateToInitialMessages;
+    /**
+     * Checks if the agent should terminate due to exceeding configured limits.
+     *
+     * @param startTime The timestamp (ms) when execution started.
+     * @param turnCounter The current turn number.
+     * @param recoveryDeadlineMs If in a recovery turn, the absolute deadline (ms)
+     *   that overrides normal max_time_minutes. Pass `undefined` when not recovering.
+     * @returns The reason for termination, or `null` if execution can continue.
+     */
+    private checkTermination;
+    /** Emits an activity event to the configured callback. */
+    private emitActivity;
+}