/**
 * Agent lifecycle span helpers.
 *
 * Tracks the full agent state machine:
 * AGENT_SPAWNING → AGENT_RUNNING → AGENT_AWAITING_MESSAGE → AGENT_AWAITING_TOOL
 * → AGENT_FINALIZING
 * Terminal states: AGENT_COMPLETED | AGENT_FAILED | AGENT_CANCELLED
 *
 * Agent spans are root spans (new trace per agent) or child of a turn span
 * when the agent was spawned within an interactive turn.
 */
import type { Span, SpanAttributes } from '../types.js';
import type { RuntimeTracer } from '../tracer.js';
/** Context supplied when starting an agent lifecycle span. */
export interface AgentSpanContext {
    /** Agent ID (unique per spawn). */
    readonly agentId: string;
    /** Task ID this agent is executing (if any). */
    readonly taskId?: string | undefined;
    /** Human-readable description of the agent task. */
    readonly task: string;
    /** Trace ID for cross-span correlation. */
    readonly traceId: string;
    /**
     * Optional parent span ID for nesting under a turn span.
     * When provided, this agent span becomes a child of the parent.
     */
    readonly parentSpanId?: string | undefined;
}
/** Phase transitions recordable on an agent lifecycle span. */
export type AgentPhase = 'running' | 'awaiting_message' | 'awaiting_tool' | 'finalizing';
/** Result context supplied when ending an agent lifecycle span. */
export interface AgentSpanEndContext {
    /** Final outcome of the agent. */
    readonly outcome: 'completed' | 'failed' | 'cancelled';
    /** Duration of the agent run in milliseconds. */
    readonly durationMs: number;
    /** Error description when outcome is 'failed'. */
    readonly error?: string | undefined;
    /** Cancel reason when outcome is 'cancelled'. */
    readonly reason?: string | undefined;
}
/**
 * Start an agent lifecycle span.
 *
 * @param tracer - RuntimeTracer instance.
 * @param ctx - Context from AGENT_SPAWNING event.
 */
export declare function startAgentSpan(tracer: RuntimeTracer, ctx: AgentSpanContext): Span;
/**
 * Record an agent phase transition event.
 *
 * @param span - The active agent lifecycle span.
 * @param phase - The phase reached.
 * @param attrs - Optional additional attributes.
 */
export declare function recordAgentPhase(span: Span, phase: AgentPhase, attrs?: SpanAttributes): void;
/**
 * End an agent lifecycle span.
 *
 * @param span - The span returned by `startAgentSpan`.
 * @param ctx - Agent lifecycle end context.
 */
export declare function endAgentSpan(span: Span, ctx: AgentSpanEndContext): void;
//# sourceMappingURL=agent.d.ts.map