@didim365/agent-cli-core 0.1.0

package/dist/src/agents/subagent-tool-wrapper.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseDeclarativeTool, type ToolInvocation, type ToolResult } from '../tools/tools.js';
+import type { Config } from '../config/config.js';
+import type { AgentDefinition, AgentInputs } from './types.js';
+import type { MessageBus } from '../confirmation-bus/message-bus.js';
+/**
+ * A tool wrapper that dynamically exposes a subagent as a standard,
+ * strongly-typed `DeclarativeTool`.
+ */
+export declare class SubagentToolWrapper extends BaseDeclarativeTool<AgentInputs, ToolResult> {
+    private readonly definition;
+    private readonly config;
+    /**
+     * Constructs the tool wrapper.
+     *
+     * The constructor dynamically generates the JSON schema for the tool's
+     * parameters based on the subagent's input configuration.
+     *
+     * @param definition The `AgentDefinition` of the subagent to wrap.
+     * @param config The runtime configuration, passed down to the subagent.
+     * @param messageBus Optional message bus for policy enforcement.
+     */
+    constructor(definition: AgentDefinition, config: Config, messageBus: MessageBus);
+    /**
+     * Creates an invocation instance for executing the subagent.
+     *
+     * This method is called by the tool framework when the parent agent decides
+     * to use this tool.
+     *
+     * @param params The validated input parameters from the parent agent's call.
+     * @returns A `ToolInvocation` instance ready for execution.
+     */
+    protected createInvocation(params: AgentInputs, messageBus: MessageBus, _toolName?: string, _toolDisplayName?: string): ToolInvocation<AgentInputs, ToolResult>;
+}

package/dist/src/agents/subagent-tool-wrapper.js

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseDeclarativeTool, Kind, } from '../tools/tools.js';
+import { LocalSubagentInvocation } from './local-invocation.js';
+import { RemoteAgentInvocation } from './remote-invocation.js';
+/**
+ * A tool wrapper that dynamically exposes a subagent as a standard,
+ * strongly-typed `DeclarativeTool`.
+ */
+export class SubagentToolWrapper extends BaseDeclarativeTool {
+    definition;
+    config;
+    /**
+     * Constructs the tool wrapper.
+     *
+     * The constructor dynamically generates the JSON schema for the tool's
+     * parameters based on the subagent's input configuration.
+     *
+     * @param definition The `AgentDefinition` of the subagent to wrap.
+     * @param config The runtime configuration, passed down to the subagent.
+     * @param messageBus Optional message bus for policy enforcement.
+     */
+    constructor(definition, config, messageBus) {
+        super(definition.name, definition.displayName ?? definition.name, definition.description, Kind.Think, definition.inputConfig.inputSchema, messageBus, 
+        /* isOutputMarkdown */ true, 
+        /* canUpdateOutput */ true);
+        this.definition = definition;
+        this.config = config;
+    }
+    /**
+     * Creates an invocation instance for executing the subagent.
+     *
+     * This method is called by the tool framework when the parent agent decides
+     * to use this tool.
+     *
+     * @param params The validated input parameters from the parent agent's call.
+     * @returns A `ToolInvocation` instance ready for execution.
+     */
+    createInvocation(params, messageBus, _toolName, _toolDisplayName) {
+        const definition = this.definition;
+        const effectiveMessageBus = messageBus;
+        if (definition.kind === 'remote') {
+            return new RemoteAgentInvocation(definition, params, effectiveMessageBus, _toolName, _toolDisplayName);
+        }
+        return new LocalSubagentInvocation(definition, this.config, params, effectiveMessageBus, _toolName, _toolDisplayName);
+    }
+}
+//# sourceMappingURL=subagent-tool-wrapper.js.map

