import type { AgencyConfig } from "../config/config.js";
import type { Host } from "../host/host.js";
import type { Policy } from "./policy.js";
/**
 * Per-invocation overrides a caller may attach to a single node, served
 * function, or serve-resume invocation. This is the ONE public, declarative
 * request shape; a host (e.g. statelog) constructs it as trusted input.
 *
 * `config` is applied override-wins for that call only — agency performs no
 * clamping, bounds-checking, or trust filtering (that is host policy; see the
 * spec §2). `traceId` becomes the run's root trace id on a fresh invocation.
 */
export type InvocationOptions = {
    config?: Partial<AgencyConfig>;
    traceId?: string;
    /** Root interrupt policy for this invocation, installed as the outermost
     *  handler on the fresh run and re-installed on every resume leg. A
     *  `reject` here beats any approval from the program's own handlers
     *  (chain precedence: reject > propagate > approve). Replaces — does not
     *  merge with — an `AGENCY_RUN_POLICY` environment policy for this run.
     *  That makes an explicit empty policy `{}` a no-op that still disables
     *  the environment policy: it has no rules, so the installed handler
     *  abstains on every effect. To restrict everything, say so:
     *  `{ "*": [{ action: "reject" }] }`. */
    policy?: Policy;
    /** The host this run uses in place of the platform's default: a
     *  `memoryHost` in a test, or a `browserHost` whose terminal is the
     *  app's. A resume does not remember the host of the run it resumes, so
     *  the caller passes it again. See docs/dev/runtime/host.md. */
    host?: Host;
    /** What `input()` calls instead of reading the terminal, for a caller
     *  that owns the terminal, such as the debugger, whose text field takes
     *  the answer. Per execution: a resume does not remember it, so the
     *  caller passes it again. */
    inputOverride?: (prompt: string) => Promise<string>;
};
/**
 * A fresh run or a resume, described declaratively for {@link resolveInvocation}.
 * A fresh run may carry an inherited subprocess run id (which wins over any
 * supplied trace id) and a harness-given trace id from the environment
 * (`AGENCY_TRACE_ID`, the fallback below a supplied one); a resume carries
 * the run id read from the interrupt.
 */
export type InvocationRequest = {
    kind: "fresh";
    options?: InvocationOptions;
    inheritedRunId?: string;
    /** `AGENCY_TRACE_ID`, when a harness set it for the whole process tree. */
    environmentTraceId?: string;
    /** The trace the paused run was logging to, from the checkpoint a CLI
     *  resume starts from. Used only when nothing else names a trace. */
    checkpointTraceId?: string;
} | {
    kind: "resume";
    options?: InvocationOptions;
    runId: string;
};
/**
 * The subset of {@link PerInvocationContextOverride}.log that is honored
 * per-invocation. Deliberately narrower than `AgencyConfig.log`: `logFile` and
 * `debugMode` are excluded (local-only sinks, not part of this channel).
 */
export type PerInvocationLogConfig = {
    host?: string;
    apiKey?: string;
    projectId?: string;
    requestTimeoutMs?: number;
    metadata?: NonNullable<AgencyConfig["log"]>["metadata"];
};
/**
 * The positively allow-listed context override the runtime will apply. Every
 * field here is safe to override per-call. Fields absent from this type — all
 * `client.*`, `traceFile`/`traceDir`, `log.logFile`, and everything else — are
 * inert in this channel by construction: they are simply never copied across.
 */
export type PerInvocationContextOverride = {
    observability?: boolean;
    log?: PerInvocationLogConfig;
    budget?: AgencyConfig["budget"];
    maxCallDepth?: number;
    failurePropagation?: AgencyConfig["failurePropagation"];
};
/**
 * The runtime-internal result of resolving an {@link InvocationRequest}: one
 * effective run id plus an already-narrowed context override. Execution-context
 * construction consumes this directly and never re-derives the allow-list.
 */
export type ResolvedInvocation = {
    runId: string;
    contextOverride?: PerInvocationContextOverride;
    /** The validated root policy for this invocation, when the caller sent one. */
    policy?: Policy;
    /** The host for this invocation, when the caller sent one. */
    host?: Host;
    /** The `input()` override for this invocation, when the caller sent one. */
    inputOverride?: (prompt: string) => Promise<string>;
};
/**
 * The single owner of run-id policy and per-invocation config projection.
 * Transport layers forward an {@link InvocationRequest} here and receive a
 * {@link ResolvedInvocation}; no caller re-implements trace precedence, resume
 * policy, or the config allow-list.
 *
 * Run-id precedence for a fresh run: an inherited subprocess id wins (so child
 * events land in the parent's trace), then a supplied `traceId`, then the
 * environment's `AGENCY_TRACE_ID` (a harness giving a whole process tree —
 * root included — one trace id), then the trace id saved in the checkpoint a
 * CLI resume starts from (so the resumed run joins the paused run's trace,
 * as an interrupt response does), then a fresh `nanoid()`. A resume always
 * keeps `interrupt.runId`; a supplied `traceId` — empty or not — is ignored.
 * A supplied empty trace id on a fresh run is a caller error and is rejected.
 */
export declare function resolveInvocation(request: InvocationRequest): ResolvedInvocation;