import type { AgentDqlArtifactReference, CascadeAnswerResult, AgentResultPayload, CertifiedBlockInvocationInput, AgentSchemaTable, AnalysisDepth, AnalyticalCascadeTierV1, AnalyticalFreshnessObservationV1, AnalyticalFreshnessRequestV1, ConversationSnapshot, GroundingExpansionResult, KGNode, LocalContextPack, ReasoningEffort, ResolvedAnalyticalPlan, SemanticQueryCompiler, DomainContextEnvelope, ProviderDispatchEvent, ProviderPayloadRowShape, AgenticSqlExecutionCapabilityV1, ExploratoryExecutionFreezeV1, AnalyticalTaskDependencyBindingV1, NarrationIntegrityReceiptV1, ProviderFailureDiagnosticV1 } from '@duckcodeailabs/dql-agent';
import type { DQLManifest, ProviderDispatchPhaseV1, ProviderEgressPurpose, ProviderEgressReceiptV1 } from '@duckcodeailabs/dql-core';
export type ProviderId = 'anthropic' | 'claude-agent-sdk' | 'claude-code' | 'codex' | 'openai' | 'gemini' | 'ollama' | 'custom-openai';
export interface ChatTurn {
    role: 'user' | 'assistant';
    content: string;
}
export interface AgentConversationContext {
    activeSurface?: 'notebook' | 'block' | 'app' | 'research' | 'chat' | string;
    conversationStateVersion?: number;
    activeTurnId?: string;
    activeTopic?: string;
    conversationSummary?: string;
    /** Canonical v1 server envelope shared by routing, planning, and execution. */
    conversationEnvelope?: ConversationSnapshot;
    /** Server-built bounded snapshot: recent turns, semantic recall, working state, and topic relation. */
    serverSnapshot?: ConversationSnapshot;
    turns?: AgentConversationTurn[];
    sourceAnswerId?: string;
    sourceCertifiedBlock?: string;
    sourceQuestion?: string;
    sourceAnswerSummary?: string;
    followupKind?: 'generic' | 'drilldown' | 'contextual';
    requestedFilters?: string[];
    requestedDimensions?: string[];
    answerContract?: unknown;
    resultColumns?: string[];
    resultRowsSample?: Record<string, unknown>[];
    resultDimensionValues?: Record<string, string[]>;
    appliedFilters?: Record<string, unknown>;
    priorLimit?: number;
    priorMeasures?: string[];
    outputColumns?: string[];
    trustLabel?: string;
    reviewStatus?: string;
    certification?: string;
    route?: string;
    contextPackId?: string;
    draftBlockPath?: string;
    dqlArtifact?: AgentDqlArtifactReference;
    cascade?: CascadeAnswerResult;
    selectedEvidence?: unknown[];
    sourceSql?: string;
    /** Server-derived compound parent binding; HTTP ingress strips client copies. */
    analyticalTaskDependencyBinding?: AnalyticalTaskDependencyBindingV1;
    updatedAt?: string;
}
export interface AgentConversationTurn {
    id: string;
    question: string;
    answerSummary?: string;
    completedAt?: string;
    artifactKind?: string;
    sourceCertifiedBlock?: string;
    route?: string;
    trustLabel?: string;
    reviewStatus?: string;
    certification?: string;
    contextPackId?: string;
    dqlArtifact?: AgentDqlArtifactReference;
    cascade?: CascadeAnswerResult;
    narrationIntegrityReceipt?: NarrationIntegrityReceiptV1;
    requestedFilters?: string[];
    requestedDimensions?: string[];
    requestedMeasures?: string[];
    answerContract?: unknown;
    topN?: number;
    result?: {
        columns?: string[];
        rowsSample?: Record<string, unknown>[];
        dimensionValues?: Record<string, string[]>;
        measureColumns?: string[];
        rowCount?: number;
    };
    sourceSql?: string;
}
export interface BlockProposal {
    name: string;
    path?: string;
    domain: string;
    owner: string;
    description: string;
    sql: string;
    blockType?: 'custom' | 'semantic';
    dqlSource?: string;
    metrics?: string[];
    dimensions?: string[];
    filters?: Array<{
        dimension: string;
        operator: string;
        values: string[];
    }>;
    timeDimension?: {
        name: string;
        granularity: string;
    };
    tags?: string[];
    chartType?: string;
}
/**
 * Normalized event a provider streams back for each step of an agent run.
 * The UI renders these in order; the final `proposal` (if any) routes through
 * the governance gate before `/api/blocks/save-from-cell`.
 */