package/dist/src/agents/subagent-tool-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-tool-wrapper.js","sourceRoot":"","sources":["../../../src/agents/subagent-tool-wrapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,mBAAmB,EACnB,IAAI,GAGL,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,mBAGxC;IAYoB;IACA;IAZnB;;;;;;;;;OASG;IACH,YACmB,UAA2B,EAC3B,MAAc,EAC/B,UAAsB;QAEtB,KAAK,CACH,UAAU,CAAC,IAAI,EACf,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC,IAAI,EACzC,UAAU,CAAC,WAAW,EACtB,IAAI,CAAC,KAAK,EACV,UAAU,CAAC,WAAW,CAAC,WAAW,EAClC,UAAU;QACV,sBAAsB,CAAC,IAAI;QAC3B,qBAAqB,CAAC,IAAI,CAC3B,CAAC;QAbe,eAAU,GAAV,UAAU,CAAiB;QAC3B,WAAM,GAAN,MAAM,CAAQ;IAajC,CAAC;IAED;;;;;;;;OAQG;IACO,gBAAgB,CACxB,MAAmB,EACnB,UAAsB,EACtB,SAAkB,EAClB,gBAAyB;QAEzB,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACnC,MAAM,mBAAmB,GAAG,UAAU,CAAC;QAEvC,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,IAAI,qBAAqB,CAC9B,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,SAAS,EACT,gBAAgB,CACjB,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,uBAAuB,CAChC,UAAU,EACV,IAAI,CAAC,MAAM,EACX,MAAM,EACN,mBAAmB,EACnB,SAAS,EACT,gBAAgB,CACjB,CAAC;IACJ,CAAC;CACF"}

package/dist/src/agents/subagent-tool-wrapper.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/agents/subagent-tool-wrapper.test.js

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SubagentToolWrapper } from './subagent-tool-wrapper.js';
+import { LocalSubagentInvocation } from './local-invocation.js';
+import { makeFakeConfig } from '../test-utils/config.js';
+import { Kind } from '../tools/tools.js';
+import { createMockMessageBus } from '../test-utils/mock-message-bus.js';
+// Mock dependencies to isolate the SubagentToolWrapper class
+vi.mock('./local-invocation.js');
+const MockedLocalSubagentInvocation = vi.mocked(LocalSubagentInvocation);
+// Define reusable test data
+let mockConfig;
+let mockMessageBus;
+const mockDefinition = {
+    kind: 'local',
+    name: 'TestAgent',
+    displayName: 'Test Agent Display Name',
+    description: 'An agent for testing.',
+    inputConfig: {
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goal: { type: 'string', description: 'The goal.' },
+                priority: {
+                    type: 'number',
+                    description: 'The priority.',
+                },
+            },
+            required: ['goal'],
+        },
+    },
+    modelConfig: {
+        model: 'gemini-test-model',
+        generateContentConfig: {
+            temperature: 0,
+            topP: 1,
+        },
+    },
+    runConfig: { maxTimeMinutes: 5 },
+    promptConfig: { systemPrompt: 'You are a test agent.' },
+};
+describe('SubagentToolWrapper', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockConfig = makeFakeConfig();
+        mockMessageBus = createMockMessageBus();
+    });
+    describe('constructor', () => {
+        it('should correctly configure the tool properties from the agent definition', () => {
+            const wrapper = new SubagentToolWrapper(mockDefinition, mockConfig, mockMessageBus);
+            expect(wrapper.name).toBe(mockDefinition.name);
+            expect(wrapper.displayName).toBe(mockDefinition.displayName);
+            expect(wrapper.description).toBe(mockDefinition.description);
+            expect(wrapper.kind).toBe(Kind.Think);
+            expect(wrapper.isOutputMarkdown).toBe(true);
+            expect(wrapper.canUpdateOutput).toBe(true);
+        });
+        it('should fall back to the agent name for displayName if it is not provided', () => {
+            const definitionWithoutDisplayName = {
+                ...mockDefinition,
+                displayName: undefined,
+            };
+            const wrapper = new SubagentToolWrapper(definitionWithoutDisplayName, mockConfig, mockMessageBus);
+            expect(wrapper.displayName).toBe(definitionWithoutDisplayName.name);
+        });
+        it('should generate a valid tool schema using the definition and converted schema', () => {
+            const wrapper = new SubagentToolWrapper(mockDefinition, mockConfig, mockMessageBus);
+            const schema = wrapper.schema;
+            expect(schema.name).toBe(mockDefinition.name);
+            expect(schema.description).toBe(mockDefinition.description);
+            expect(schema.parametersJsonSchema).toEqual(mockDefinition.inputConfig.inputSchema);
+        });
+    });
+    describe('createInvocation', () => {
+        it('should create a LocalSubagentInvocation with the correct parameters', () => {
+            const wrapper = new SubagentToolWrapper(mockDefinition, mockConfig, mockMessageBus);
+            const params = { goal: 'Test the invocation', priority: 1 };
+            // The public `build` method calls the protected `createInvocation` after validation
+            const invocation = wrapper.build(params);
+            expect(invocation).toBeInstanceOf(LocalSubagentInvocation);
+            expect(MockedLocalSubagentInvocation).toHaveBeenCalledExactlyOnceWith(mockDefinition, mockConfig, params, mockMessageBus, mockDefinition.name, mockDefinition.displayName);
+        });
+        it('should pass the messageBus to the LocalSubagentInvocation constructor', () => {
+            const specificMessageBus = {
+                publish: vi.fn(),
+                subscribe: vi.fn(),
+                unsubscribe: vi.fn(),
+            };
+            const wrapper = new SubagentToolWrapper(mockDefinition, mockConfig, specificMessageBus);
+            const params = { goal: 'Test the invocation', priority: 1 };
+            wrapper.build(params);
+            expect(MockedLocalSubagentInvocation).toHaveBeenCalledWith(mockDefinition, mockConfig, params, specificMessageBus, mockDefinition.name, mockDefinition.displayName);
+        });
+        it('should throw a validation error for invalid parameters before creating an invocation', () => {
+            const wrapper = new SubagentToolWrapper(mockDefinition, mockConfig, mockMessageBus);
+            // Missing the required 'goal' parameter
+            const invalidParams = { priority: 1 };
+            // The `build` method in the base class performs JSON schema validation
+            // before calling the protected `createInvocation` method.
+            expect(() => wrapper.build(invalidParams)).toThrow("params must have required property 'goal'");
+            expect(MockedLocalSubagentInvocation).not.toHaveBeenCalled();
+        });
+    });
+});
+//# sourceMappingURL=subagent-tool-wrapper.test.js.map

