@blackbox_ai/blackbox-cli-core 0.0.4

package/dist/src/subagents/builtin-agents.js

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Registry of built-in subagents that are always available to all users.
+ * These agents are embedded in the codebase and cannot be modified or deleted.
+ */
+export class BuiltinAgentRegistry {
+    static BUILTIN_AGENTS = [
+        {
+            name: 'general-purpose',
+            description: 'General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.',
+            systemPrompt: `You are a general-purpose research and code analysis agent. Given the user's message, you should use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: Use Grep or Glob when you need to search broadly. Use Read when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
+- For clear communication, avoid using emojis.
+
+
+Notes:
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
+- For clear communication with the user the assistant MUST avoid using emojis.`,
+        },
+    ];
+    /**
+     * Gets all built-in agent configurations.
+     * @returns Array of built-in subagent configurations
+     */
+    static getBuiltinAgents() {
+        return this.BUILTIN_AGENTS.map((agent) => ({
+            ...agent,
+            level: 'builtin',
+            filePath: `<builtin:${agent.name}>`,
+            isBuiltin: true,
+        }));
+    }
+    /**
+     * Gets a specific built-in agent by name.
+     * @param name - Name of the built-in agent
+     * @returns Built-in agent configuration or null if not found
+     */
+    static getBuiltinAgent(name) {
+        const agent = this.BUILTIN_AGENTS.find((a) => a.name === name);
+        if (!agent) {
+            return null;
+        }
+        return {
+            ...agent,
+            level: 'builtin',
+            filePath: `<builtin:${name}>`,
+            isBuiltin: true,
+        };
+    }
+    /**
+     * Checks if an agent name corresponds to a built-in agent.
+     * @param name - Agent name to check
+     * @returns True if the name is a built-in agent
+     */
+    static isBuiltinAgent(name) {
+        return this.BUILTIN_AGENTS.some((agent) => agent.name === name);
+    }
+    /**
+     * Gets the names of all built-in agents.
+     * @returns Array of built-in agent names
+     */
+    static getBuiltinAgentNames() {
+        return this.BUILTIN_AGENTS.map((agent) => agent.name);
+    }
+}
+//# sourceMappingURL=builtin-agents.js.map

package/dist/src/subagents/builtin-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.js","sourceRoot":"","sources":["../../../src/subagents/builtin-agents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IACvB,MAAM,CAAU,cAAc,GAElC;QACF;YACE,IAAI,EAAE,iBAAiB;YACvB,WAAW,EACT,yRAAyR;YAC3R,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;+EAsB2D;SAC1E;KACF,CAAC;IAEF;;;OAGG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACzC,GAAG,KAAK;YACR,KAAK,EAAE,SAAkB;YACzB,QAAQ,EAAE,YAAY,KAAK,CAAC,IAAI,GAAG;YACnC,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,IAAY;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO;YACL,GAAG,KAAK;YACR,KAAK,EAAE,SAAkB;YACzB,QAAQ,EAAE,YAAY,IAAI,GAAG;YAC7B,SAAS,EAAE,IAAI;SAChB,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,IAAY;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAClE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,oBAAoB;QACzB,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC"}

package/dist/src/subagents/builtin-agents.test.d.ts

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

