/**
 * spawnAgent orchestrator — entry point for the agent tool's `spawn` action.
 * Spec: §4.1.1 — TEMPLATE → RESOLVE → MODEL_CHECK → ISOLATION_ROUTE → INSTANCE → REGISTER
 */
import type { AgentLifecycle } from "@pi-orca/core";
import type { ResolvedAgentTemplate } from "./template.js";
import type { SpawnRespawnSpec } from "./spawners/sdk.js";
export type { SpawnRespawnSpec } from "./spawners/sdk.js";
import { type ChildBootWatchdog } from "./verify-child-boot.js";
import { type GitExec } from "./worktree.js";
export interface SpawnAgentParams {
    /** Template name to instantiate (e.g., "scout") */
    templateName: string;
    /** Optional initial task; agent runs idle if omitted */
    task?: string;
    /** Parent session info — required for status path resolution */
    parent: {
        sessionId: string;
        sessionPath: string;
        /** Absolute path to the parent's session file (for forkFrom) */
        sessionFile?: string;
        /** Cached entries from ctx.sessionManager.getEntries() (for fork-bloat check) */
        entries?: any[];
    };
    /**
     * Optional override for the project root directory used when searching for
     * project-level templates (.pi/orca/agents). Defaults to process.cwd().
     */
    projectDir?: string;
    /**
     * Optional override for the user root directory used when searching for
     * user-level templates (.pi/agent/orca/agents). Defaults to $HOME.
     */
    userDir?: string;
    /** Heartbeat interval in milliseconds. */
    heartbeatIntervalMs?: number;
    /** Fork-bloat warning threshold in bytes; 0 disables. */
    forkSizeWarnBytes?: number;
    /** Hook for surfacing warnings/notifications to the user. */
    notify?: (message: string, type?: "info" | "warning" | "error") => void;
    /** Absolute path to the parent's notify socket (for child push pings). */
    parentNotifySockPath?: string;
    /**
     * Parent's resolved template for inheritance. When omitted, the spawned agent
     * is treated as a root and inherits no fields.
     */
    parentTemplate?: ResolvedAgentTemplate;
    /** Parent's currently-active tool list (from pi.getActiveTools()) */
    parentTools?: string[];
    /** Optional cwd override for child processes. */
    cwd?: string;
    /** Optional Pi session directory override. */
    sessionDir?: string;
    /** Optional project slug for registry registration. */
    projectSlug?: string;
    /**
     * Deadline (seconds) for the RPC/tmux child boot watchdog (§4.1.1 step 11).
     * Defaults to 10. Set to 0 to disable the watchdog.
     */
    spawnBootDeadlineSeconds?: number;
    /**
     * Optional callback for tests/observers to capture the watchdog handle.
     * Production callers normally ignore this — the watchdog runs detached.
     */
    onChildBootWatchdog?: (agentId: string, handle: ChildBootWatchdog) => void;
    /**
     * When set, this spawn is a respawn from `/agents recover`. The spawner
     * reuses the supplied agentId + session file, skips `nextAgentId`, and
     * threads the directive into the per-mode spawners so they call
     * `SessionManager.open()` and skip re-appending `orca:agent-instance`.
     */
    respawn?: SpawnRespawnSpec;
    /**
     * Test-only injection for the git CLI. Production calls execFile("git", ...).
     */
    execGit?: GitExec;
    /**
     * Worktree cleanup safeguard override. Default false → uncommitted changes
     * block cleanup (W9). Driven by `agents.worktreeForceCleanupOnTerminal`.
     */
    worktreeForceCleanupOnTerminal?: boolean;
    /**
     * Per-spawn isolation override (spec §5.2 precedence ladder, slot 4 — tool
     * call — and slot 5 — `--isolation` slash flag). Replaces the resolved
     * template's `isolation` for this one spawn only. When omitted, the
     * template's `isolation` (after inheritance) is used.
     */
    isolation?: "sdk" | "process" | "tmux";
    /**
     * Per-spawn tmux target override (`--tmux-target pane|window`). Replaces
     * the resolved template's `tmux.target` for this spawn only. Ignored when
     * effective isolation is not tmux (validation rejects the flag earlier).
     */
    tmuxTarget?: "pane" | "window";
    /**
     * Per-spawn tmux split direction override (`--tmux-split horizontal|vertical`).
     * Replaces the resolved template's `tmux.split` for this spawn only.
     */
    tmuxSplit?: "horizontal" | "vertical";
    /**
     * Per-spawn lifecycle override (`--lifecycle one-shot|persistent`).
     * Replaces the resolved template's `lifecycle` for this spawn only.
     * Spec §5.2 / §5.13.
     */
    lifecycle?: AgentLifecycle;
}
export interface SpawnAgentResult {
    agentId: string;
    status: "running";
    isolation: "sdk" | "process" | "tmux";
    sessionPath: string;
    pid?: number;
    tmuxWindowId?: string;
    tmuxPaneId?: string;
    tmuxTarget?: "pane" | "window";
}
/**
 * Spawn a new agent from a template (fire-and-forget).
 * Spec: §4.1.1 — Mermaid flow TEMPLATE → RESOLVE → MODEL_CHECK → ISOLATION_ROUTE → INSTANCE → REGISTER
 *
 * @param params - Spawn parameters
 * @returns Spawn result with agentId, status, isolation, sessionPath
 * @throws Error on validation failure, template error, or spawn failure
 */
export declare function spawnAgent(params: SpawnAgentParams): Promise<SpawnAgentResult>;
//# sourceMappingURL=spawn.d.ts.map