package/dist/src/agents/subagent-tool-wrapper.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-tool-wrapper.test.js","sourceRoot":"","sources":["../../../src/agents/subagent-tool-wrapper.test.ts"],"names":[],"mappings":"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"}

package/dist/src/agents/subagent-tool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseDeclarativeTool, type ToolInvocation, type ToolResult } from '../tools/tools.js';
+import type { Config } from '../config/config.js';
+import type { MessageBus } from '../confirmation-bus/message-bus.js';
+import type { AgentDefinition, AgentInputs } from './types.js';
+export declare class SubagentTool extends BaseDeclarativeTool<AgentInputs, ToolResult> {
+    private readonly definition;
+    private readonly config;
+    constructor(definition: AgentDefinition, config: Config, messageBus: MessageBus);
+    protected createInvocation(params: AgentInputs, messageBus: MessageBus, _toolName?: string, _toolDisplayName?: string): ToolInvocation<AgentInputs, ToolResult>;
+}

package/dist/src/agents/subagent-tool.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseDeclarativeTool, Kind, BaseToolInvocation, } from '../tools/tools.js';
+import { SubagentToolWrapper } from './subagent-tool-wrapper.js';
+import { SchemaValidator } from '../utils/schemaValidator.js';
+export class SubagentTool extends BaseDeclarativeTool {
+    definition;
+    config;
+    constructor(definition, config, messageBus) {
+        const inputSchema = definition.inputConfig.inputSchema;
+        // Validate schema on construction
+        const schemaError = SchemaValidator.validateSchema(inputSchema);
+        if (schemaError) {
+            throw new Error(`Invalid schema for agent ${definition.name}: ${schemaError}`);
+        }
+        super(definition.name, definition.displayName ?? definition.name, definition.description, Kind.Think, inputSchema, messageBus, 
+        /* isOutputMarkdown */ true, 
+        /* canUpdateOutput */ true);
+        this.definition = definition;
+        this.config = config;
+    }
+    createInvocation(params, messageBus, _toolName, _toolDisplayName) {
+        return new SubAgentInvocation(params, this.definition, this.config, messageBus, _toolName, _toolDisplayName);
+    }
+}
+class SubAgentInvocation extends BaseToolInvocation {
+    definition;
+    config;
+    constructor(params, definition, config, messageBus, _toolName, _toolDisplayName) {
+        super(params, messageBus, _toolName ?? definition.name, _toolDisplayName ?? definition.displayName ?? definition.name);
+        this.definition = definition;
+        this.config = config;
+    }
+    getDescription() {
+        return `Delegating to agent '${this.definition.name}'`;
+    }
+    async shouldConfirmExecute(abortSignal) {
+        if (this.definition.kind !== 'remote') {
+            // Local agents should execute without confirmation. Inner tool calls will bubble up their own confirmations to the user.
+            return false;
+        }
+        const invocation = this.buildSubInvocation(this.definition, this.params);
+        return invocation.shouldConfirmExecute(abortSignal);
+    }
+    async execute(signal, updateOutput) {
+        const validationError = SchemaValidator.validate(this.definition.inputConfig.inputSchema, this.params);
+        if (validationError) {
+            throw new Error(`Invalid arguments for agent '${this.definition.name}': ${validationError}. Input schema: ${JSON.stringify(this.definition.inputConfig.inputSchema)}.`);
+        }
+        const invocation = this.buildSubInvocation(this.definition, this.params);
+        return invocation.execute(signal, updateOutput);
+    }
+    buildSubInvocation(definition, agentArgs) {
+        const wrapper = new SubagentToolWrapper(definition, this.config, this.messageBus);
+        return wrapper.build(agentArgs);
+    }
+}
+//# sourceMappingURL=subagent-tool.js.map

