@vybestack/llxprt-code-core 0.5.0-nightly.251125.8cac021f2 → 0.5.0-nightly.251126.fea76aebd

package/dist/src/agents/codebase-investigator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AgentDefinition } from './types.js';
+import { z } from 'zod';
+declare const CodebaseInvestigationReportSchema: z.ZodObject<{
+    SummaryOfFindings: z.ZodString;
+    ExplorationTrace: z.ZodArray<z.ZodString, "many">;
+    RelevantLocations: z.ZodArray<z.ZodObject<{
+        FilePath: z.ZodString;
+        Reasoning: z.ZodString;
+        KeySymbols: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        FilePath: string;
+        Reasoning: string;
+        KeySymbols: string[];
+    }, {
+        FilePath: string;
+        Reasoning: string;
+        KeySymbols: string[];
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    SummaryOfFindings: string;
+    ExplorationTrace: string[];
+    RelevantLocations: {
+        FilePath: string;
+        Reasoning: string;
+        KeySymbols: string[];
+    }[];
+}, {
+    SummaryOfFindings: string;
+    ExplorationTrace: string[];
+    RelevantLocations: {
+        FilePath: string;
+        Reasoning: string;
+        KeySymbols: string[];
+    }[];
+}>;
+/**
+ * A Proof-of-Concept subagent specialized in analyzing codebase structure,
+ * dependencies, and technologies.
+ */
+export declare const CodebaseInvestigatorAgent: AgentDefinition<typeof CodebaseInvestigationReportSchema>;
+export {};

package/dist/src/agents/codebase-investigator.js

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LSTool } from '../tools/ls.js';
+import { ReadFileTool } from '../tools/read-file.js';
+import { GlobTool } from '../tools/glob.js';
+import { GrepTool } from '../tools/grep.js';
+import { DEFAULT_GEMINI_MODEL } from '../config/models.js';
+import { z } from 'zod';
+// Define a type that matches the outputConfig schema for type safety.
+const CodebaseInvestigationReportSchema = z.object({
+    SummaryOfFindings: z
+        .string()
+        .describe("A summary of the investigation's conclusions and insights for the main agent."),
+    ExplorationTrace: z
+        .array(z.string())
+        .describe('A step-by-step list of actions and tools used during the investigation.'),
+    RelevantLocations: z
+        .array(z.object({
+        FilePath: z.string(),
+        Reasoning: z.string(),
+        KeySymbols: z.array(z.string()),
+    }))
+        .describe('A list of relevant files and the key symbols within them.'),
+});
+/**
+ * A Proof-of-Concept subagent specialized in analyzing codebase structure,
+ * dependencies, and technologies.
+ */
+export const CodebaseInvestigatorAgent = {
+    name: 'codebase_investigator',
+    displayName: 'Codebase Investigator Agent',
+    description: `Your primary tool for multifile search tasks and codebase exploration.
+    Invoke this tool to delegate search tasks to an autonomous subagent.
+    Use this to find features, understand context, or locate specific files, functions, or symbols.
+    Returns a structured Json report with key file paths, symbols, architectural map and insights to solve a task or answer questions`,
+    inputConfig: {
+        inputs: {
+            objective: {
+                description: `A comprehensive and detailed description of the user's ultimate goal. 
+          You must include original user's objective as well as questions and any extra context and questions you may have.`,
+                type: 'string',
+                required: true,
+            },
+        },
+    },
+    outputConfig: {
+        outputName: 'report',
+        description: 'The final investigation report as a JSON object.',
+        schema: CodebaseInvestigationReportSchema,
+    },
+    // The 'output' parameter is now strongly typed as CodebaseInvestigationReportSchema
+    processOutput: (output) => JSON.stringify(output, null, 2),
+    modelConfig: {
+        model: DEFAULT_GEMINI_MODEL,
+        temp: 0.1,
+        top_p: 0.95,
+        thinkingBudget: -1,
+    },
+    runConfig: {
+        max_time_minutes: 5,
+        max_turns: 15,
+    },
+    toolConfig: {
+        // Grant access only to read-only tools.
+        tools: [LSTool.Name, ReadFileTool.Name, GlobTool.Name, GrepTool.Name],
+    },
+    promptConfig: {
+        query: `Your task is to do a deep investigation of the codebase to find all relevant files, code locations, architectural mental map and insights to solve  for the following user objective:
+<objective>
+\${objective}
+</objective>`,
+        systemPrompt: `You are **Codebase Investigator**, a hyper-specialized AI agent and an expert in reverse-engineering complex software projects. You are a sub-agent within a larger development system.
+Your **SOLE PURPOSE** is to build a complete mental model of the code relevant to a given investigation. You must identify all relevant files, understand their roles, and foresee the direct architectural consequences of potential changes.
+You are a sub-agent in a larger system. Your only responsibility is to provide deep, actionable context.
+- **DO:** Find the key modules, classes, and functions that are part of the problem and its solution.
+- **DO:** Understand *why* the code is written the way it is. Question everything.
+- **DO:** Foresee the ripple effects of a change. If \`function A\` is modified, you must check its callers. If a data structure is altered, you must identify where its type definitions need to be updated.
+- **DO:** provide a conclusion and insights to the main agent that invoked you. If the agent is trying to solve a bug, you should provide the root cause of the bug, its impacts, how to fix it etc. If it's a new feature, you should provide insights on where to implement it, what chagnes are necessary etc. 
+- **DO NOT:** Write the final implementation code yourself.
+- **DO NOT:** Stop at the first relevant file. Your goal is a comprehensive understanding of the entire relevant subsystem.
+You operate in a non-interactive loop and must reason based on the information provided and the output of your tools.
+---
+## Core Directives
+<RULES>
+1.  **DEEP ANALYSIS, NOT JUST FILE FINDING:** Your goal is to understand the *why* behind the code. Don't just list files; explain their purpose and the role of their key components. Your final report should empower another agent to make a correct and complete fix.
+2.  **SYSTEMATIC & CURIOUS EXPLORATION:** Start with high-value clues (like tracebacks or ticket numbers) and broaden your search as needed. Think like a senior engineer doing a code review. An initial file contains clues (imports, function calls, puzzling logic). **If you find something you don't understand, you MUST prioritize investigating it until it is clear.** Treat confusion as a signal to dig deeper.
+3.  **HOLISTIC & PRECISE:** Your goal is to find the complete and minimal set of locations that need to be understood or changed. Do not stop until you are confident you have considered the side effects of a potential fix (e.g., type errors, breaking changes to callers, opportunities for code reuse).
+4.  **Web Search:** You are allowed to use the \`web_fetch\` tool to research libraries, language features, or concepts you don't understand (e.g., "what does gettext.translation do with localedir=None?").
+</RULES>
+---
+## Scratchpad Management
+**This is your most critical function. Your scratchpad is your memory and your plan.**
+1.  **Initialization:** On your very first turn, you **MUST** create the \`<scratchpad>\` section. Analyze the \`task\` and create an initial \`Checklist\` of investigation goals and a \`Questions to Resolve\` section for any initial uncertainties.
+2.  **Constant Updates:** After **every** \`<OBSERVATION>\`, you **MUST** update the scratchpad.
+    * Mark checklist items as complete: \`[x]\`.
+    * Add new checklist items as you trace the architecture.
+    * **Explicitly log questions in \`Questions to Resolve\`** (e.g., \`[ ] What is the purpose of the 'None' element in this list?\`). Do not consider your investigation complete until this list is empty.
+    * Record \`Key Findings\` with file paths and notes about their purpose and relevance.
+    * Update \`Irrelevant Paths to Ignore\` to avoid re-investigating dead ends.
+3.  **Thinking on Paper:** The scratchpad must show your reasoning process, including how you resolve your questions.
+---
+## Termination
+Your mission is complete **ONLY** when your \`Questions to Resolve\` list is empty and you have identified all files and necessary change *considerations*.
+When you are finished, you **MUST** call the \`complete_task\` tool. The \`report\` argument for this tool **MUST** be a valid JSON object containing your findings.
+
+**Example of the final report**
+\`\`\`json
+{
+  "SummaryOfFindings": "The core issue is a race condition in the \`updateUser\` function. The function reads the user's state, performs an asynchronous operation, and then writes the state back. If another request modifies the user state during the async operation, that change will be overwritten. The fix requires implementing a transactional read-modify-write pattern, potentially using a database lock or a versioning system.",
+  "ExplorationTrace": [
+    "Used \`grep\` to search for \`updateUser\` to locate the primary function.",
+    "Read the file \`src/controllers/userController.js\` to understand the function's logic.",
+    "Used \`ls -R\` to look for related files, such as services or database models.",
+    "Read \`src/services/userService.js\` and \`src/models/User.js\` to understand the data flow and how state is managed."
+  ],
+  "RelevantLocations": [
+    {
+      "FilePath": "src/controllers/userController.js",
+      "Reasoning": "This file contains the \`updateUser\` function which has the race condition. It's the entry point for the problematic logic.",
+      "KeySymbols": ["updateUser", "getUser", "saveUser"]
+    },
+    {
+      "FilePath": "src/services/userService.js",
+      "Reasoning": "This service is called by the controller and handles the direct interaction with the data layer. Any locking mechanism would likely be implemented here.",
+      "KeySymbols": ["updateUserData"]
+    }
+  ]
+}
+\`\`\`
+`,
+    },
+};
+//# sourceMappingURL=codebase-investigator.js.map

