/**
 * Shared types for tmux-pilot.
 */
import type { EffectiveRoleDefinition, RoleDefinitionProvenance } from "./role-definition";
import type { SandboxAudit } from "./sandbox/types";
import type { StyleConfig } from "./widget-style";
import type { MergeResult } from "./worktree-merge";
export type { MergeResult };
/** Status of a managed subagent process. */
export type SubagentStatus = "pending" | "running" | "completed" | "failed" | "crashed" | "interrupted";
/** Opaque type for idempotency keys used to deduplicate spawn requests. */
export type IdempotencyKey = string;
/** In-memory record for a tracked subagent process. */
export interface SubagentRecord {
    /** Unique agent ID (UUID v4). */
    id: string;
    /** The coding harness used to spawn this agent. */
    harness?: string;
    /** Agent type / role name. */
    type: string;
    /** The original prompt given to the subagent. */
    prompt: string;
    /** Current lifecycle status. */
    status: SubagentStatus;
    /** Backend type used to host this agent (e.g. "tmux", "spawn"). */
    backendType: string;
    /** Recovery identifier for reconnecting to the backend session. Display-only — never parsed for live targeting. */
    recoveryId?: string;
    /**
     * Stable tmux window ID (`@N`) captured atomically at window creation.
     * The correct live-targeting primitive — never renumbers, never reused for
     * the life of the server. Absent on records persisted before this field
     * existed; such records fall back to name-based targeting.
     */
    windowId?: string;
    /**
     * Socket path of the per-parent tmux server this agent's window lives on
     * (ADR 0003). Absent on records persisted before socket isolation; such
     * records are addressed on the default tmux server, as before.
     */
    socketPath?: string;
    /** Process ID of the running agent (set when alive). */
    pid?: number;
    /** Path to the subagent's isolated config directory. */
    configDir: string;
    /**
     * Core-allocated owned per-agent runtime directory
     * (`<hostStorage>/tmp/subagents/<parent>/<agent>/runtime`) holding this
     * agent's lifecycle files (see the `subagent-runtime-storage` capability).
     * Persisted at spawn; ALSO the layout-version discriminator: absent ⇒ a
     * legacy record whose child was launched with ambient-`$TMPDIR` lifecycle
     * paths (resume/reconcile/teardown then use the historical layout).
     */
    runtimeDir?: string;
    /** Path to the session file being monitored (JSONL). */
    sessionFilePath?: string;
    /** Extracted result text, set on successful completion. */
    result?: string;
    /** Error message, set on failure or crash. */
    error?: string;
    /** Current restart epoch (0 = first attempt). */
    epoch: number;
    /** Unix timestamp (ms) when the agent was spawned. */
    startedAt: number;
    /** Unix timestamp (ms) when the agent reached a terminal state. */
    completedAt?: number;
    /** Per-agent override for max restarts (legacy field kept for persisted records). */
    maxRestarts?: number;
    /** Per-agent override for restart window in ms. */
    restartWindowMs?: number;
    /** C3/C1: Name of the tool the child is currently executing (from status file or JSONL). */
    currentTool?: string;
    /**
     * Live activity phase for the cast lane (tui-frames-polish D3), driven by
     * the pi status stream (`turn_start` → thinking, `tool_start` → tool,
     * `tool_end` → thinking, terminal → idle). Default `idle` when unset.
     * Harnesses without a live status stream never set this — the renderer
     * treats a bare `currentTool` as the `tool` phase.
     */
    activityPhase?: "idle" | "thinking" | "tool";
    /** C3: Current turn count extracted from JSONL session file. */
    turnCount?: number;
    /** C3: Last response text snippet extracted from JSONL session file. */
    responseText?: string;
    /** C1/C3: ISO-8601 timestamp of the most recent activity event. */
    lastActivity?: string;
    /** Path to the status file written by the child extension (C1). */
    statusFilePath?: string;
    /** Path to the hooks-audit JSONL file for cmd harness tool visibility. */
    hooksAuditPath?: string;
    /** Whether the agent was stopped by a guard (turn threshold/grace exceeded). */
    guardStopped?: boolean;
    /** Human-readable reason for interruption, set when guard stops the agent. */
    interruptedReason?: string;
    /** Result of worktree auto-merge attempt (set when agent used a worktree). */
    mergeResult?: MergeResult;
    /** Worktree context block injected into the agent's prompt (set when worktree is active). */
    worktreeContext?: string;
    /** Git worktree branch name (set when the agent runs in an isolated worktree). Used for teardown. */
    worktreeBranch?: string;
    /** Absolute path to the agent's git worktree (set when isolated). Used for teardown. */
    worktreePath?: string;
    /** Definition provenance captured at spawn; instruction content is never persisted. */
    roleDefinition?: RoleDefinitionProvenance;
    /**
     * Parent session id that spawned this agent (spawn-time metadata). The
     * widget renders running/pending records only when this matches the
     * current parent OR the agent is registry-live in the current session;
     * the startup reconciler uses it for the adopt policy. Absent on records
     * persisted before this field existed (legacy fallback: the
     * `pilot-<parent>` prefix in `recoveryId`).
     */
    parentSessionId?: string;
    /**
     * Resolved role style captured at spawn (global ⊕ role `style:` config —
     * presentation metadata, like `model`/`thinking`). Config edits never
     * restyle a live agent; legacy records without it render with the
     * resolved global style.
     */
    style?: StyleConfig;
    /** Resolved model id (spawn-time metadata; health-bar denominator lookup). */
    model?: string;
    /** Resolved thinking level (spawn-time metadata; thinking buff icon). */
    thinking?: string;
    /** Resolved guard maxTurns for this agent (0 = unlimited; mana bar). */
    maxTurns?: number;
    /** Resolved guard graceTurns (mana bar red zone / grace debuff). */
    graceTurns?: number;
    /** Resolved staleness timeout (staleness-suspected debuff gate; 0 = disabled). */
    stalenessTimeoutMs?: number;
    /** Latest context usage (tokens) from session-file analysis (health bar). */
    contextTokens?: number;
    /**
     * The model's REAL context window (tokens) when session analysis carries it
     * (codex). Preferred over the static per-model table as the health bar's
     * denominator; absent → table lookup as before.
     */
    contextWindow?: number;
    /**
     * Unix timestamp (ms) when the parent retrieved this agent via
     * `get_subagent_result`. Retrieval is the ACKNOWLEDGMENT: failed/crashed
     * agents persist in the widget until this is set (linger-until-retrieved,
     * design D5). Presentation state only — no lifecycle transition involved.
     */
    resultRetrievedAt?: number;
    /** Unix timestamp (ms) of the last steer/threshold nudge (steered debuff, short TTL). */
    lastSteeredAt?: number;
    /** Unix timestamp (ms) when the agent was resumed after interrupt (resumed debuff). */
    resumedAt?: number;
    /**
     * How many times the parent called `get_subagent_result` while this agent
     * was still pending/running (poll-discipline capability). Fed back in the
     * running-status message so the model has context that it already checked.
     * Presentation/behavioral metadata only — never drives a lifecycle
     * transition.
     */
    pollCount?: number;
    /**
     * Immutable spawn-time sandbox audit (subagent-os-sandbox D10). Present only
     * for sandbox-REQUESTED spawns that created a window/record: captures the
     * resolved requested policy (env NAMES only — never values), enforced vs
     * degraded status, provider id/version, enforced canonical paths, network
     * mode, AF_UNIX status, harness write-root consequence, owned short-temp
     * path, and a sanitized degradation reason. Write-once: a later config edit
     * or provider probe never rewrites it. Absent on disabled/legacy records.
     */
    sandbox?: SandboxAudit;
}
/** Parent conversation message captured for inherit_context. */
export interface ParentContextMessage {
    role: "user" | "assistant";
    content: string;
}
/** Settings for spawned subagents (extensions, env, etc.). */
export interface SubagentSettings {
    /** Extension paths to load via `-e` flag. */
    extensions?: string[];
    /** Whether to load the child-status-writer extension. */
    statusFileEnabled?: boolean;
    /** Additional environment variables for the spawned process. */
    env?: Record<string, string>;
    /**
     * Glob patterns for env vars to pass from parent to child.
     * Defaults cover common provider API keys (*_API_KEY), Pi-specific vars (PI_*),
     * and AWS credentials (AWS_*).
     */
    passEnv?: string[];
    /** Allow unknown keys for future agent-type definitions. */
    [key: string]: unknown;
}
/** Parameters accepted by the spawn function. */
export interface SpawnParams {
    agentType: string;
    prompt: string;
    description?: string;
    model?: string;
    provider?: string;
    thinking?: string;
    maxTurns?: number;
    inheritContext?: boolean;
    /** Pre-formatted parent context text extracted from the parent session. */
    parentContextText?: string;
    /** Structured parent conversation messages for buildParentContext. */
    parentContext?: ParentContextMessage[];
    /** Backend to use (spawn or tmux). Defaults from config. */
    backend?: string;
    /** Restart policy (permanent, transient, or temporary). */
    restartPolicy?: string;
    /** The coding harness to use for this subagent. Resolved from tmux-pilot.config.yaml. */
    harness?: string;
    /** Per-subagent settings overrides. */
    settings?: SubagentSettings;
    /**
     * Optional explicit branch name for git worktree isolation.
     *
     * - When set, the subagent runs in its own git worktree at
     *   `<repoRoot>/.worktrees/<branch>/` and the branch persists across
     *   subagent completions (so subsequent agents with the same branch
     *   name reuse the worktree).
     * - When omitted and `description` is set, a branch name is auto-generated
     *   from the description (sanitized) plus a 4-character agent-ID suffix.
     *   Auto-generated worktrees are removed on agent completion.
     * - When both are omitted, the subagent runs in the main working directory
     *   (no worktree isolation) — fully backward compatible.
     */
    worktreeBranch?: string;
    /** Whether worktree isolation is enabled for this spawn. Resolved from config. */
    newWorktree?: boolean;
    /** User-facing label for the worktree (display only, not the actual branch name). */
    worktreeUserLabel?: string;
    /** Whether persistent worktrees are enabled. When false, all worktrees are ephemeral. */
    enablePersistentWorktrees?: boolean;
    /**
     * Resolved config-dir selection (path + mode) for this spawn, resolved from
     * tmux-pilot.config.yaml via `resolveHarnessConfigDir`. `dir` undefined ⇒
     * no override (harness runs as today). See the `harness-config-dir` capability.
     */
    configDirSelection?: {
        dir?: string;
        mode: "layer" | "replace";
    };
    /**
     * Resolved role style (global ⊕ role `style:` config) captured onto the
     * tracker record at spawn. Resolved by the spawn tool from
     * tmux-pilot.config.yaml via `resolveStyleConfig`.
     */
    style?: StyleConfig;
    /** Immutable role instructions resolved before this new spawn. */
    roleDefinition?: EffectiveRoleDefinition;
}
/** Options passed to tmux manager commands. */
export interface TmuxOptions {
    /** Timeout in milliseconds for tmux CLI calls. Default: 5000. */
    timeout?: number;
}
//# sourceMappingURL=types.d.ts.map