package/dist/src/agents/subagent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-tool.js","sourceRoot":"","sources":["../../../src/agents/subagent-tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Defines the core configuration interfaces and types for the agent architecture.
+ */
+import type { Content, FunctionDeclaration, PartListUnion, Tool } from '@google/genai';
+import type { AnyDeclarativeTool } from '../tools/tools.js';
+import { type z } from 'zod';
+import type { ModelConfig, ModelConfigKey } from '../services/modelConfigService.js';
+import type { AnySchema } from 'ajv';
+import type { StreamEvent } from '../providers/gemini/chat.js';
+import type { Config } from '../config/config.js';
+/**
+ * Abstract chat session interface used by agent executors.
+ * Breaks the direct dependency on GeminiChat (Q5 provisional decision).
+ */
+export interface AgentChatSession {
+    sendMessageStream(modelConfigKey: ModelConfigKey, message: PartListUnion, promptId: string, signal: AbortSignal): Promise<AsyncGenerator<StreamEvent>>;
+    setHistory(history: Content[]): void;
+    getHistory(curated?: boolean): Content[];
+    getLastPromptTokenCount(): number;
+}
+/**
+ * Factory function type for creating AgentChatSession instances.
+ * Allows injecting different chat implementations (e.g., for testing or multi-provider).
+ */
+export type ChatSessionFactory = (config: Config, systemInstruction: string | undefined, tools: Tool[], history: Content[]) => AgentChatSession;
+/**
+ * Describes the possible termination modes for an agent.
+ */
+export declare enum AgentTerminateMode {
+    ERROR = "ERROR",
+    TIMEOUT = "TIMEOUT",
+    GOAL = "GOAL",
+    MAX_TURNS = "MAX_TURNS",
+    ABORTED = "ABORTED",
+    ERROR_NO_COMPLETE_TASK_CALL = "ERROR_NO_COMPLETE_TASK_CALL"
+}
+/**
+ * Represents the output structure of an agent's execution.
+ */
+export interface OutputObject {
+    result: string;
+    terminate_reason: AgentTerminateMode;
+}
+/**
+ * The default query string provided to an agent as input.
+ */
+export declare const DEFAULT_QUERY_STRING = "Get Started!";
+/**
+ * Represents the validated input parameters passed to an agent upon invocation.
+ * Used primarily for templating the system prompt. (Replaces ContextState)
+ */
+export type AgentInputs = Record<string, unknown>;
+/**
+ * Simplified input structure for Remote Agents, which consumes a single string query.
+ */
+export type RemoteAgentInputs = {
+    query: string;
+};
+/**
+ * Structured events emitted during subagent execution for user observability.
+ */
+export interface SubagentActivityEvent {
+    isSubagentActivityEvent: true;
+    agentName: string;
+    type: 'TOOL_CALL_START' | 'TOOL_CALL_END' | 'THOUGHT_CHUNK' | 'ERROR';
+    data: Record<string, unknown>;
+}
+/**
+ * The base definition for an agent.
+ * @template TOutput The specific Zod schema for the agent's final output object.
+ */
+export interface BaseAgentDefinition<TOutput extends z.ZodTypeAny = z.ZodUnknown> {
+    /** Unique identifier for the agent. */
+    name: string;
+    displayName?: string;
+    description: string;
+    experimental?: boolean;
+    inputConfig: InputConfig;
+    outputConfig?: OutputConfig<TOutput>;
+    metadata?: {
+        hash?: string;
+        filePath?: string;
+    };
+}
+export interface LocalAgentDefinition<TOutput extends z.ZodTypeAny = z.ZodUnknown> extends BaseAgentDefinition<TOutput> {
+    kind: 'local';
+    promptConfig: PromptConfig;
+    modelConfig: ModelConfig;
+    runConfig: RunConfig;
+    toolConfig?: ToolConfig;
+    /**
+     * An optional function to process the raw output from the agent's final tool
+     * call into a string format.
+     *
+     * @param output The raw output value from the `complete_task` tool, now strongly typed with TOutput.
+     * @returns A string representation of the final output.
+     */
+    processOutput?: (output: z.infer<TOutput>) => string;
+}
+export interface RemoteAgentDefinition<TOutput extends z.ZodTypeAny = z.ZodUnknown> extends BaseAgentDefinition<TOutput> {
+    kind: 'remote';
+    agentCardUrl: string;
+}
+export type AgentDefinition<TOutput extends z.ZodTypeAny = z.ZodUnknown> = LocalAgentDefinition<TOutput> | RemoteAgentDefinition<TOutput>;
+/**
+ * Configures the initial prompt for the agent.
+ */
+export interface PromptConfig {
+    /**
+     * A single system prompt string. Supports templating using `${input_name}` syntax.
+     */
+    systemPrompt?: string;
+    /**
+     * An array of user/model content pairs for few-shot prompting.
+     */
+    initialMessages?: Content[];
+    /**
+     * The specific task or question to trigger the agent's execution loop.
+     * This is sent as the first user message, distinct from the systemPrompt (identity/rules)
+     * and initialMessages (history/few-shots). Supports templating.
+     * If not provided, a generic "Get Started!" message is used.
+     */
+    query?: string;
+}
+/**
+ * Configures the tools available to the agent during its execution.
+ */
+export interface ToolConfig {
+    tools: Array<string | FunctionDeclaration | AnyDeclarativeTool>;
+}
+/**
+ * Configures the expected inputs (parameters) for the agent.
+ */
+export interface InputConfig {
+    inputSchema: AnySchema;
+}
+/**
+ * Configures the expected outputs for the agent.
+ */
+export interface OutputConfig<T extends z.ZodTypeAny> {
+    /**
+     * The name of the final result parameter. This will be the name of the
+     * argument in the `submit_final_output` tool (e.g., "report", "answer").
+     */
+    outputName: string;
+    /**
+     * A description of the expected output. This will be used as the description
+     * for the tool argument.
+     */
+    description: string;
+    /**
+     * Optional JSON schema for the output. If provided, it will be used as the
+     * schema for the tool's argument, allowing for structured output enforcement.
+     * Defaults to { type: 'string' }.
+     */
+    schema: T;
+}
+/**
+ * Configures the execution environment and constraints for the agent.
+ */
+export interface RunConfig {
+    /** The maximum execution time for the agent in minutes. */
+    maxTimeMinutes: number;
+    /** The maximum number of conversational turns. */
+    maxTurns?: number;
+}