package/dist/src/subagents/builtin-agents.test.js

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { BuiltinAgentRegistry } from './builtin-agents.js';
+describe('BuiltinAgentRegistry', () => {
+    describe('getBuiltinAgents', () => {
+        it('should return array of builtin agents with correct properties', () => {
+            const agents = BuiltinAgentRegistry.getBuiltinAgents();
+            expect(agents).toBeInstanceOf(Array);
+            expect(agents.length).toBeGreaterThan(0);
+            agents.forEach((agent) => {
+                expect(agent).toMatchObject({
+                    name: expect.any(String),
+                    description: expect.any(String),
+                    systemPrompt: expect.any(String),
+                    level: 'builtin',
+                    filePath: `<builtin:${agent.name}>`,
+                    isBuiltin: true,
+                });
+            });
+        });
+        it('should include general-purpose agent', () => {
+            const agents = BuiltinAgentRegistry.getBuiltinAgents();
+            const generalAgent = agents.find((agent) => agent.name === 'general-purpose');
+            expect(generalAgent).toBeDefined();
+            expect(generalAgent?.description).toContain('General-purpose agent');
+        });
+    });
+    describe('getBuiltinAgent', () => {
+        it('should return correct agent for valid name', () => {
+            const agent = BuiltinAgentRegistry.getBuiltinAgent('general-purpose');
+            expect(agent).toMatchObject({
+                name: 'general-purpose',
+                level: 'builtin',
+                filePath: '<builtin:general-purpose>',
+                isBuiltin: true,
+            });
+        });
+        it('should return null for invalid name', () => {
+            expect(BuiltinAgentRegistry.getBuiltinAgent('invalid')).toBeNull();
+            expect(BuiltinAgentRegistry.getBuiltinAgent('')).toBeNull();
+        });
+    });
+    describe('isBuiltinAgent', () => {
+        it('should return true for valid builtin agent names', () => {
+            expect(BuiltinAgentRegistry.isBuiltinAgent('general-purpose')).toBe(true);
+        });
+        it('should return false for invalid names', () => {
+            expect(BuiltinAgentRegistry.isBuiltinAgent('invalid')).toBe(false);
+            expect(BuiltinAgentRegistry.isBuiltinAgent('')).toBe(false);
+        });
+    });
+    describe('getBuiltinAgentNames', () => {
+        it('should return array of agent names', () => {
+            const names = BuiltinAgentRegistry.getBuiltinAgentNames();
+            expect(names).toBeInstanceOf(Array);
+            expect(names).toContain('general-purpose');
+            expect(names.every((name) => typeof name === 'string')).toBe(true);
+        });
+    });
+    describe('consistency', () => {
+        it('should maintain consistency across all methods', () => {
+            const agents = BuiltinAgentRegistry.getBuiltinAgents();
+            const names = BuiltinAgentRegistry.getBuiltinAgentNames();
+            // Names should match agents
+            expect(names).toEqual(agents.map((agent) => agent.name));
+            // Each name should be valid
+            names.forEach((name) => {
+                expect(BuiltinAgentRegistry.isBuiltinAgent(name)).toBe(true);
+                expect(BuiltinAgentRegistry.getBuiltinAgent(name)).toBeDefined();
+            });
+        });
+    });
+});
+//# sourceMappingURL=builtin-agents.test.js.map

package/dist/src/subagents/builtin-agents.test.js.map

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

package/dist/src/subagents/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Subagents Phase 1 implementation - File-based configuration layer
+ *
+ * This module provides the foundation for the subagents feature by implementing
+ * a file-based configuration system that builds on the existing SubAgentScope
+ * runtime system. It includes:
+ *
+ * - Type definitions for file-based subagent configurations
+ * - Validation system for configuration integrity
+ * - Runtime conversion functions integrated into the manager
+ * - Manager class for CRUD operations on subagent files
+ *
+ * The implementation follows the Markdown + YAML frontmatter format , with storage at both project and user levels.
+ */
+export type { SubagentConfig, SubagentLevel, SubagentRuntimeConfig, ValidationResult, ListSubagentsOptions, CreateSubagentOptions, SubagentErrorCode, } from './types.js';
+export { SubagentError } from './types.js';
+export { BuiltinAgentRegistry } from './builtin-agents.js';
+export { SubagentValidator } from './validation.js';
+export { SubagentManager } from './subagent-manager.js';
+export type { PromptConfig, ModelConfig, RunConfig, ToolConfig, SubagentTerminateMode, } from './types.js';
+export { SubAgentScope } from './subagent.js';
+export type { SubAgentEvent, SubAgentStartEvent, SubAgentRoundEvent, SubAgentStreamTextEvent, SubAgentToolCallEvent, SubAgentToolResultEvent, SubAgentFinishEvent, SubAgentErrorEvent, } from './subagent-events.js';
+export { SubAgentEventEmitter } from './subagent-events.js';
+export type { SubagentStatsSummary, ToolUsageStats, } from './subagent-statistics.js';

package/dist/src/subagents/index.js

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { SubagentError } from './types.js';
+// Built-in agents registry
+export { BuiltinAgentRegistry } from './builtin-agents.js';
+// Validation system
+export { SubagentValidator } from './validation.js';
+// Main management class
+export { SubagentManager } from './subagent-manager.js';
+export { SubAgentScope } from './subagent.js';
+export { SubAgentEventEmitter } from './subagent-events.js';
+//# sourceMappingURL=index.js.map

