import type { PromptCompressionLevel } from "./types.js";
/**
 * handoff.ts — Structured handoff protocol for chain-of-agents.
 *
 * Enables machine-parseable handoffs between chained agents without context
 * leakage. Inspired by Claude Code and Droid Factory handoff patterns.
 *
 * ## Handoff v2 (typed artifacts)
 *
 * The `artifacts` field is a discriminated union on `type`:
 *
 *   - `"file"`   — path on disk (required `path`; optional `mimeType`, `title`)
 *   - `"branch"` — git branch (required `branch`; optional `base`, `commits`, `title`)
 *   - `"url"`    — web URL (required `url`; optional `title`, `description`)
 *   - `"note"`   — free-form text (required `title` + `value`; optional `mimeType`)
 *
 * Legacy loose artifacts (`{type: "<unknown>", path, title, value, mimeType}`)
 * are coerced best-effort into a `note` to keep older agents working.
 */
/** Structured handoff produced by a sub-agent at the end of its response. */
export interface AgentHandoff {
    type: "handoff";
    status: "success" | "partial" | "failed";
    summary: string;
    findings: string[];
    nextSteps?: string[];
    confidence?: number;
    evidence?: string[];
    files?: string[];
    /** v2 typed artifacts — see {@link HandoffArtifactV2} for the discriminated union. */
    artifacts?: HandoffArtifactV2[];
}
/** A reference to a file on disk. */
export interface HandoffFileArtifact {
    type: "file";
    /** Absolute or repo-relative path to the file. */
    path: string;
    /** MIME type override (e.g., "text/typescript"). Inferred from extension when omitted. */
    mimeType?: string;
    /** Short label (e.g., "Fixed rate limiter"). */
    title?: string;
}
/** A reference to a git branch. */
export interface HandoffBranchArtifact {
    type: "branch";
    /** The branch name. */
    branch: string;
    /** The base branch this was forked from. */
    base?: string;
    /** Commit SHAs included in the branch. */
    commits?: string[];
    /** Short label. */
    title?: string;
}
/** A reference to a URL. */
export interface HandoffUrlArtifact {
    type: "url";
    /** The URL. */
    url: string;
    /** Short label. */
    title?: string;
    /** One-line description. */
    description?: string;
}
/** A free-form note or text artifact. */
export interface HandoffNoteArtifact {
    type: "note";
    /** Short label. */
    title: string;
    /** The note text. */
    value: string;
    /** MIME type override. */
    mimeType?: string;
}
/** v2 typed handoff artifact — discriminated union on `type`. */
export type HandoffArtifactV2 = HandoffFileArtifact | HandoffBranchArtifact | HandoffUrlArtifact | HandoffNoteArtifact;
/** All known v2 artifact types. */
export declare const HANDOFF_ARTIFACT_TYPES: readonly ["file", "branch", "url", "note"];
export type HandoffArtifactType = typeof HANDOFF_ARTIFACT_TYPES[number];
/**
 * Loose handoff artifact — the pre-v2 shape that older agents may still emit.
 * Kept as a structural alias so existing call sites and external consumers
 * continue to typecheck; {@link parseHandoff} coerces these into v2 shapes.
 */
export interface HandoffArtifact {
    type: string;
    path?: string;
    title?: string;
    value?: string;
    mimeType?: string;
    branch?: string;
    base?: string;
    commits?: string[];
    url?: string;
    description?: string;
}
/**
 * Parse a structured handoff from agent output text.
 *
 * Gracefully handles malformed, missing, or incomplete JSON. Never throws —
 * always returns null with a logger warning on parse failures.
 *
 * CVE-008 FIX: Added size and depth limits for JSON parsing.
 *
 * @returns A valid AgentHandoff, or null if no handoff could be parsed.
 */
export declare function parseHandoff(text: string): AgentHandoff | null;
/**
 * Build a handoff template for injection into an agent's system prompt.
 *
 * This tells the agent to produce a structured JSON handoff at the very end
 * of its response, enabling the parent to machine-parse the result for
 * chain-of-agents workflows.
 */
export declare function buildHandoffPrompt(level?: PromptCompressionLevel): string;
/**
 * Render a structured handoff back into readable text for the parent agent.
 *
 * Converts the machine-parseable handoff into a human-readable format that
 * preserves all fields, suitable for display or forwarding to the parent.
 */
export declare function renderHandoffForParent(handoff: AgentHandoff): string;