import type { SpanHandle, SpanAttributes } from '../../types/observability.js';
/**
 * Starts a root span for a tool call.
 * Attributes include toolName, inputSize, and any extra attrs provided.
 *
 * Usage:
 *   const span = startToolSpan('create_spec', { projectId: 'abc' });
 *   // ... do work ...
 *   span.end('ok');
 */
export declare function startToolSpan(toolName: string, extraAttributes?: SpanAttributes): SpanHandle;
/**
 * Starts a span representing a spec lifecycle event (e.g. status transition).
 * Intended to be used as a child of a per-spec root trace.
 *
 * @param specId  The spec identifier, e.g. "SPEC-042"
 * @param event   A lifecycle event name, e.g. "draft_to_approved"
 * @param parent  Parent span handle (the per-spec root span). May be null.
 * @param extraAttributes  Additional attributes.
 */
export declare function startSpecLifecycleSpan(specId: string, event: string, parent: SpanHandle | null, extraAttributes?: SpanAttributes): SpanHandle;
/**
 * Runs `fn` inside a tool span, automatically recording duration and status.
 * Returns the result of `fn`.
 * If `fn` throws, records the error on the span, ends it with 'error', then re-throws.
 */
export declare function withToolSpan<T>(toolName: string, fn: (span: SpanHandle) => Promise<T> | T, extraAttributes?: SpanAttributes): Promise<T>;
//# sourceMappingURL=span-helpers.d.ts.map