package/dist/src/subagents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/subagents/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4BH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,2BAA2B;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,oBAAoB;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,wBAAwB;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAWxD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAc9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/subagents/subagent-events.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ToolCallConfirmationDetails, ToolConfirmationOutcome } from '../tools/tools.js';
+export type SubAgentEvent = 'start' | 'round_start' | 'round_end' | 'stream_text' | 'tool_call' | 'tool_result' | 'tool_waiting_approval' | 'finish' | 'error';
+export declare enum SubAgentEventType {
+    START = "start",
+    ROUND_START = "round_start",
+    ROUND_END = "round_end",
+    STREAM_TEXT = "stream_text",
+    TOOL_CALL = "tool_call",
+    TOOL_RESULT = "tool_result",
+    TOOL_WAITING_APPROVAL = "tool_waiting_approval",
+    FINISH = "finish",
+    ERROR = "error"
+}
+export interface SubAgentStartEvent {
+    subagentId: string;
+    name: string;
+    model?: string;
+    tools: string[];
+    timestamp: number;
+}
+export interface SubAgentRoundEvent {
+    subagentId: string;
+    round: number;
+    promptId: string;
+    timestamp: number;
+}
+export interface SubAgentStreamTextEvent {
+    subagentId: string;
+    round: number;
+    text: string;
+    timestamp: number;
+}
+export interface SubAgentToolCallEvent {
+    subagentId: string;
+    round: number;
+    callId: string;
+    name: string;
+    args: Record<string, unknown>;
+    description: string;
+    timestamp: number;
+}
+export interface SubAgentToolResultEvent {
+    subagentId: string;
+    round: number;
+    callId: string;
+    name: string;
+    success: boolean;
+    error?: string;
+    resultDisplay?: string;
+    durationMs?: number;
+    timestamp: number;
+}
+export interface SubAgentApprovalRequestEvent {
+    subagentId: string;
+    round: number;
+    callId: string;
+    name: string;
+    description: string;
+    confirmationDetails: Omit<ToolCallConfirmationDetails, 'onConfirm'> & {
+        type: ToolCallConfirmationDetails['type'];
+    };
+    respond: (outcome: ToolConfirmationOutcome, payload?: Parameters<ToolCallConfirmationDetails['onConfirm']>[1]) => Promise<void>;
+    timestamp: number;
+}
+export interface SubAgentFinishEvent {
+    subagentId: string;
+    terminateReason: string;
+    timestamp: number;
+    rounds?: number;
+    totalDurationMs?: number;
+    totalToolCalls?: number;
+    successfulToolCalls?: number;
+    failedToolCalls?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface SubAgentErrorEvent {
+    subagentId: string;
+    error: string;
+    timestamp: number;
+}
+export declare class SubAgentEventEmitter {
+    private ee;
+    on(event: SubAgentEvent, listener: (...args: unknown[]) => void): void;
+    off(event: SubAgentEvent, listener: (...args: unknown[]) => void): void;
+    emit(event: SubAgentEvent, payload: unknown): void;
+}

package/dist/src/subagents/subagent-events.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { EventEmitter } from 'events';
+export var SubAgentEventType;
+(function (SubAgentEventType) {
+    SubAgentEventType["START"] = "start";
+    SubAgentEventType["ROUND_START"] = "round_start";
+    SubAgentEventType["ROUND_END"] = "round_end";
+    SubAgentEventType["STREAM_TEXT"] = "stream_text";
+    SubAgentEventType["TOOL_CALL"] = "tool_call";
+    SubAgentEventType["TOOL_RESULT"] = "tool_result";
+    SubAgentEventType["TOOL_WAITING_APPROVAL"] = "tool_waiting_approval";
+    SubAgentEventType["FINISH"] = "finish";
+    SubAgentEventType["ERROR"] = "error";
+})(SubAgentEventType || (SubAgentEventType = {}));
+export class SubAgentEventEmitter {
+    ee = new EventEmitter();
+    on(event, listener) {
+        this.ee.on(event, listener);
+    }
+    off(event, listener) {
+        this.ee.off(event, listener);
+    }
+    emit(event, payload) {
+        this.ee.emit(event, payload);
+    }
+}
+//# sourceMappingURL=subagent-events.js.map

package/dist/src/subagents/subagent-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-events.js","sourceRoot":"","sources":["../../../src/subagents/subagent-events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAiBtC,MAAM,CAAN,IAAY,iBAUX;AAVD,WAAY,iBAAiB;IAC3B,oCAAe,CAAA;IACf,gDAA2B,CAAA;IAC3B,4CAAuB,CAAA;IACvB,gDAA2B,CAAA;IAC3B,4CAAuB,CAAA;IACvB,gDAA2B,CAAA;IAC3B,oEAA+C,CAAA;IAC/C,sCAAiB,CAAA;IACjB,oCAAe,CAAA;AACjB,CAAC,EAVW,iBAAiB,KAAjB,iBAAiB,QAU5B;AAkFD,MAAM,OAAO,oBAAoB;IACvB,EAAE,GAAG,IAAI,YAAY,EAAE,CAAC;IAEhC,EAAE,CAAC,KAAoB,EAAE,QAAsC;QAC7D,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED,GAAG,CAAC,KAAoB,EAAE,QAAsC;QAC9D,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,KAAoB,EAAE,OAAgB;QACzC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/src/subagents/subagent-hooks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface PreToolUsePayload {
+    subagentId: string;
+    name: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    timestamp: number;
+}
+export interface PostToolUsePayload extends PreToolUsePayload {
+    success: boolean;
+    durationMs: number;
+    errorMessage?: string;
+}
+export interface SubagentStopPayload {
+    subagentId: string;
+    name: string;
+    terminateReason: string;
+    summary: Record<string, unknown>;
+    timestamp: number;
+}
+export interface SubagentHooks {
+    preToolUse?(payload: PreToolUsePayload): Promise<void> | void;
+    postToolUse?(payload: PostToolUsePayload): Promise<void> | void;
+    onStop?(payload: SubagentStopPayload): Promise<void> | void;
+}

package/dist/src/subagents/subagent-hooks.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=subagent-hooks.js.map

package/dist/src/subagents/subagent-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-hooks.js","sourceRoot":"","sources":["../../../src/subagents/subagent-hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/subagents/subagent-manager.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * Copyright 2025 Blackbox
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SubagentConfig, SubagentRuntimeConfig, SubagentLevel, ListSubagentsOptions, CreateSubagentOptions } from './types.js';
+import { SubAgentScope } from './subagent.js';
+import type { Config } from '../config/config.js';
+/**
+ * Manages subagent configurations stored as Markdown files with YAML frontmatter.
+ * Provides CRUD operations, validation, and integration with the runtime system.
+ */
+export declare class SubagentManager {
+    private readonly config;
+    private readonly validator;
+    private subagentsCache;
+    private readonly changeListeners;
+    constructor(config: Config);
+    addChangeListener(listener: () => void): () => void;
+    private notifyChangeListeners;
+    /**
+     * Creates a new subagent configuration.
+     *
+     * @param config - Subagent configuration to create
+     * @param options - Creation options
+     * @throws SubagentError if creation fails
+     */
+    createSubagent(config: SubagentConfig, options: CreateSubagentOptions): Promise<void>;
+    /**
+     * Loads a subagent configuration by name.
+     * If level is specified, only searches that level.
+     * If level is omitted, searches project-level first, then user-level, then built-in.
+     *
+     * @param name - Name of the subagent to load
+     * @param level - Optional level to limit search to specific level
+     * @returns SubagentConfig or null if not found
+     */
+    loadSubagent(name: string, level?: SubagentLevel): Promise<SubagentConfig | null>;
+    /**
+     * Updates an existing subagent configuration.
+     *
+     * @param name - Name of the subagent to update
+     * @param updates - Partial configuration updates
+     * @throws SubagentError if subagent not found or update fails
+     */
+    updateSubagent(name: string, updates: Partial<SubagentConfig>, level?: SubagentLevel): Promise<void>;
+    /**
+     * Deletes a subagent configuration.
+     *
+     * @param name - Name of the subagent to delete
+     * @param level - Specific level to delete from, or undefined to delete from both
+     * @throws SubagentError if deletion fails
+     */
+    deleteSubagent(name: string, level?: SubagentLevel): Promise<void>;
+    /**
+     * Lists all available subagents.
+     *
+     * @param options - Filtering and sorting options
+     * @returns Array of subagent metadata
+     */
+    listSubagents(options?: ListSubagentsOptions): Promise<SubagentConfig[]>;
+    /**
+     * Refreshes the subagents cache by loading all subagents from disk.
+     * This method is called automatically when cache is null or when force=true.
+     *
+     * @private
+     */
+    private refreshCache;
+    /**
+     * Finds a subagent by name and returns its metadata.
+     *
+     * @param name - Name of the subagent to find
+     * @returns SubagentConfig or null if not found
+     */
+    findSubagentByName(name: string, level?: SubagentLevel): Promise<SubagentConfig | null>;
+    /**
+     * Parses a subagent file and returns the configuration.
+     *
+     * @param filePath - Path to the subagent file
+     * @returns SubagentConfig
+     * @throws SubagentError if parsing fails
+     */
+    parseSubagentFile(filePath: string, level: SubagentLevel): Promise<SubagentConfig>;
+    /**
+     * Parses subagent content from a string.
+     *
+     * @param content - File content
+     * @param filePath - File path for error reporting
+     * @returns SubagentConfig
+     * @throws SubagentError if parsing fails
+     */
+    parseSubagentContent(content: string, filePath: string, level: SubagentLevel): SubagentConfig;
+    /**
+     * Serializes a subagent configuration to Markdown format.
+     *
+     * @param config - Configuration to serialize
+     * @returns Markdown content with YAML frontmatter
+     */
+    serializeSubagent(config: SubagentConfig): string;
+    /**
+     * Creates a SubAgentScope from a subagent configuration.
+     *
+     * @param config - Subagent configuration
+     * @param runtimeContext - Runtime context
+     * @returns Promise resolving to SubAgentScope
+     */
+    createSubagentScope(config: SubagentConfig, runtimeContext: Config, options?: {
+        eventEmitter?: import('./subagent-events.js').SubAgentEventEmitter;
+        hooks?: import('./subagent-hooks.js').SubagentHooks;
+    }): Promise<SubAgentScope>;
+    /**
+     * Converts a file-based SubagentConfig to runtime configuration
+     * compatible with SubAgentScope.create().
+     *
+     * @param config - File-based subagent configuration
+     * @returns Runtime configuration for SubAgentScope
+     */
+    convertToRuntimeConfig(config: SubagentConfig): SubagentRuntimeConfig;
+    /**
+     * Transforms a tools array that may contain tool names or display names
+     * into an array containing only tool names.
+     *
+     * @param tools - Array of tool names or display names
+     * @returns Array of tool names
+     * @private
+     */
+    private transformToToolNames;
+    /**
+     * Merges partial configurations with defaults, useful for updating
+     * existing configurations.
+     *
+     * @param base - Base configuration
+     * @param updates - Partial updates to apply
+     * @returns New configuration with updates applied
+     */
+    mergeConfigurations(base: SubagentConfig, updates: Partial<SubagentConfig>): SubagentConfig;
+    /**
+     * Gets the file path for a subagent at a specific level.
+     *
+     * @param name - Subagent name
+     * @param level - Storage level
+     * @returns Absolute file path
+     */
+    getSubagentPath(name: string, level: SubagentLevel): string;
+    /**
+     * Lists subagent files at a specific level.
+     * Handles both builtin agents and file-based agents.
+     *
+     * @param level - Storage level to scan
+     * @returns Array of subagent configurations
+     */
+    private listSubagentsAtLevel;
+    /**
+     * Finds a subagent by name at a specific level by scanning all files.
+     * This method ensures we find subagents even if the filename doesn't match the name.
+     *
+     * @param name - Name of the subagent to find
+     * @param level - Storage level to search
+     * @returns SubagentConfig or null if not found
+     */
+    private findSubagentByNameAtLevel;
+    /**
+     * Validates that a subagent name is available (not already in use).
+     *
+     * @param name - Name to check
+     * @param level - Level to check, or undefined to check both
+     * @returns True if name is available
+     */
+    isNameAvailable(name: string, level?: SubagentLevel): Promise<boolean>;
+}