package/dist/src/agents/types.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {} from 'zod';
+/**
+ * Describes the possible termination modes for an agent.
+ */
+export var AgentTerminateMode;
+(function (AgentTerminateMode) {
+    AgentTerminateMode["ERROR"] = "ERROR";
+    AgentTerminateMode["TIMEOUT"] = "TIMEOUT";
+    AgentTerminateMode["GOAL"] = "GOAL";
+    AgentTerminateMode["MAX_TURNS"] = "MAX_TURNS";
+    AgentTerminateMode["ABORTED"] = "ABORTED";
+    AgentTerminateMode["ERROR_NO_COMPLETE_TASK_CALL"] = "ERROR_NO_COMPLETE_TASK_CALL";
+})(AgentTerminateMode || (AgentTerminateMode = {}));
+/**
+ * The default query string provided to an agent as input.
+ */
+export const DEFAULT_QUERY_STRING = 'Get Started!';
+//# sourceMappingURL=types.js.map

package/dist/src/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agents/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,EAAU,MAAM,KAAK,CAAC;AA0C7B;;GAEG;AACH,MAAM,CAAN,IAAY,kBAOX;AAPD,WAAY,kBAAkB;IAC5B,qCAAe,CAAA;IACf,yCAAmB,CAAA;IACnB,mCAAa,CAAA;IACb,6CAAuB,CAAA;IACvB,yCAAmB,CAAA;IACnB,iFAA2D,CAAA;AAC7D,CAAC,EAPW,kBAAkB,KAAlB,kBAAkB,QAO7B;AAUD;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AgentInputs } from './types.js';
+/**
+ * Replaces `${...}` placeholders in a template string with values from AgentInputs.
+ *
+ * @param template The template string containing placeholders.
+ * @param inputs The AgentInputs object providing placeholder values.
+ * @returns The populated string with all placeholders replaced.
+ * @throws {Error} if any placeholder key is not found in the inputs.
+ */
+export declare function templateString(template: string, inputs: AgentInputs): string;

