@vybestack/llxprt-code-core 0.5.0 → 0.6.0

package/README.md

@@ -1,244 +0,0 @@
-# LLxprt Code
-
-[![LLxprt Code CI](https://github.com/vybestack/llxprt-code/actions/workflows/ci.yml/badge.svg)](https://github.com/vybestack/llxprt-code/actions/workflows/ci.yml)
- [![Mentioned in Awesome Gemini CLI](https://awesome.re/mentioned-badge.svg)](https://github.com/Piebald-AI/awesome-gemini-cli) [![Discord Server](https://dcbadge.limes.pink/api/server/https://discord.gg/Wc6dZqWWYv?style=flat)](https://discord.gg/Wc6dZqWWYv) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/vybestack/llxprt-code?utm_source=oss&utm_medium=github&utm_campaign=vybestack%2Fllxprt-code&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
-
-![LLxprt Code Screenshot](./docs/assets/llxprt-screenshot.png)
-
-**AI-powered coding assistant that works with any LLM provider.** Command-line interface for querying and editing codebases, generating applications, and automating development workflows.
-
-## Free & Subscription Options
-
-Get started immediately with powerful LLM options:
-
-```bash
-# Free Gemini models
-/auth gemini enable
-/provider gemini
-/model gemini-2.5-flash
-
-# Free Qwen models
-/auth qwen enable
-/provider qwen
-/model qwen-3-coder
-
-# Your Claude Pro / Max subscription
-/auth anthropic enable
-/provider anthropic
-/model claude-sonnet-4-5
-```
-
-## Why Choose LLxprt Code?
-
-- **Free Tier Support**: Start coding immediately with Gemini, Qwen, or your existing Claude account
-- **Provider Flexibility**: Switch between any Anthropic, Gemini, or OpenAI-compatible provider
-- **Top Open Models**: Works seamlessly with GLM 4.6, MiniMax-2, and Qwen 3 Coder
-- **Local Models**: Run models locally with LM Studio, llama.cpp for complete privacy
-- **Privacy First**: No telemetry by default, local processing available
-- **Subagent Flexibility**: Create agents with different models, providers, or settings
-- **[ACTION] Real-time**: Interactive REPL with beautiful themes
-- **Zed Integration**: Native Zed editor integration for seamless workflow
-
-```bash
-# Install and get started
-npm install -g @vybestack/llxprt-code
-llxprt
-
-# Try without installing
-npx @vybestack/llxprt-code --provider synthetic --model hf:zai-org/GLM-4.6 --keyfile ~/.synthetic_key "simplify the README.md"
-```
-
-## What is LLxprt Code?
-
-LLxprt Code is a command-line AI assistant designed for developers who want powerful LLM capabilities without leaving their terminal. Unlike GitHub Copilot or ChatGPT, LLxprt Code works with **any provider** and can run **locally** for complete privacy.
-
-**Key differences:**
-
-- **Open source & community driven**: Not locked into proprietary ecosystems
-- **Provider agnostic**: Not locked into one AI service
-- **Local-first**: Run entirely offline if needed
-- **Developer-centric**: Built specifically for coding workflows
-- **Terminal native**: Designed for CLI workflows, not web interfaces
-
-## Quick Start
-
-1. **Prerequisites:** Node.js 20+ installed
-2. **Install:**
-   ```bash
-   npm install -g @vybestack/llxprt-code
-   # Or try without installing:
-   npx @vybestack/llxprt-code
-   ```
-3. **Run:** `llxprt`
-4. **Choose provider:** Use `/provider` to select your preferred LLM service
-5. **Start coding:** Ask questions, generate code, or analyze projects
-
-**First session example:**
-
-```bash
-cd your-project/
-llxprt
-> Explain the architecture of this codebase and suggest improvements
-> Create a test file for the user authentication module
-> Help me debug this error: [paste error message]
-```
-
-## Key Features
-
-- **Free & Subscription Options** - Gemini, Qwen (free), Claude Pro/Max (subscription)
-- **Extensive Provider Support** - Any Anthropic, Gemini, or OpenAI-compatible provider [**Provider Guide →**](./docs/providers/quick-reference.md)
-- **Top Open Models** - GLM 4.6, MiniMax-2, Qwen 3 Coder
-- **Local Model Support** - LM Studio, llama.cpp, Ollama for complete privacy
-- **Profile System** - Save provider configurations and model settings
-- **Advanced Subagents** - Isolated AI assistants with different models/providers
-- **MCP Integration** - Connect to external tools and services
-- **Beautiful Terminal UI** - Multiple themes with syntax highlighting
-
-## Interactive vs Non-Interactive Workflows
-
-**Interactive Mode (REPL):**
-Perfect for exploration, rapid prototyping, and iterative development:
-
-```bash
-# Start interactive session
-llxprt
-
-> Explore this codebase and suggest improvements
-> Create a REST API endpoint with tests
-> Debug this authentication issue
-> Optimize this database query
-```
-
-**Non-Interactive Mode:**
-Ideal for automation, CI/CD, and scripted workflows:
-
-```bash
-# Single command with immediate response
-llxprt --profile-load zai-glm46 "Refactor this function for better readability"
-llxprt "Generate unit tests for payment module" > tests/payment.test.js
-```
-
-## Top Open Weight Models
-
-LLxprt Code works seamlessly with the best open-weight models:
-
-### GLM 4.6
-
-- **Context Window**: 200,000 tokens
-- **Architecture**: Mixture-of-Experts with 355B total parameters (32B active)
-- **Strengths**: Coding, multi-step planning, tool integration
-- **15% fewer tokens** for equivalent tasks vs previous generation
-
-### MiniMax-2
-
-- **Context Window**: ~204,800 tokens
-- **Architecture**: MoE with 230B total parameters (10B active)
-- **Strengths**: Coding workflows, multi-step agents, tool calling
-- **Cost**: Only 8% of Claude Sonnet, ~2x faster
-
-### Qwen 3 Coder
-
-- **Context Window**: 256,000 tokens (extendable to 1M)
-- **Architecture**: MoE with 480B total parameters (35B active)
-- **Strengths**: Agentic coding, browser automation, tool usage
-- **Performance**: State-of-the-art on SWE-bench Verified (69.6%)
-
-## Local Models
-
-Run models completely offline for maximum privacy:
-
-```bash
-# With LM Studio
-/provider openai
-/baseurl http://localhost:1234/v1/
-/model your-local-model
-
-# With Ollama
-/provider ollama
-/model codellama:13b
-```
-
-Supported local providers:
-
-- **LM Studio**: Easy Windows/Mac/Linux setup
-- **llama.cpp**: Maximum performance and control
-- **Ollama**: Simple model management
-- **Any OpenAI-compatible API**: Full flexibility
-
-## Advanced Subagents
-
-Create specialized AI assistants with isolated contexts and different configurations:
-
-```bash
-# Subagents run with custom profiles and tool access
-# Access via the commands interface
-/subagent list
-/subagent create <name>
-```
-
-Each subagent can be configured with:
-
-- **Different providers** (Gemini vs Anthropic vs Qwen vs Local)
-- **Different models** (Flash vs Sonnet vs GLM 4.6 vs Custom)
-- **Different tool access** (Restrict or allow specific tools)
-- **Different settings** (Temperature, timeouts, max turns)
-- **Isolated runtime context** (No memory or state crossover)
-
-Subagents are designed for:
-
-- **Specialized tasks** (Code review, debugging, documentation)
-- **Different expertise areas** (Frontend vs Backend vs DevOps)
-- **Tool-limited environments** (Read-only analysis vs Full development)
-- **Experimental configurations** (Testing new models or settings)
-
-**[Full Subagent Documentation →](./docs/subagents.md)**
-
-## Zed Integration
-
-Native Zed editor support for seamless development workflow:
-
-```bash
-# Install Zed extension
-zed:install llxprt-code
-
-# Use within Zed
-# (See docs for Zed integration setup)
-```
-
-Features:
-
-- **In-editor chat**: Direct AI interaction without leaving Zed
-- **Code selection**: Ask about specific code selections
-- **Inline suggestions**: Get AI help while typing
-- **Project awareness**: Full context of your open workspace
-
-** [Zed Integration Guide →](./docs/zed-integration.md)**
-
-** [Complete Provider Guide →](./docs/cli/providers.md)**
-
-## Advanced Features
-
-- **Settings & Profiles**: Fine-tune model parameters and save configurations
-- **Subagents**: Create specialized assistants for different tasks
-- **MCP Servers**: Connect external tools and data sources
-- **Checkpointing**: Save and resume complex conversations
-- **IDE Integration**: Connect to VS Code and other editors
-
-** [Full Documentation →](./docs/index.md)**
-
-## Migration & Resources
-
-- **From Gemini CLI**: [Migration Guide](./docs/gemini-cli-tips.md)
-- **Local Models Setup**: [Local Models Guide](./docs/local-models.md)
-- **Command Reference**: [CLI Commands](./docs/cli/commands.md)
-- **Troubleshooting**: [Common Issues](./docs/troubleshooting.md)
-
-## Privacy & Terms
-
-LLxprt Code does not collect telemetry by default. Your data stays with you unless you choose to send it to external AI providers.
-
-When using external services, their respective terms of service apply:
-
-- [OpenAI Terms](https://openai.com/policies/terms-of-use)
-- [Anthropic Terms](https://www.anthropic.com/legal/terms)
-- [Google Terms](https://policies.google.com/terms)

package/dist/index.d.ts

@@ -8,10 +8,10 @@ export { DEFAULT_GEMINI_MODEL, DEFAULT_GEMINI_FLASH_MODEL, DEFAULT_GEMINI_FLASH_
 export { QwenDeviceFlow, DeviceFlowConfig, } from './src/auth/qwen-device-flow.js';
 export { MultiProviderTokenStore } from './src/auth/token-store.js';
 export { openBrowserSecurely, shouldLaunchBrowser, } from './src/utils/secure-browser-launcher.js';
+export { IDE_DEFINITIONS, detectIdeFromEnv } from './src/ide/detect-ide.js';
 export { SettingsService } from './src/settings/SettingsService.js';
 export type { ISettingsService, GlobalSettings, SettingsChangeEvent, ProviderSettings, UISettings, AdvancedSettings, EventListener, EventUnsubscribe, } from './src/settings/types.js';
 export type { TelemetrySettings as SettingsTelemetrySettings } from './src/settings/types.js';
 export { IdeConnectionEvent, IdeConnectionType, } from './src/telemetry/types.js';
 export { getIdeTrust } from './src/utils/ide-trust.js';
-export { makeFakeConfig } from './src/test-utils/config.js';
 export * from './src/utils/pathReader.js';

package/dist/index.js

@@ -8,11 +8,11 @@ export { DEFAULT_GEMINI_MODEL, DEFAULT_GEMINI_FLASH_MODEL, DEFAULT_GEMINI_FLASH_
 export { QwenDeviceFlow, } from './src/auth/qwen-device-flow.js';
 export { MultiProviderTokenStore } from './src/auth/token-store.js';
 export { openBrowserSecurely, shouldLaunchBrowser, } from './src/utils/secure-browser-launcher.js';
+export { IDE_DEFINITIONS, detectIdeFromEnv } from './src/ide/detect-ide.js';
 // Re-export settings system for explicit access
 export { SettingsService } from './src/settings/SettingsService.js';
 // IDE connection telemetry exports removed - telemetry disabled in llxprt
 export { IdeConnectionEvent, IdeConnectionType, } from './src/telemetry/types.js';
 export { getIdeTrust } from './src/utils/ide-trust.js';
-export { makeFakeConfig } from './src/test-utils/config.js';
 export * from './src/utils/pathReader.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,GAEf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wCAAwC,CAAC;AAEhD,gDAAgD;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAYpE,0EAA0E;AAC1E,OAAO,EACL,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,GAEf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE5E,gDAAgD;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAYpE,0EAA0E;AAC1E,OAAO,EACL,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,cAAc,2BAA2B,CAAC"}

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;
+}