import type { CapabilityMetadata, CapabilityInput, CapabilityModelConfigOverride, CapabilityProviderMetadata, CapabilityId } from '@bubblelab/shared-schemas';
import type { CredentialType, BubbleName } from '@bubblelab/shared-schemas';
import type { ToolHookBefore, ToolHookAfter } from '../bubbles/service-bubble/ai-agent.js';
import type { BubbleContext } from '../types/bubble.js';
import { z } from 'zod';
/** Runtime context passed to capability tool factories and system prompt factories. */
export interface CapabilityRuntimeContext {
    credentials: Partial<Record<CredentialType, string>>;
    /** Metadata-only credential pool — no secrets. For capabilities that need to
     *  disambiguate between multiple credentials of the same type (e.g., data-analyst
     *  routing to "readonly" vs "write" PostgreSQL). */
    credentialPoolMeta?: Partial<Record<CredentialType, Array<{
        id: number;
        name: string;
    }>>>;
    inputs: Record<string, string | number | boolean | string[]>;
    bubbleContext?: BubbleContext;
    /** Free-text context from the capability config, injected into the subagent system prompt. */
    context?: string;
}
/** A single capability tool function that accepts parsed parameters and returns a result. */
export type CapabilityToolFunc = (params: Record<string, unknown>) => Promise<unknown>;
/** Factory that creates tool functions given a runtime context. */
export type CapabilityToolFactory = (context: CapabilityRuntimeContext) => Record<string, CapabilityToolFunc>;
/** Factory that creates a system prompt addition given a runtime context. */
export type CapabilitySystemPromptFactory = (context: CapabilityRuntimeContext) => string | Promise<string>;
/** Factory that creates a delegation hint given a runtime context. */
export type CapabilityDelegationHintFactory = (context: CapabilityRuntimeContext) => string | Promise<string>;
/** Factory that creates text to append to the agent's final response. */
export type CapabilityResponseAppendFactory = (context: CapabilityRuntimeContext) => string | Promise<string>;
/** Full runtime capability definition with metadata + factories. */
export interface CapabilityDefinition {
    metadata: CapabilityMetadata;
    createTools: CapabilityToolFactory;
    createSystemPrompt?: CapabilitySystemPromptFactory;
    /** Async factory that resolves a delegation hint at runtime (multi-cap mode). */
    createDelegationHint?: CapabilityDelegationHintFactory;
    /** Called after the agent finishes — returned text is appended to the response. */
    createResponseAppend?: CapabilityResponseAppendFactory;
    hooks?: {
        beforeToolCall?: ToolHookBefore;
        afterToolCall?: ToolHookAfter;
    };
}
/** Options for the defineCapability() helper — ergonomic API for creating capabilities. */
export interface DefineCapabilityOptions {
    id: CapabilityId;
    name: string;
    description: string;
    icon?: string;
    category?: string;
    version?: string;
    requiredCredentials: CredentialType[];
    optionalCredentials?: CredentialType[];
    inputs: CapabilityInput[];
    tools: Array<{
        name: string;
        description: string;
        schema: z.ZodObject<z.ZodRawShape>;
        /** Bubble names used internally by this tool (e.g., ['google-drive']). */
        internalBubbles?: BubbleName[];
        /** Whether this tool requires human approval before execution. */
        requiresApproval?: boolean;
        /** Expose this tool directly on the master agent in multi-capability delegation mode. */
        masterTool?: boolean;
        func: (ctx: CapabilityRuntimeContext) => CapabilityToolFunc;
    }>;
    systemPrompt?: string | CapabilitySystemPromptFactory;
    /** Text (or async factory) to append to the agent's final response. */
    responseAppend?: string | CapabilityResponseAppendFactory;
    hooks?: CapabilityDefinition['hooks'];
    /** Optional model config overrides applied at runtime (e.g., force a specific model or raise maxTokens). */
    modelConfigOverride?: CapabilityModelConfigOverride;
    /**
     * When true and this capability runs as a sub-agent, inherit the parent
     * agent's model + reasoningEffort from executionMeta._pearlChatModelOverride.
     * Other modelConfigOverride fields (maxTokens, maxIterations) still apply.
     */
    inheritParentModel?: boolean;
    /** Short guidance for the main agent on when to delegate to this capability in multi-capability mode. */
    delegationHint?: string | CapabilityDelegationHintFactory;
    /** Hidden capabilities are registered for runtime use but not shown in the UI. */
    hidden?: boolean;
    /** Data-driven provider options for the wizard "Choose Providers" step. */
    providers?: CapabilityProviderMetadata[];
}
/**
 * Creates a CapabilityDefinition from a user-friendly options object.
 * Converts Zod schemas to JSON Schema for serializable metadata,
 * and wraps tool functions with context currying.
 */
export declare function defineCapability(options: DefineCapabilityOptions): CapabilityDefinition;
//# sourceMappingURL=define-capability.d.ts.map