package/dist/src/agents/utils.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Replaces `${...}` placeholders in a template string with values from AgentInputs.
+ *
+ * @param template The template string containing placeholders.
+ * @param inputs The AgentInputs object providing placeholder values.
+ * @returns The populated string with all placeholders replaced.
+ * @throws {Error} if any placeholder key is not found in the inputs.
+ */
+export function templateString(template, inputs) {
+    const placeholderRegex = /\$\{(\w+)\}/g;
+    // First, find all unique keys required by the template.
+    const requiredKeys = new Set(Array.from(template.matchAll(placeholderRegex), (match) => match[1]));
+    // Check if all required keys exist in the inputs.
+    const inputKeys = new Set(Object.keys(inputs));
+    const missingKeys = Array.from(requiredKeys).filter((key) => !inputKeys.has(key));
+    if (missingKeys.length > 0) {
+        // Enhanced error message showing both missing and available keys
+        throw new Error(`Template validation failed: Missing required input parameters: ${missingKeys.join(', ')}. ` +
+            `Available inputs: ${Object.keys(inputs).join(', ')}`);
+    }
+    // Perform the replacement using a replacer function.
+    return template.replace(placeholderRegex, (_match, key) => String(inputs[key]));
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/agents/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/agents/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,MAAmB;IAClE,MAAM,gBAAgB,GAAG,cAAc,CAAC;IAExC,wDAAwD;IACxD,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACrE,CAAC;IAEF,kDAAkD;IAClD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,CACjD,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAC7B,CAAC;IAEF,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,iEAAiE;QACjE,MAAM,IAAI,KAAK,CACb,kEAAkE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC1F,qBAAqB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,OAAO,QAAQ,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,CACxD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CACpB,CAAC;AACJ,CAAC"}

package/dist/src/agents/utils.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/agents/utils.test.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { templateString } from './utils.js';
+describe('templateString', () => {
+    it('should replace a single placeholder with a string value', () => {
+        const template = 'Hello, ${name}!';
+        const inputs = { name: 'World' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('Hello, World!');
+    });
+    it('should replace multiple unique placeholders', () => {
+        const template = 'User: ${user}, Role: ${role}';
+        const inputs = { user: 'Alex', role: 'Admin' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('User: Alex, Role: Admin');
+    });
+    it('should replace multiple instances of the same placeholder', () => {
+        const template = '${greeting}, ${user}. Welcome, ${user}!';
+        const inputs = { greeting: 'Hi', user: 'Sam' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('Hi, Sam. Welcome, Sam!');
+    });
+    it('should handle various data types for input values', () => {
+        const template = 'Name: ${name}, Age: ${age}, Active: ${isActive}, Plan: ${plan}, Score: ${score}';
+        const inputs = {
+            name: 'Jo',
+            age: 30,
+            isActive: true,
+            plan: null,
+            score: undefined,
+        };
+        const result = templateString(template, inputs);
+        // All values are converted to their string representations
+        expect(result).toBe('Name: Jo, Age: 30, Active: true, Plan: null, Score: undefined');
+    });
+    it('should return the original string if no placeholders are present', () => {
+        const template = 'This is a plain string with no placeholders.';
+        const inputs = { key: 'value' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('This is a plain string with no placeholders.');
+    });
+    it('should correctly handle an empty template string', () => {
+        const template = '';
+        const inputs = { key: 'value' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('');
+    });
+    it('should ignore extra keys in the inputs object that are not in the template', () => {
+        const template = 'Hello, ${name}.';
+        const inputs = { name: 'Alice', extra: 'ignored' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('Hello, Alice.');
+    });
+    it('should throw an error if a required key is missing from the inputs', () => {
+        const template = 'The goal is ${goal}.';
+        const inputs = { other_input: 'some value' };
+        expect(() => templateString(template, inputs)).toThrow('Template validation failed: Missing required input parameters: goal. Available inputs: other_input');
+    });
+    it('should throw an error listing all missing keys if multiple are missing', () => {
+        const template = 'Analyze ${file} with ${tool}.';
+        const inputs = { an_available_key: 'foo' };
+        // Using a regex to allow for any order of missing keys in the error message
+        expect(() => templateString(template, inputs)).toThrow(/Missing required input parameters: (file, tool|tool, file)/);
+    });
+    it('should be case-sensitive with placeholder keys', () => {
+        const template = 'Value: ${Key}';
+        const inputs = { key: 'some value' }; // 'key' is lowercase
+        expect(() => templateString(template, inputs)).toThrow('Template validation failed: Missing required input parameters: Key. Available inputs: key');
+    });
+    it('should not replace malformed or incomplete placeholders', () => {
+        const template = 'This is {not_a_placeholder} and this is $$escaped. Test: ${valid}';
+        const inputs = { valid: 'works' };
+        const result = templateString(template, inputs);
+        expect(result).toBe('This is {not_a_placeholder} and this is $$escaped. Test: works');
+    });
+    it('should work correctly with an empty inputs object if the template has no placeholders', () => {
+        const template = 'Static text.';
+        const inputs = {};
+        const result = templateString(template, inputs);
+        expect(result).toBe('Static text.');
+    });
+});
+//# sourceMappingURL=utils.test.js.map