/**
 * SDK helper — invoke a CLEO meta-agent from the `@cleocode/agents/meta/` directory.
 *
 * Meta-agents (agent-architect, playbook-architect) synthesize project-specific
 * artifacts from templates + context. This module provides the invocation shim
 * used by `initProject({ installSeedAgents: true })` and `cleo agent mint`.
 *
 * Invocation mechanism (ADR-055 R1 resolution):
 *   1. Preferred: subprocess via `cleo orchestrate spawn <agentId> --no-worktree`
 *      This leverages the full CANT runtime, token injection, and spawn prompt.
 *   2. Fallback: when the CANT runtime is unavailable or dry-run is requested,
 *      skip invocation and return a `{ invoked: false, reason }` result. The
 *      caller is responsible for falling back to static seed-agent copy.
 *
 * User profile + project-context threading (AC6 / W3):
 *   `invokeMetaAgent()` reads `.cleo/project-context.json` and optionally calls
 *   `listUserProfile(nexusDb)` to build the token payload passed to the meta-agent.
 *   Both are serialized as JSON token args in the spawn invocation.
 *
 * @module agents/invoke-meta-agent
 * @task T1272 v2026.4.127 T1259 E2 agent-architect invocation shim
 * @task T1273 v2026.4.127 T1259 E2 user_profile + project-context threading
 */
/**
 * Result of invoking a meta-agent.
 *
 * When `invoked: true` the agent completed successfully and `outputs` contains
 * the list of artifact filenames it reported (one per emitted line).
 *
 * When `invoked: false` the caller should fall back to static seed-agent copy.
 */
export interface MetaAgentResult {
    /** Whether the meta-agent was actually invoked. */
    invoked: boolean;
    /**
     * Reason for skipping invocation (only set when `invoked: false`).
     * Consumers may surface this as a warning log line.
     */
    reason?: string;
    /**
     * Artifact filenames reported by the meta-agent (lines matching
     * `agent-created: <name>.cant` or `playbook-created: <name>.cantbook`).
     * Only populated when `invoked: true`.
     */
    outputs?: string[];
    /** Raw stdout from the meta-agent process (for debugging). */
    stdout?: string;
}
/**
 * Token payload threaded into the meta-agent spawn invocation.
 *
 * Corresponds to the `tokens` block in `agent-architect.cant` and
 * `playbook-architect.cant`. Required tokens must be populated; optional
 * tokens may be omitted (meta-agent uses defaults).
 */
export interface MetaAgentTokens {
    /** Project name, kebab-case (e.g. "cleocode"). Required for agent-architect. */
    PROJECT_NAME?: string;
    /** Absolute path where the agent will write output .cant files. */
    CANT_AGENTS_DIR?: string;
    /** Semantic version of the agents bundle (e.g. "2026.4.127"). */
    BUNDLE_VERSION?: string;
    /** Serialized project-context.json (optional, improves synthesis quality). */
    PROJECT_CONTEXT?: string;
    /** Serialized user_profile rows as JSON array (optional). */
    USER_PROFILE?: string;
    /** Model override (e.g. "sonnet", "haiku"). Empty = use agent default. */
    MODEL_OVERRIDE?: string;
    /** Tier override. Empty = use agent default. */
    TIER_OVERRIDE?: string;
    /** Serialized skills list JSON array (e.g. ["ct-cleo", "ct-orchestrator"]). */
    SKILLS_JSON?: string;
    /** Serialized domains object JSON (e.g. {"tasks": "read"}). */
    DOMAINS_JSON?: string;
    /** Playbook name (used by playbook-architect only). */
    PLAYBOOK_NAME?: string;
    /** Workflow description (used by playbook-architect only). */
    WORKFLOW_DESCRIPTION?: string;
    /** Output directory for the .cantbook file (used by playbook-architect only). */
    OUTPUT_DIR?: string;
}
/**
 * Options for {@link invokeMetaAgent}.
 */
export interface InvokeMetaAgentOptions {
    /**
     * Meta-agent name without extension (e.g. "agent-architect").
     * Must match a file in `@cleocode/agents/meta/<name>.cant`.
     */
    agentName: string;
    /**
     * Absolute path to the project root (CWD for the subprocess).
     * Defaults to `process.cwd()`.
     */
    projectRoot?: string;
    /**
     * Token payload to thread into the spawn invocation.
     * Maps to the `tokens` block in the meta-agent's .cant file.
     */
    tokens?: MetaAgentTokens;
    /**
     * Optional open handle to `nexus.db` (Drizzle `NodeSQLiteDatabase`) for
     * reading user_profile rows. When provided, `invokeMetaAgent()` calls
     * `listUserProfile(nexusDb)` and threads the result as `USER_PROFILE` in
     * the token payload.
     *
     * Typed as `unknown` to avoid importing the heavy Drizzle type graph here.
     * The inner `listUserProfile` call uses a dynamic import and handles the cast.
     */
    nexusDb?: any;
    /**
     * When `true`, skip subprocess invocation and return immediately with
     * `{ invoked: false, reason: 'dry-run' }`.
     * Default: false.
     */
    dryRun?: boolean;
}
/**
 * Invoke a CLEO meta-agent from the `@cleocode/agents/meta/` directory.
 *
 * Builds a rich token payload from project-context.json + user_profile, then
 * attempts to invoke the meta-agent via `cleo orchestrate spawn <agentName>
 * --no-worktree` in a subprocess. Falls back gracefully when the meta-agent
 * cannot be located or the subprocess fails.
 *
 * @param options - See {@link InvokeMetaAgentOptions}.
 * @returns A {@link MetaAgentResult} describing the outcome.
 *
 * @example
 * ```typescript
 * const result = await invokeMetaAgent({
 *   agentName: 'agent-architect',
 *   projectRoot: '/path/to/project',
 *   tokens: {
 *     PROJECT_NAME: 'my-app',
 *     CANT_AGENTS_DIR: '/path/to/project/.cleo/cant/agents',
 *     BUNDLE_VERSION: '2026.4.127',
 *   },
 *   nexusDb,
 * });
 *
 * if (!result.invoked) {
 *   // Fall back to static seed-agent copy
 *   console.warn('Meta-agent unavailable:', result.reason);
 * }
 * ```
 *
 * @task T1272 — invocation shim
 * @task T1273 — user_profile + project-context threading
 */
export declare function invokeMetaAgent(options: InvokeMetaAgentOptions): Promise<MetaAgentResult>;
/**
 * Build the standard token payload for `agent-architect` invocation.
 *
 * Convenience wrapper around {@link invokeMetaAgent} for the primary use case:
 * `cleo init --install-seed-agents`.
 *
 * @param projectRoot - Absolute path to the project root.
 * @param cantAgentsDir - Absolute path where agent-architect writes output .cant files.
 * @param bundleVersion - Semantic version string (e.g. "2026.4.127").
 * @param nexusDb - Optional open nexus.db handle for user_profile threading.
 * @returns A {@link MetaAgentResult}.
 *
 * @task T1272
 * @task T1273
 */
export declare function invokeAgentArchitect(projectRoot: string, cantAgentsDir: string, bundleVersion: string, nexusDb?: any): Promise<MetaAgentResult>;
//# sourceMappingURL=invoke-meta-agent.d.ts.map