/**
 * Per-request ambient context for Photon tool execution.
 *
 * Uses Node's AsyncLocalStorage to make trace/caller context available
 * anywhere in the async call tree without parameter threading. Populated
 * by PhotonLoader.executeTool; consumed by the structured Logger, metrics
 * recorders, and any user code via getRequestContext().
 */
import type { CallerInfo } from '@portel/photon-core';
export interface RequestContext {
    photon: string;
    tool: string;
    /** W3C 32-hex trace ID when the execution is async or correlated. */
    traceId?: string;
    /** Inbound W3C traceparent (`00-{traceId}-{spanId}-{flags}`) when present. */
    parentTraceparent?: string;
    /** Authenticated caller when available. */
    caller?: CallerInfo;
    /** Normalized transport/client/app-session details for the current invocation. */
    request?: PhotonExecutionRequestContext;
    /**
     * Originating CLI invocation directory, propagated end-to-end across
     * worker thread and cross-photon-call boundaries. Lets photons resolve
     * defaults relative to where the user ran the command, not the daemon's
     * cwd. `process.cwd()` inside a worker is the daemon process's cwd, which
     * is rarely what the photon author wants. Photons read this back via
     * `this.callerCwd`.
     */
    cwd?: string;
    /**
     * Resolved PHOTON_DIR for the currently loading/executing photon.
     * In the single in-process daemon, several PHOTON_DIRs can execute
     * concurrently, so this must be async-local rather than process-global.
     */
    photonDir?: string;
    /** Wall-clock start of the tool call. */
    startedAt: number;
}
export interface PhotonExecutionClientContext {
    protocolVersion: string;
    clientName?: string;
    clientVersion?: string;
    mode: 'legacy-sessionful' | 'stateless' | 'unknown';
    capabilities?: Record<string, unknown>;
    quirks?: Record<string, unknown>;
}
export interface PhotonExecutionRequestContext {
    requestId?: string | number;
    transport: string;
    protocolVersion: string;
    client: PhotonExecutionClientContext;
    traceparent?: string;
    legacyTransportSessionId?: string;
    appSessionId?: string;
    appSessionSource?: string;
    scopeDir?: string;
}
export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
export declare function getRequestContext(): RequestContext | undefined;
export declare function runWithPhotonDir<T>(photonDir: string, fn: () => T): T;
//# sourceMappingURL=context.d.ts.map