@warble/codex-local 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,981 @@
+declare class CodexDispatchError extends Error {
+    constructor(message: string);
+}
+
+/** The deliberately small host-facing contract for provider-owned model discovery. */
+declare const MODEL_CATALOG_VERSION: 1;
+interface ModelCatalogModel {
+    model: string;
+    displayName: string;
+    description?: string;
+    isDefault?: boolean;
+    reasoningEfforts?: Array<{
+        value: string;
+        displayName: string;
+        description?: string;
+    }>;
+}
+type ModelCatalogUnavailableCode = "not_authenticated" | "runtime_unavailable" | "timeout" | "protocol_error";
+type ModelCatalogResult = {
+    version: typeof MODEL_CATALOG_VERSION;
+    status: "ready";
+    provider: "codex";
+    models: ModelCatalogModel[];
+} | {
+    version: typeof MODEL_CATALOG_VERSION;
+    status: "unavailable";
+    provider: "codex";
+    code: ModelCatalogUnavailableCode;
+    retryable: boolean;
+};
+interface DiscoverCodexModelsOptions {
+    cwd?: string;
+    codexHome?: string;
+    codexBin?: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * List authenticated Codex models over app-server without creating a thread or a turn.
+ * Only explicitly mapped model-picker fields ever leave this module.
+ */
+declare function discoverCodexModels(options?: DiscoverCodexModelsOptions): Promise<ModelCatalogResult>;
+
+/**
+ * Host-verifiable contract for a bound-project enrichment run.
+ *
+ * This is deliberately a pure contract, not a Codex runtime implementation. The current local
+ * target has no human-approval callback for gated writes, so callers can draft and validate this
+ * envelope but must wall-hit before attempting to execute it. A host that later provides approval
+ * and sink-scoped tools can use the same deterministic policy without exposing raw material,
+ * credentials, provider session ids, or project-side state files.
+ */
+declare const ENRICHMENT_CONTRACT_VERSION: "1";
+declare const ENRICHMENT_SINKS: readonly ["mdl_model_description", "mdl_column_description", "knowledge_rule", "knowledge_sql", "cube", "view", "relationship", "mdl_metric", "calculated_column"];
+type EnrichmentSink = (typeof ENRICHMENT_SINKS)[number];
+type EnrichmentMode = "grill" | "autopilot";
+type EnrichmentConfidence = "high" | "medium" | "low";
+type EnrichmentStatus = "completed" | "paused_for_decision" | "rejected" | "failed";
+type EnrichmentDecisionAction = "accept" | "edit" | "skip";
+type EnrichmentOperationRisk = "low_risk" | "high_impact" | "raw_current_conflict" | "ambiguous_sink";
+interface EnrichmentEvidence {
+    /** Opaque reference, never a raw excerpt or credential-bearing path. */
+    id: string;
+    kind: "structural" | "raw_claim" | "inference" | "probe";
+    confidence: EnrichmentConfidence;
+    /** A non-sensitive locator/digest supplied by the executor, never source content. */
+    locatorDigest: string;
+}
+interface EnrichmentChange {
+    operationId: string;
+    sink: EnrichmentSink;
+    /** Relative path inside the selected sink, never an absolute/workspace path. */
+    path: string;
+    /** Enrichment is append-only; replacements are never representable. */
+    operation: "append";
+    /** Opaque canonical digest of executor-held content; raw payload stays out of this contract. */
+    contentDigest: string;
+    evidenceIds: string[];
+}
+interface EnrichmentProposal {
+    id: string;
+    hash: string;
+    projectRevision: string;
+    mode: EnrichmentMode;
+    changes: EnrichmentChange[];
+    evidence: EnrichmentEvidence[];
+    rawCurrentConflict: boolean;
+    ambiguousSink: boolean;
+}
+interface EnrichmentDecision {
+    proposalId: string;
+    proposalHash: string;
+    projectRevision: string;
+    operationId: string;
+    action: EnrichmentDecisionAction;
+}
+/** A pending request is an identity-bearing terminal state, not prose asking for approval. */
+interface EnrichmentDecisionRequest {
+    id: string;
+    proposalId: string;
+    proposalHash: string;
+    projectRevision: string;
+    operationId: string;
+    action: "pending";
+}
+/**
+ * A host-issued approval record. It is supplied out-of-band to validation; no model output,
+ * terminal decision, secret, or model-generated signature can stand in for this record.
+ */
+interface HostApprovalAttestation {
+    id: string;
+    projectRevision: string;
+    proposalHash: string;
+    operationId: string;
+    sink: EnrichmentSink;
+    risk: Exclude<EnrichmentOperationRisk, "low_risk">;
+}
+/** The host's canonical operation classification, never copied from a terminal envelope. */
+interface TrustedEnrichmentOperation {
+    operationId: string;
+    sink: EnrichmentSink;
+    risk: EnrichmentOperationRisk;
+}
+/**
+ * Snapshot of operations completed before the terminal being checked. A host may back this with a
+ * durable ledger or reconstruct it from an authoritative audit stream after provider-session loss.
+ */
+interface CompletedOperationLedger {
+    wasCompleted(operationId: string): boolean;
+}
+/** Trusted, host-owned inputs required to validate a terminal envelope. */
+interface EnrichmentHostContext {
+    projectRevision: string;
+    proposalId: string;
+    proposalHash: string;
+    operations: readonly TrustedEnrichmentOperation[];
+    approvals: readonly HostApprovalAttestation[];
+    completedOperations: CompletedOperationLedger;
+}
+interface ValidationProof {
+    operationId: string;
+    status: "passed" | "failed" | "not_required";
+    verifier: "context_validate" | "cube_sql_only";
+    proofDigest: string;
+}
+interface BuildProof {
+    status: "passed" | "failed" | "not_run";
+    verifier: "context_build";
+    proofDigest: string | null;
+}
+interface EnrichmentAudit {
+    appliedOperationIds: string[];
+    skippedOperationIds: string[];
+    revertedOperationIds: string[];
+    /** Resume state is host-owned; no gaps/state artifact is ever written in the project. */
+    resume: "provider_session" | "reconstructed" | "not_resumed";
+}
+interface EnrichmentTerminal {
+    contractVersion: typeof ENRICHMENT_CONTRACT_VERSION;
+    mode: EnrichmentMode;
+    status: EnrichmentStatus;
+    projectRevision: string;
+    proposal: Pick<EnrichmentProposal, "id" | "hash">;
+    decision: EnrichmentDecision | EnrichmentDecisionRequest | null;
+    evidence: EnrichmentEvidence[];
+    changes: EnrichmentChange[];
+    validations: ValidationProof[];
+    build: BuildProof;
+    audit: EnrichmentAudit;
+}
+type EnrichmentDisposition = {
+    kind: "ready_to_apply";
+    operationIds: string[];
+    skippedOperationIds: string[];
+} | {
+    kind: "requires_decision";
+    operationIds: string[];
+    reasons: string[];
+    skippedOperationIds: string[];
+} | {
+    kind: "requires_redraft";
+    operationId: string;
+} | {
+    kind: "stale_approval";
+    reason: "project_revision" | "proposal_hash" | "proposal_id";
+} | {
+    kind: "invalid";
+    reason: string;
+};
+interface EnrichmentPolicyInput {
+    proposal: EnrichmentProposal;
+    host: EnrichmentHostContext;
+    /** Successful build proof captured before the enrichment run starts. */
+    currentBuild: BuildProof;
+    decision?: EnrichmentDecision;
+}
+/**
+ * Pure policy for one proposal. It makes the native grill/autopilot split inspectable by a host:
+ * completed operation ids are removed before dispatch, making a reconstructed resume replay-safe.
+ */
+declare function decideEnrichment(input: EnrichmentPolicyInput): EnrichmentDisposition;
+/**
+ * Validates a terminal against trusted host context. Terminal decisions are display/audit data only:
+ * they are never authority to apply a high-risk operation or to suppress a prior-completion ledger.
+ */
+declare function assertEnrichmentTerminal(terminal: EnrichmentTerminal, host: EnrichmentHostContext): void;
+
+declare const TARGET: "codex:local";
+declare const SUPPORTED_IR_VERSION: "0.6";
+interface LlmCall {
+    name: string;
+    tier: string;
+    prompt: string;
+    consumes: string[];
+    produces: string | null;
+    conditional: boolean;
+    when: unknown;
+}
+interface Guardrail {
+    name: string;
+    locked: boolean;
+    scope?: string;
+    threshold?: number;
+}
+interface ComponentNode {
+    id: string;
+    verb: string;
+    type: string;
+    realization_kind: string;
+    llm_calls: LlmCall[];
+    required_capabilities: string[];
+    guardrails: Guardrail[];
+    trigger: {
+        kind: string;
+    };
+    effect: {
+        outcome: {
+            kind: string;
+        };
+        render_blocks: unknown[];
+    };
+    context_binding: {
+        binding_mode: string;
+        project: string;
+    };
+}
+interface WarbleIr {
+    warble_ir_version: string;
+    profile: string;
+    components: ComponentNode[];
+}
+declare function parseIr(raw: string): WarbleIr;
+
+/**
+ * The only `when` dialect this transport (and the Ask path) evaluates: a step runs only when an
+ * earlier step in the same component failed. `target` names that earlier step.
+ */
+interface OnFailureGuard {
+    guard: "on_failure";
+    target: string;
+}
+
+declare const SETUP_DOMAIN_CAPABILITIES: readonly ["source_connect", "context_build"];
+type SetupDomainCapability = (typeof SETUP_DOMAIN_CAPABILITIES)[number];
+declare const ENRICH_DOMAIN_CAPABILITIES: readonly ["semantic_introspection", "raw_material_read"];
+type EnrichDomainCapability = (typeof ENRICH_DOMAIN_CAPABILITIES)[number];
+
+interface McpServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    toolsByCapability: Record<SetupDomainCapability, string[]>;
+}
+interface CapabilityResolution {
+    capability: string;
+    outcome: "native" | "realize-via";
+    via: string | null;
+}
+interface PreparedSetupStep {
+    name: string;
+    tier: string;
+    model: string;
+    prompt: string;
+    consumes: string[];
+    produces: string;
+    when: OnFailureGuard | null;
+}
+interface PreparedSetupComponent {
+    target: typeof TARGET;
+    profile: string;
+    node: ComponentNode;
+    componentId: string;
+    domainCapability: SetupDomainCapability;
+    steps: PreparedSetupStep[];
+    capabilities: CapabilityResolution[];
+    enabledTools: string[];
+    mcp: McpServerConfig;
+}
+interface PrepareInput {
+    ir: string | WarbleIr;
+    component: string;
+    /**
+     * A single string binds every step in the component to that one model (the shape every
+     * existing single-step fixture already uses, and still all that's required when a component
+     * declares only one tier). A per-tier map is required once a component declares steps at more
+     * than one tier — see `resolveStepModel`.
+     */
+    model: string | Record<string, string>;
+    mcp: McpServerConfig;
+}
+declare function matchesSetupContractShape(node: ComponentNode): boolean;
+/**
+ * The specific reason a component's IR shape does not match the Setup contract, or null when it
+ * does match. This mirrors `matchesSetupContractShape`'s try/catch but preserves the validator's
+ * own wall-hit message instead of collapsing it to a boolean, so a caller classifying across all
+ * three families can surface precisely which structural expectation failed.
+ */
+declare function setupContractMismatchReason(node: ComponentNode): string | null;
+declare function prepareSetup(input: PrepareInput): PreparedSetupComponent;
+declare function prepareAllSetup(raw: string, config: Omit<PrepareInput, "ir" | "component">): PreparedSetupComponent[];
+
+/**
+ * The public CLI is intentionally profile-agnostic. These are implementation contracts selected
+ * from a parsed component's declared IR shape, never from a command spelling, profile name, or
+ * component identity.
+ */
+type DispatchContract = "setup" | "ask" | "enrich";
+/**
+ * Select the native execution contract only when exactly one complete structural contract matches.
+ * This check runs before configuration, preparation, or a runtime launch.
+ */
+declare function classifyDispatchContract(ir: WarbleIr, component: string): DispatchContract;
+/**
+ * Setup is the sole whole-profile manifest/describe contract. Other shapes are scoped dispatches
+ * and therefore require an explicit --component selection.
+ */
+declare function supportsSetupAggregate(ir: WarbleIr): boolean;
+
+interface AskMcpServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    toolsByStep: Record<string, string[]>;
+}
+interface AskTierModels {
+    orchestrator: string;
+    cheap: string;
+    strong: string;
+}
+interface AskWhenGuard {
+    guard: "on_failure";
+    target: string;
+}
+interface PreparedAskStep {
+    name: string;
+    role: string;
+    tier: "cheap" | "strong";
+    model: string;
+    prompt: string;
+    consumes: string[];
+    produces: string;
+    conditional: boolean;
+    when: AskWhenGuard | null;
+    enabledTools: string[];
+    requireSuccessfulTool: boolean;
+}
+type AnalyticalExecutionKind = "answer_query" | "generate_dashboard";
+interface PreparedAskComponent {
+    target: typeof TARGET;
+    profile: string;
+    node: ComponentNode;
+    componentId: string;
+    steps: PreparedAskStep[];
+    capabilities: CapabilityResolution[];
+    mcp: AskMcpServerConfig;
+    models: AskTierModels;
+    executionKind: AnalyticalExecutionKind;
+    maxRepairAttempts: number;
+}
+interface PrepareAskInput {
+    ir: string | WarbleIr;
+    component: string;
+    models: AskTierModels;
+    mcp: AskMcpServerConfig;
+}
+declare function matchesAskContractShape(node: ComponentNode): boolean;
+/**
+ * The specific reason a component's IR shape does not match either Ask contract (answer_query or
+ * generate_dashboard), or null when it matches one of them. Mirrors `matchesAskContractShape`'s
+ * try/catch but preserves the validator's own wall-hit message so a caller classifying across all
+ * three families can surface precisely which structural expectation failed.
+ */
+declare function askContractMismatchReason(node: ComponentNode): string | null;
+declare function prepareAsk(input: PrepareAskInput): PreparedAskComponent;
+
+interface EnrichMcpServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    toolsByCapability: Record<EnrichDomainCapability, string[]>;
+}
+interface PreparedEnrichStep {
+    name: string;
+    tier: string;
+    model: string;
+    prompt: string;
+    consumes: string[];
+    produces: string;
+    when: OnFailureGuard | null;
+}
+interface PreparedEnrichComponent {
+    target: typeof TARGET;
+    profile: string;
+    node: ComponentNode;
+    componentId: string;
+    domainCapabilities: EnrichDomainCapability[];
+    steps: PreparedEnrichStep[];
+    capabilities: CapabilityResolution[];
+    enabledTools: string[];
+    mcp: EnrichMcpServerConfig;
+}
+interface PrepareEnrichInput {
+    ir: string | WarbleIr;
+    component: string;
+    /**
+     * A single string binds every step in the component to that one model. A per-tier map is
+     * required once a component declares steps at more than one tier — see `resolveStepModel`.
+     */
+    model: string | Record<string, string>;
+    mcp: EnrichMcpServerConfig;
+}
+declare function matchesEnrichContractShape(node: ComponentNode): boolean;
+/**
+ * The specific reason a component's IR shape does not match the Enrich contract, or null when it
+ * does match. Mirrors `matchesEnrichContractShape`'s try/catch but preserves the validator's own
+ * wall-hit message so a caller classifying across all three families can surface precisely which
+ * structural expectation failed.
+ */
+declare function enrichContractMismatchReason(node: ComponentNode): string | null;
+declare function prepareEnrich(input: PrepareEnrichInput): PreparedEnrichComponent;
+
+interface AskAgentConfigFile {
+    role: string;
+    path: string;
+    model: string;
+    tools: string[];
+}
+interface AskAgentConfigBundle {
+    directory: string;
+    requestFile: string;
+    stepRequestFile: string;
+    agents: AskAgentConfigFile[];
+    parentConfig: Record<string, unknown>;
+    bindRequest: (request: string) => void;
+    bindStepRequest: (request: string) => void;
+    cleanup: () => void;
+}
+declare function renderAskAgentToml(prepared: PreparedAskComponent, step: PreparedAskStep, requestFile: string, stepRequestFile: string): string;
+declare function createAskAgentConfigBundle(prepared: PreparedAskComponent): AskAgentConfigBundle;
+
+type WarbleCodexEvent = {
+    t: "step_start";
+    id: string;
+    name: string;
+} | {
+    t: "tool_call";
+    id: string;
+    name: string;
+} | {
+    t: "tool_result";
+    id: string;
+    ok: boolean;
+    error?: string;
+} | {
+    t: "answer";
+    text: string;
+} | {
+    t: "step_finish";
+    id: string;
+    ok: boolean;
+    detail?: string;
+};
+declare class CodexJsonlMapper {
+    private readonly stepId;
+    private readonly expectedMcpServer;
+    private started;
+    private finished;
+    private threadStarted;
+    private finalText;
+    private failureDetail;
+    private toolFailureDetail;
+    private readonly pendingTools;
+    private successfulToolCount;
+    private readonly enabledTools;
+    constructor(stepId: string, expectedMcpServer: string, enabledTools: readonly string[]);
+    nextLine(line: string): WarbleCodexEvent[];
+    result(): {
+        finalText: string;
+        threadStarted: boolean;
+        turnCompleted: boolean;
+    };
+    private onItem;
+    private finish;
+}
+
+declare const SESSION_REFERENCE_VERSION: "0.1";
+interface CodexSessionReference {
+    version: typeof SESSION_REFERENCE_VERSION;
+    target: "codex:local";
+    threadId: string;
+    forkedFromThreadId: string | null;
+}
+type SessionTurnStatus = "in_progress" | "completed" | "interrupted" | "failed";
+interface CodexTurnReference {
+    threadId: string;
+    turnId: string;
+    status: SessionTurnStatus;
+}
+interface CodexArtifactReference {
+    version: typeof SESSION_REFERENCE_VERSION;
+    kind: "mcp_tool_result";
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    server: string;
+    tool: string;
+    ok: boolean;
+}
+type CodexHistoryItem = {
+    type: "user" | "assistant";
+    itemId: string;
+} | {
+    type: "artifact";
+    reference: CodexArtifactReference;
+};
+interface CodexHistoryTurn {
+    id: string;
+    status: SessionTurnStatus;
+    items: CodexHistoryItem[];
+}
+interface CodexSessionHistory {
+    session: CodexSessionReference;
+    turns: CodexHistoryTurn[];
+}
+type CodexSessionEvent = {
+    t: "session_started" | "session_resumed" | "session_forked";
+    session: CodexSessionReference;
+} | {
+    t: "session_recoverable";
+    threadId: string | null;
+    reason: "transport_disconnect" | "app_server_crash" | "turn_timeout";
+} | {
+    t: "session_failed";
+    threadId: string | null;
+    reason: "protocol_violation";
+} | {
+    t: "turn_started";
+    turn: CodexTurnReference;
+} | {
+    t: "turn_completed";
+    turn: CodexTurnReference;
+} | {
+    t: "artifact";
+    reference: CodexArtifactReference;
+} | ({
+    threadId: string;
+    turnId: string;
+} & WarbleCodexEvent);
+interface SessionIsolationOptions {
+    codexHome: string;
+    cwd: string;
+    externalAuthentication: "provisioned";
+    codexBin?: string;
+    codexArgsPrefix?: string[];
+    timeoutMs?: number;
+    terminationGraceMs?: number;
+    env?: NodeJS.ProcessEnv;
+    onEvent?: (event: CodexSessionEvent) => void;
+}
+
+interface CodexAskStepResult {
+    step: string;
+    agentRole: string;
+    agentThreadId: string;
+    model: string;
+    produced: string;
+    ok: boolean;
+    value: unknown;
+    artifacts: CodexAskArtifactReference[];
+}
+interface CodexAskArtifactReference {
+    version: typeof SESSION_REFERENCE_VERSION;
+    kind: "mcp_tool_result";
+    parentThreadId: string;
+    parentTurnId: string;
+    agentThreadId: string;
+    step: string;
+    agentRole: string;
+    itemId: string;
+    server: string;
+    tool: string;
+    ok: boolean;
+}
+interface CodexRenderArtifactReference {
+    version: typeof SESSION_REFERENCE_VERSION;
+    kind: "render_envelope";
+    parentThreadId: string;
+    parentTurnId: string;
+    agentThreadId: string;
+    step: string;
+    agentRole: string;
+    verified: boolean;
+    blockTypes: string[];
+}
+type CodexAskEvent = {
+    t: "session_started" | "session_resumed";
+    session: CodexSessionReference;
+} | {
+    t: "turn_started" | "turn_completed";
+    turn: CodexTurnReference;
+} | {
+    t: "agent_started";
+    parentThreadId: string;
+    parentTurnId: string;
+    step: string;
+    agentRole: string;
+    agentThreadId: string;
+    model: string;
+} | {
+    t: "step_finished";
+    parentThreadId: string;
+    parentTurnId: string;
+    step: string;
+    agentRole: string;
+    agentThreadId: string;
+    ok: boolean;
+} | {
+    t: "artifact";
+    reference: CodexAskArtifactReference;
+} | {
+    t: "render_artifact";
+    reference: CodexRenderArtifactReference;
+} | {
+    t: "render_degraded";
+    parentThreadId: string;
+    parentTurnId: string;
+    reason: "invalid_render_envelope";
+} | {
+    t: "session_recoverable";
+    threadId: string | null;
+    reason: "transport_disconnect" | "app_server_crash" | "turn_timeout" | "turn_cancelled";
+} | {
+    t: "session_failed";
+    threadId: string | null;
+    reason: "protocol_violation";
+};
+interface CodexAskRuntimeOptions extends SessionIsolationOptions {
+    turnTimeoutMs?: number;
+    onAskEvent?: (event: CodexAskEvent) => void;
+}
+interface CodexAskRunResult {
+    target: "codex:local";
+    component: string;
+    session: CodexSessionReference;
+    turn: CodexTurnReference;
+    finalText: string;
+    value: unknown;
+    steps: CodexAskStepResult[];
+    artifact: CodexRenderArtifactReference | null;
+    renderDegraded: boolean;
+}
+declare function buildAskDriverPrompt(prepared: PreparedAskComponent): string;
+declare class CodexAskRuntime {
+    private readonly prepared;
+    private readonly options;
+    private transport;
+    private bundle;
+    private session;
+    private active;
+    private startingTurn;
+    private pendingTurnNotifications;
+    private disconnected;
+    private constructor();
+    static connect(prepared: PreparedAskComponent, options: CodexAskRuntimeOptions): Promise<CodexAskRuntime>;
+    start(): Promise<CodexSessionReference>;
+    resume(reference: CodexSessionReference): Promise<CodexSessionReference>;
+    run(reference: CodexSessionReference, request: string, signal?: AbortSignal): Promise<CodexAskRunResult>;
+    restartAndResume(reference: CodexSessionReference): Promise<CodexSessionReference>;
+    close(): Promise<void>;
+    private onNotification;
+    private onItem;
+    private observeChildNotification;
+    private onCollabItem;
+    private completeWait;
+    private tryFinalizeTurn;
+    private synthesizeDirectCollaboration;
+    private validateChildren;
+    private stopTurn;
+    private onDisconnect;
+    private ensureConnected;
+    private emit;
+}
+
+interface JsonRecord {
+    [key: string]: unknown;
+}
+interface DashboardRenderEnvelope {
+    blocks: JsonRecord[];
+    summary?: string;
+    verified: boolean;
+}
+declare function validateDashboardRenderEnvelope(value: unknown, node: ComponentNode): DashboardRenderEnvelope;
+
+interface StepManifest {
+    name: string;
+    tier: string;
+    model: string;
+    consumes: string[];
+    produces: string | null;
+    agent_role?: string;
+    conditional?: boolean;
+    when?: {
+        guard: string;
+        target: string;
+    } | null;
+    tools?: string[];
+}
+interface AgentManifest {
+    id: string;
+    verb: string;
+    component_type: string;
+    realization_kind: string;
+    trigger: string;
+    outcome: string;
+    steps: StepManifest[];
+    capabilities: PreparedSetupComponent["capabilities"];
+    tools: Array<{
+        name: string;
+        source: string;
+        agents?: string[];
+    }>;
+    guardrails: Record<string, unknown>;
+    artifact_output?: {
+        kind: "render_envelope";
+        persistence: "consumer";
+        block_types: string[];
+    };
+}
+interface Manifest {
+    manifest_version: "0.1";
+    compat: {
+        min_ir_version: typeof SUPPORTED_IR_VERSION;
+        max_ir_version: typeof SUPPORTED_IR_VERSION;
+    };
+    profile: string;
+    target: typeof TARGET;
+    session: SessionManifest;
+    agents: AgentManifest[];
+}
+declare const SESSION_LIFECYCLE_OPERATIONS: readonly ["start", "resume", "read", "turn", "steer", "interrupt", "fork"];
+interface SessionManifest {
+    persistence: "codex_thread_history";
+    lifecycle_operations: Array<(typeof SESSION_LIFECYCLE_OPERATIONS)[number]>;
+    artifact_reference: "allowlisted_mcp_tool_result" | "allowlisted_mcp_tool_result_or_render_envelope";
+    isolation: "dedicated_persistent_codex_home";
+    authentication: "externally_provisioned";
+}
+interface TargetDescription {
+    target: typeof TARGET;
+    phase: "setup-only" | "setup-and-ask-parity" | "setup-ask-and-dashboard-parity" | "enrich-parity";
+    execution_modes: Array<"one_shot" | "persistent_session">;
+    session_persistence: SessionManifest["persistence"];
+    lifecycle_operations: SessionManifest["lifecycle_operations"];
+    supported_components: string[];
+    tiers: string[];
+    capabilities: string[];
+    tools: string[];
+    guardrails: string[];
+}
+declare function buildAskAgentManifest(prepared: PreparedAskComponent): AgentManifest;
+declare function buildAskManifest(prepared: PreparedAskComponent): Manifest;
+declare function describeAskTarget(prepared: PreparedAskComponent): TargetDescription;
+declare function buildAgentManifest(prepared: PreparedSetupComponent): AgentManifest;
+declare function buildManifest(prepared: readonly PreparedSetupComponent[]): Manifest;
+declare function describeTarget(prepared: readonly PreparedSetupComponent[]): TargetDescription;
+declare function buildEnrichAgentManifest(prepared: PreparedEnrichComponent): AgentManifest;
+declare function buildEnrichManifest(prepared: PreparedEnrichComponent): Manifest;
+declare function describeEnrichTarget(prepared: PreparedEnrichComponent): TargetDescription;
+
+type PreparedOneShotComponent = PreparedSetupComponent | PreparedEnrichComponent;
+/** Structurally matches both `PreparedSetupStep` and `PreparedEnrichStep` — the two engines stay
+ * separate types, but a single prepared step is enough to build this target's args/prompt for
+ * either one. */
+interface PreparedStepLike {
+    name: string;
+    model: string;
+    prompt: string;
+    consumes: string[];
+    produces: string;
+}
+interface BuildPromptOptions {
+    /** Setup's host consumes the produced slot as terminal text; Enrich may marshal structured JSON. */
+    producedValue?: "string" | "json";
+}
+declare function sanitizeCodexEnvironment(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+interface InvocationArgsOptions {
+    cwd: string;
+    codexArgsPrefix?: string[];
+}
+declare function buildCodexArgs(prepared: PreparedOneShotComponent, step: PreparedStepLike, options: InvocationArgsOptions): string[];
+/**
+ * `inputs` carries the marshalled values this step's `consumes` names resolve to from earlier
+ * steps' outputs in this same dispatch. When a step declares no `consumes` (every existing
+ * single-step fixture, and the first step of any multi-step component), no input section is added.
+ */
+declare function buildPrompt(prepared: PreparedOneShotComponent, step: PreparedStepLike, request: string, inputs?: Record<string, unknown>, options?: BuildPromptOptions): string;
+
+declare function validateSessionIsolation(options: SessionIsolationOptions): {
+    codexHome: string;
+    cwd: string;
+};
+declare function buildAppServerArgs(prepared: PreparedSetupComponent | PreparedEnrichComponent, options: SessionIsolationOptions): string[];
+/** Read-only app-server startup for model discovery. It deliberately has no thread/session config. */
+interface CatalogTransportOptions {
+    cwd: string;
+    codexHome?: string;
+    codexBin?: string;
+    codexArgsPrefix?: string[];
+    timeoutMs?: number;
+    terminationGraceMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+declare class CodexAppServerTransport {
+    private readonly timeoutMs;
+    private readonly terminationGraceMs;
+    private readonly onNotification;
+    private readonly onDisconnect;
+    private nextId;
+    private readonly pending;
+    private readonly lines;
+    private readonly child;
+    private closing;
+    private closed;
+    private killTimer;
+    private readonly closePromise;
+    private constructor();
+    static start(prepared: PreparedSetupComponent | PreparedEnrichComponent, options: SessionIsolationOptions, onNotification: (method: string, params: unknown) => void, onDisconnect: (error?: CodexDispatchError) => void): Promise<CodexAppServerTransport>;
+    static startWithArgs(args: string[], options: SessionIsolationOptions, onNotification: (method: string, params: unknown) => void, onDisconnect: (error?: CodexDispatchError) => void): Promise<CodexAppServerTransport>;
+    /**
+     * Start a narrowly read-only app-server transport for `model/list`. Unlike persistent sessions,
+     * catalog discovery may use the caller's normal logged-in Codex identity, but it never starts a
+     * thread or applies the session's MCP/tool isolation configuration.
+     */
+    static startCatalog(options: CatalogTransportOptions): Promise<CodexAppServerTransport>;
+    request(method: string, params?: unknown): Promise<unknown>;
+    notify(method: string, params?: unknown): void;
+    close(): Promise<void>;
+    private write;
+    private onLine;
+    private protocolFailure;
+    private rejectPending;
+    private signalTree;
+}
+
+declare class CodexSessionRuntime {
+    private readonly prepared;
+    private readonly options;
+    private transport;
+    private session;
+    private readonly activeTurns;
+    private readonly waiters;
+    private readonly stepNameByTurn;
+    private disconnected;
+    private constructor();
+    /**
+     * The model bound to this persistent thread for its whole lifetime. `thread/start` takes a
+     * single `model` with no per-turn override, so unlike Setup's one-shot-process-per-step
+     * transport, every step dispatched through one session must resolve to the same model — see
+     * `enrich_prepare.ts`'s single-tier-per-component requirement, which is what makes this true by
+     * construction rather than by convention.
+     */
+    private get model();
+    static connect(prepared: PreparedSetupComponent | PreparedEnrichComponent, options: SessionIsolationOptions): Promise<CodexSessionRuntime>;
+    start(): Promise<CodexSessionReference>;
+    resume(reference: CodexSessionReference): Promise<CodexSessionReference>;
+    read(reference: CodexSessionReference): Promise<CodexSessionHistory>;
+    /**
+     * `step`/`inputs` default to this component's first (and, for every existing single-step
+     * fixture, only) step with no marshalled inputs — so every pre-existing caller that never named
+     * a step keeps building the exact same prompt as before. A multi-step caller (the n-step Enrich
+     * executor) passes the step actually being dispatched this turn, plus that step's marshalled
+     * `consumes` values, and this records which step owns the resulting turn id so the
+     * `step_start`/`step_finish` events this turn emits are attributed correctly rather than always
+     * naming the component's first step.
+     */
+    turn(reference: CodexSessionReference, input: string, step?: PreparedStepLike, inputs?: Record<string, unknown>): Promise<CodexTurnReference>;
+    steer(reference: CodexSessionReference, turnId: string, input: string): Promise<CodexTurnReference>;
+    interrupt(reference: CodexSessionReference, turnId: string): Promise<void>;
+    fork(reference: CodexSessionReference, lastTurnId?: string): Promise<CodexSessionReference>;
+    waitForTurn(turn: CodexTurnReference, timeoutMs?: number): Promise<CodexTurnReference>;
+    restartAndResume(reference: CodexSessionReference): Promise<CodexSessionReference>;
+    close(): Promise<void>;
+    private onNotification;
+    private onItem;
+    private onTurnCompleted;
+    private projectHistoryTurn;
+    private ensureActiveTurn;
+    private requireCurrent;
+    private requireNotificationThread;
+    private requireNoActiveTurns;
+    private ensureConnected;
+    private onDisconnect;
+    private settleWaiters;
+    private removeWaiter;
+    private emit;
+}
+
+interface RunOptions {
+    cwd: string;
+    request: string;
+    codexBin?: string;
+    codexArgsPrefix?: string[];
+    timeoutMs?: number;
+    terminationGraceMs?: number;
+    signal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
+    onEvent?: (event: WarbleCodexEvent) => void;
+}
+/** One step's dispatch-time evidence: whether it ran (an on_failure guard may skip it) and, if
+ * it ran, whether its terminal matched its declared `produces` slot. */
+interface SetupStepRunOutcome {
+    name: string;
+    ran: boolean;
+    ok: boolean;
+    value?: unknown;
+}
+interface RunResult {
+    target: "codex:local";
+    component: string;
+    /** The last step that actually ran's raw terminal text — unchanged for every existing
+     * single-step component, since there the last step run is the only step run. */
+    finalText: string;
+    events: WarbleCodexEvent[];
+    steps: SetupStepRunOutcome[];
+}
+declare function runSetup(prepared: PreparedSetupComponent, options: RunOptions): Promise<RunResult>;
+
+/** One step's dispatch-time evidence: whether it ran (an on_failure guard may skip it) and, if it
+ * ran, whether its terminal matched its declared `produces` slot. Mirrors `run.ts`'s
+ * `SetupStepRunOutcome` — kept as a separate type (not imported from `run.ts`) so Setup and Enrich
+ * stay two independent engines, by design. */
+interface EnrichStepRunOutcome {
+    name: string;
+    ran: boolean;
+    ok: boolean;
+    value?: unknown;
+}
+interface EnrichRunResult {
+    target: "codex:local";
+    component: string;
+    /** The last step that actually ran's raw terminal text — unchanged for every existing
+     * single-step component, since there the last step run is the only step run. */
+    finalText: string;
+    /** The parsed terminal object of the last step that actually ran. */
+    value: unknown;
+    events: CodexSessionEvent[];
+    steps: EnrichStepRunOutcome[];
+}
+/**
+ * Execute a read-only enrichment component's steps, in order, through one persistent Codex
+ * app-server session. The Codex thread is created before the first model turn begins; this
+ * preserves durable session history before any metered work can occur, while the host remains
+ * owner of enrichment run bookkeeping. Every step of one dispatch shares the same thread — see
+ * `session.ts`'s `CodexSessionRuntime.turn`, which now takes the current step and its marshalled
+ * `consumes` inputs — with produces/consumes marshalled between turns exactly as `run.ts`'s
+ * `runSetup` marshals them between one-shot processes, and the same recoverable-vs-fatal
+ * on_failure evaluation (`shouldRunStep`/`parseStepTerminal`).
+ */
+declare function runEnrich(prepared: PreparedEnrichComponent, request: string, options: SessionIsolationOptions): Promise<EnrichRunResult>;
+
+export { type AgentManifest, type AnalyticalExecutionKind, type AskAgentConfigBundle, type AskAgentConfigFile, type AskMcpServerConfig, type AskTierModels, type AskWhenGuard, type BuildProof, type CapabilityResolution, type CatalogTransportOptions, CodexAppServerTransport, type CodexArtifactReference, type CodexAskArtifactReference, type CodexAskEvent, type CodexAskRunResult, CodexAskRuntime, type CodexAskRuntimeOptions, type CodexAskStepResult, CodexDispatchError, type CodexHistoryItem, type CodexHistoryTurn, CodexJsonlMapper, type CodexRenderArtifactReference, type CodexSessionEvent, type CodexSessionHistory, type CodexSessionReference, CodexSessionRuntime, type CodexTurnReference, type CompletedOperationLedger, type ComponentNode, type DashboardRenderEnvelope, type DiscoverCodexModelsOptions, type DispatchContract, ENRICHMENT_CONTRACT_VERSION, ENRICHMENT_SINKS, type EnrichDomainCapability, type EnrichMcpServerConfig, type EnrichRunResult, type EnrichStepRunOutcome, type EnrichmentAudit, type EnrichmentChange, type EnrichmentConfidence, type EnrichmentDecision, type EnrichmentDecisionAction, type EnrichmentDecisionRequest, type EnrichmentDisposition, type EnrichmentEvidence, type EnrichmentHostContext, type EnrichmentMode, type EnrichmentOperationRisk, type EnrichmentPolicyInput, type EnrichmentProposal, type EnrichmentSink, type EnrichmentStatus, type EnrichmentTerminal, type Guardrail, type HostApprovalAttestation, type LlmCall, MODEL_CATALOG_VERSION, type Manifest, type McpServerConfig, type ModelCatalogModel, type ModelCatalogResult, type ModelCatalogUnavailableCode, type OnFailureGuard, type PrepareAskInput, type PrepareEnrichInput, type PrepareInput, type PreparedAskComponent, type PreparedAskStep, type PreparedEnrichComponent, type PreparedEnrichStep, type PreparedSetupComponent, type PreparedSetupStep, type RunOptions, type RunResult, SESSION_LIFECYCLE_OPERATIONS, SESSION_REFERENCE_VERSION, SUPPORTED_IR_VERSION, type SessionIsolationOptions, type SessionManifest, type SessionTurnStatus, type SetupDomainCapability, type SetupStepRunOutcome, type StepManifest, TARGET, type TargetDescription, type TrustedEnrichmentOperation, type ValidationProof, type WarbleCodexEvent, type WarbleIr, askContractMismatchReason, assertEnrichmentTerminal, buildAgentManifest, buildAppServerArgs, buildAskAgentManifest, buildAskDriverPrompt, buildAskManifest, buildCodexArgs, buildEnrichAgentManifest, buildEnrichManifest, buildManifest, buildPrompt, classifyDispatchContract, createAskAgentConfigBundle, decideEnrichment, describeAskTarget, describeEnrichTarget, describeTarget, discoverCodexModels, enrichContractMismatchReason, matchesAskContractShape, matchesEnrichContractShape, matchesSetupContractShape, parseIr, prepareAllSetup, prepareAsk, prepareEnrich, prepareSetup, renderAskAgentToml, runEnrich, runSetup, sanitizeCodexEnvironment, setupContractMismatchReason, supportsSetupAggregate, validateDashboardRenderEnvelope, validateSessionIsolation };