export type AgentTurn = {
    kind: 'thinking';
    text: string;
} | {
    kind: 'text';
    text: string;
} | {
    kind: 'tool_call';
    id: string;
    name: string;
    input: unknown;
} | {
    kind: 'tool_result';
    id: string;
    output: unknown;
    isError?: boolean;
} | {
    kind: 'proposal';
    proposal: BlockProposal;
    governance: {
        certified: boolean;
        errors: string[];
        warnings: string[];
    };
} | {
    kind: 'error';
    message: string;
    dispatchEvidence?: ProviderDispatchTerminalEvidence;
    /** Redacted classification captured at the provider boundary. */
    providerDiagnostic?: ProviderFailureDiagnosticV1;
} | {
    kind: 'done';
    stopReason?: string;
};
export interface ProviderDispatchTerminalEvidence {
    providerEgressReceipts: ProviderEgressReceiptV1[];
    providerRoundTrips: number;
    toolCalls: number;
    sqlExecutions: number;
    repairs: number;
    fallbackReason: string;
}
export interface ProviderDispatchEvidenceSink {
    observe(event: ProviderDispatchEvent, context: {
        purpose: ProviderEgressPurpose;
        dispatchPhase: ProviderDispatchPhaseV1;
        optIn: boolean;
        serializedResultShape?: ProviderPayloadRowShape;
        cumulativeResultRowCount?: number;
    }): Record<string, unknown>;
    snapshot(fallbackReason?: string): ProviderDispatchTerminalEvidence;
    /** Run-budget guard checked before every provider-visible tool branch. */
    mayStartToolCall?(): boolean;
}
export interface AgentRunRequest {
    provider: ProviderId;
    /** Server-owned run-scoped accounting shared by routing, planning and answer generation. */
    providerDispatchEvidenceSink?: ProviderDispatchEvidenceSink;
    messages: ChatTurn[];
    upstream?: {
        cellId?: string;
        sql?: string;
        preview?: unknown;
    };
    conversationContext?: AgentConversationContext;
    /**
     * Reasoning effort for this run (low/medium/high). Resolved upstream from the
     * engine's per-route effort clamped by the provider's Settings ceiling; the
     * SDK runners translate it into their native param and no-op when unsupported.
     */
    reasoningEffort?: ReasoningEffort;
    /** Context/prompt depth for governed Ask AI. Research routes pass deep. */
    analysisDepth?: AnalysisDepth;
    /**
     * Server-resolved workflow mode. This is deliberately distinct from
     * `analysisDepth`: choosing more thinking must not silently grant Research
     * tools, Research dispatch budget, or result-row consent semantics.
     */
    orchestrationMode?: 'ask' | 'research';
    /** Explicit per-run Research consent; absent/false for every ordinary Ask and repair. */
    researchResultRowsOptIn?: boolean;
    /** Explicit Research-only permission for bounded semantic-member selection. */
    allowProviderSemanticMemberSelection?: boolean;
    projectRoot: string;
    /**
     * The agent run this turn belongs to. Used to key the execution
     * authorization, so proofs cannot cross turns.
     */
    agentRunId?: string;
    /** Server-resolved domain and purpose scope; clients never supply imports. */
    domainContext?: DomainContextEnvelope;
    /** Immutable server-owned manifest used for the entire governed answer. */
    projectSnapshot?: {
        snapshotId: string;
        manifest: DQLManifest;
    };
    /** Final guard invoked before execution and answer publication. */
    assertProjectSnapshot?: (snapshotId: string) => void;
    executeCertifiedBlock?: (block: KGNode, invocation?: CertifiedBlockInvocationInput) => Promise<AgentResultPayload>;
    executeGeneratedSql?: (sql: string, artifact?: AgentDqlArtifactReference) => Promise<AgentResultPayload>;
    /**
     * Server-only freeze for a router-selected exploratory proposal. The client
     * never supplies this callback or the returned opaque capability.
     */
    prepareExploratorySqlExecution?: (sql: string, artifact?: AgentDqlArtifactReference) => Promise<{
        capability: AgenticSqlExecutionCapabilityV1;
        freeze: ExploratoryExecutionFreezeV1;
    }>;
    /** Server-only generated execution capability; never accepted from a client payload. */
    executeAgenticGeneratedSql?: (capability: AgenticSqlExecutionCapabilityV1, sql: string, artifact?: AgentDqlArtifactReference) => Promise<AgentResultPayload>;
    executeDqlArtifact?: (artifact: AgentDqlArtifactReference) => Promise<AgentResultPayload>;
    getSchemaContext?: (question: string, contextPack?: LocalContextPack) => Promise<AgentSchemaTable[]>;
    /**
     * Bounded, equality-predicated lookup of specific relations the model
     * referenced but retrieval never inspected. Used only after the cached
     * catalog misses, so a real table is not refused without ever asking the
     * warehouse whether it exists.
     */
    probeNamedRelations?: (relations: string[]) => Promise<GroundingExpansionResult | undefined>;
    /** Active warehouse dialect so Lane-2 semantic compiles emit dialect-correct SQL. */
    semanticDriver?: string;
    /** Logical->physical table mapping for the semantic compiler, when resolved. */
    semanticTableMapping?: Record<string, string>;
    /** Shared host compiler for native, local MetricFlow, or dbt Cloud semantic execution. */
    semanticQueryCompiler?: SemanticQueryCompiler;
    /**
     * Qualified IDs selected by the bounded meaning resolver. They are advisory
     * for relevance but identifier-bound; the answer loop still runs its own
     * deterministic contract/compiler/policy checks before execution.
     */
    preferredEvidenceIds?: string[];
    preferredExecutionId?: string;
    /** Router-owned immutable v2 plan. Provider adapters must pass it through unchanged. */
    resolvedAnalyticalPlan?: ResolvedAnalyticalPlan;
    /**
     * Router-owned pre-freeze cascade choice. The provider adapter forwards this
     * unchanged to the answer loop so an eligible exploratory plan cannot reopen
     * certified or semantic selection after meaning has been resolved.
     */
    selectedCascadeTier?: Exclude<AnalyticalCascadeTierV1, 'clarify_or_gap'>;
    /**
     * Immutable physical evidence selected by the router for a pre-freeze
     * exploratory tier. This is an execution authority, not a relevance hint:
     * provider prompts and SQL validation may use only this candidate closure.
     */
    exploratoryCandidateIds?: string[];
    /**
     * Candidate-ID-scoped physical prompt/execution pack for `exploratory_sql`.
     * The broad prepared pack remains host diagnostics and is never provider
     * authority once the router has selected this tier.
     */
    preparedExploratoryContextPack?: LocalContextPack;
    /** Server-observed identity for a generated proposal's execution target. */
    generatedProposalTargetFingerprint?: string;
    /** Server-captured instant used to bind relative periods deterministically. */
    analyticalReferenceInstant?: string;
    /** Route-locked, snapshot-bound freshness lookup prepared by the execution host. */
    resolveAnalyticalFreshness?: (request: AnalyticalFreshnessRequestV1) => Promise<AnalyticalFreshnessObservationV1>;
    /**
     * Request-scoped ranked evidence prepared before routing. Hosts pass this to
     * prevent the provider adapter from rebuilding and re-searching the same
     * metadata snapshot after the meaning/route decision has already been made.
     */
    preparedContextPack?: LocalContextPack;
}
export interface AgentRunner {
    run(req: AgentRunRequest, emit: (turn: AgentTurn) => void, signal: AbortSignal): Promise<void>;
}
/**
 * Public-facing name for the adapter contract a provider must implement.
 * `AgentRunner` is the internal call site; `LLMProvider` is what community
 * authors target when they add a new `providers/<name>.ts`. Keep in sync.
 */
export type LLMProvider = AgentRunner;
//# sourceMappingURL=types.d.ts.map