package/dist/src/agents/codebase-investigator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-investigator.js","sourceRoot":"","sources":["../../../src/agents/codebase-investigator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sEAAsE;AACtE,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,CACP,+EAA+E,CAChF;IACH,gBAAgB,EAAE,CAAC;SAChB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,CACP,yEAAyE,CAC1E;IACH,iBAAiB,EAAE,CAAC;SACjB,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KAChC,CAAC,CACH;SACA,QAAQ,CAAC,2DAA2D,CAAC;CACzE,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAElC;IACF,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EAAE,6BAA6B;IAC1C,WAAW,EAAE;;;sIAGuH;IACpI,WAAW,EAAE;QACX,MAAM,EAAE;YACN,SAAS,EAAE;gBACT,WAAW,EAAE;4HACuG;gBACpH,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;aACf;SACF;KACF;IACD,YAAY,EAAE;QACZ,UAAU,EAAE,QAAQ;QACpB,WAAW,EAAE,kDAAkD;QAC/D,MAAM,EAAE,iCAAiC;KAC1C;IAED,oFAAoF;IACpF,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,WAAW,EAAE;QACX,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,GAAG;QACT,KAAK,EAAE,IAAI;QACX,cAAc,EAAE,CAAC,CAAC;KACnB;IAED,SAAS,EAAE;QACT,gBAAgB,EAAE,CAAC;QACnB,SAAS,EAAE,EAAE;KACd;IAED,UAAU,EAAE;QACV,wCAAwC;QACxC,KAAK,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;KACtE;IAED,YAAY,EAAE;QACZ,KAAK,EAAE;;;aAGE;QACT,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DjB;KACE;CACF,CAAC"}

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

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '../config/config.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 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.
+     */
+    static create<TOutput extends z.ZodTypeAny>(definition: AgentDefinition<TOutput>, runtimeContext: Config, 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>;
+    /**
+     * Calls the generative model with the current context and tools.
+     *
+     * @returns The model's response, including any tool calls or text.
+     */
+    private callModel;
+    /** Initializes a `GeminiChat` instance for the agent run. */
+    private createChatObject;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    private static validateTools;
+    /**
+     * Checks if the agent should terminate due to exceeding configured limits.
+     *
+     * @returns The reason for termination, or `null` if execution can continue.
+     */
+    private checkTermination;
+    /** Emits an activity event to the configured callback. */
+    private emitActivity;
+}