import { AgentFallbackPolicy } from "./fallback/index.js";
import { MergeGuardConfig } from "./lateral-leak/merge-guard.js";
import { ChildResult, FanOutOptions, FanOutResult, MergeStrategy, PerChildBudget } from "./fanout/index.js";
import { CausalityMonitorConfig } from "./lateral-leak/causality-monitor.js";
import { ProgressIO, ProgressReadOptions, ProgressWriteOptions } from "./progress/index.js";
import * as _graphorin_core0 from "@graphorin/core";
import { AgentEvent, AgentResult, CheckpointStore, HandoffFilter, Message, ModelHint, ModelSpec, ProgressArtifactRef, Provider, ProviderCachePolicy, ReasoningRetention, RunContext, RunState, Sensitivity, StopCondition, Tool, ToolChoice, Tracer } from "@graphorin/core";
import { InputGuardrail, OutputGuardrail } from "@graphorin/security/guardrails";
import { ResultReader } from "@graphorin/tools/result";
import { DataFlowPolicyConfig } from "@graphorin/security/dataflow";
import { RuleOfTwoProfile, ToolArgumentPolicy } from "@graphorin/security/policy";
import { ToolRegistry } from "@graphorin/tools/registry";
import { Memory, PostCompactionHook } from "@graphorin/memory";

//#region src/types.d.ts

/**
 * Forward-compatible type alias for the input accepted by
 * `Agent.stream / run / steer / followUp`. v0.1 ships with the
 * canonical text + multimodal Message shape; future versions may
 * add structured inputs.
 *
 * @stable
 */
type AgentInput = string | Message | ReadonlyArray<Message>;
/**
 * Output type specification.
 *
 * @stable
 */
interface OutputSpec<TOutput> {
  readonly kind: 'text' | 'structured';
  /**
   * Local validator (Zod-compatible `{ parse }`) applied to the final
   * model output on the completed path (AG-3). A parse failure fails
   * the run with `output-validation-failed` - never a silent cast.
   */
  readonly schema?: {
    parse(value: unknown): TOutput;
  };
  /** Optional description shown to the model alongside the schema. */
  readonly description?: string;
  /**
   * Wire-format JSON Schema advertised to the model: forwarded on
   * `ProviderRequest.outputType` for adapters with native structured
   * output, and embedded in the fallback JSON instruction appended as
   * a trailing system message (the documented contract until adapters
   * consume `outputType` natively - PS-24).
   */
  readonly jsonSchema?: Readonly<Record<string, unknown>>;
}
/**
 * Per-step override hook. Receives the current `RunContext` and may
 * return overrides applied to the next provider call only.
 *
 * @stable
 */
type PrepareStepHook<TDeps = unknown> = (ctx: RunContext<TDeps>) => Promise<PrepareStepOverrides<TDeps>> | PrepareStepOverrides<TDeps>;
/** @stable */
interface PrepareStepOverrides<TDeps = unknown> {
  readonly provider?: Provider;
  readonly tools?: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
  readonly toolChoice?: ToolChoice;
  readonly temperature?: number;
  readonly maxTokens?: number;
}
/**
 * Compaction post-hook factory accepted by `createAgent({...})`.
 * Re-exported from `@graphorin/memory` here for ergonomic typing.
 *
 * @stable
 */
type PostCompactionHook$1 = PostCompactionHook;
/**
 * Skill-registry shape consumed by the agent loop. Implementations
 * live in `@graphorin/skills`. We accept any structurally-compatible
 * value to avoid the heavyweight peer dependency on the typing
 * surface.
 *
 * @stable
 */
interface SkillsRegistryLike {
  list?(): ReadonlyArray<unknown>;
}
/**
 * Handoff target entry accepted by `createAgent({ handoffs })`.
 * Either a bare {@link Agent} reference (default filter applied) or
 * an explicit `{ target, inputFilter? }` envelope.
 *
 * @stable
 */
type HandoffEntry<TDeps = unknown> = Agent<TDeps, any> | {
  readonly target: Agent<TDeps, any>;
  readonly inputFilter?: HandoffFilter;
};
/**
 * The full options object accepted by {@link createAgent}.
 *
 * @stable
 */
interface AgentConfig<TDeps = unknown, TOutput = string> {
  readonly name: string;
  /**
   * The agent's system prompt. A string is used verbatim; a function is
   * resolved **once per run** (sync or async, awaited) against a
   * {@link RunContext} snapshot at step 0, and its result is pinned as the
   * run's system-prompt prefix for the whole run (it is not re-evaluated
   * per step). An empty string injects no system message.
   */
  readonly instructions: string | ((ctx: RunContext<TDeps>) => string | Promise<string>);
  readonly provider: Provider;
  readonly tools?: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
  readonly skills?: SkillsRegistryLike;
  readonly memory?: Memory;
  /**
   * Opt in to building the per-run system prompt from the memory
   * {@link ContextEngine} (CE-1). When `true` **and** `memory` is wired, the
   * runtime calls `memory.contextEngine.assemble(...)` once at run start: the
   * agent's `instructions` become Layer 2 and the engine prepends the memory
   * base and appends working blocks, procedural rules, skill cards, the
   * metadata counts, and - when `factsAutoRecall` is configured - auto-recalled
   * facts. Defaults `false`: the prompt is built from `instructions` alone and
   * the model reaches memory only through the memory tools it calls (the
   * documented explicit pattern). Has no effect without `memory`.
   */
  readonly autoAssembleContext?: boolean;
  readonly handoffs?: ReadonlyArray<HandoffEntry<TDeps>>;
  readonly outputType?: OutputSpec<TOutput>;
  /**
   * Deterministic checks run by the loop (AG-2; canonical contract is
   * `@graphorin/security`'s `GuardrailDefinition` - SDF-4).
   *
   * - `input` guardrails run over each **fresh-run seed user message**
   *   (string content) before the first provider call. `'block'` fails
   *   the run (`guardrail-blocked`) without reaching the model;
   *   `'rewrite'` replaces the message content (mirrored into the
   *   persisted `RunState`); `'warn'` logs and continues.
   * - `output` guardrails run over the **final output** on the
   *   completed path before `agent.end`. `'block'` fails the run;
   *   `'rewrite'` replaces `result.output` (text deltas were already
   *   streamed - the rewrite governs the durable result, not the
   *   live token stream).
   *
   * Every trip emits a `guardrail.tripped` event.
   */
  readonly guardrails?: {
    readonly input?: ReadonlyArray<InputGuardrail<string>>;
    readonly output?: ReadonlyArray<OutputGuardrail<TOutput>>;
  };
  readonly stopWhen?: StopCondition;
  readonly toolChoice?: ToolChoice;
  readonly prepareStep?: PrepareStepHook<TDeps>;
  readonly maxParallelTools?: number;
  /**
   * How the model invokes tools (P1-2).
   *
   * - `'direct'` (default) - the model emits one provider tool-call per
   *   tool, each result inlined into the conversation.
   * - `'code-mode'` - the agent advertises only the `code_execute` /
   *   `code_search` meta-tools; the model writes a script that calls
   *   tools in a sandbox via `tools.<name>(args)`, and **only the
   *   script's final result re-enters context** (intermediate results
   *   stay inside the sandbox). Each in-script call still runs through
   *   the executor, so per-tool ACL / sanitization / truncation apply.
   *   Approval-gated tools are not reachable from code-mode (there is no
   *   durable-HITL path mid-script); call those in `'direct'` mode.
   *
   * @default 'direct'
   */
  readonly toolInvocation?: 'direct' | 'code-mode';
  readonly fallbackModels?: ReadonlyArray<ModelSpec>;
  readonly fallbackPolicy?: AgentFallbackPolicy;
  readonly preferredModel?: ModelHint | ModelSpec;
  readonly modelTierMap?: Partial<Record<ModelHint, ModelSpec>>;
  /**
   * Per-agent override of the per-provider auto-detected
   * {@link ReasoningRetention} default. Wins over the provider-
   * level default when both are present. The agent runtime feeds
   * the effective value into every `provider.stream(...)` call so
   * the wire-correct contract is honoured per RB-42 / suggested
   * DEC-158 / suggested ADR-046.
   */
  readonly reasoningRetention?: ReasoningRetention;
  readonly causalityMonitor?: CausalityMonitorConfig;
  /**
   * Sideways-injection merge guard for `agent.fanOut` `'judge-merge'`
   * (AG-7): scores per-child source trust × contribution weight against
   * the judge's merged output; a biased merge emits
   * `agent.lateral-leak.detected` and `'detect-and-block'` throws
   * `MergeBlockedError`.
   */
  readonly mergeGuard?: MergeGuardConfig;
  /**
   * Provenance / taint-based data-flow policy (P1-3, opt-in). Enforces
   * data-flow rules at the tool-execution boundary using the provenance
   * Graphorin already tracks (trust class + source + sensitivity), to
   * defuse the lethal trifecta: a sink (`side-effecting` /
   * `external-stateful` tool) is blocked when untrusted content flows
   * into it verbatim, or - conservatively - when it fires while both
   * untrusted content and secret-tier data are present in the run.
   *
   * - `mode: 'shadow'`  - audit-only; tainted flows are flagged
   *   (`tool:dataflow:flagged` audit + counter) but never blocked. Ship
   *   this first to surface false positives.
   * - `mode: 'enforce'` - tainted flows are blocked (the sink does not
   *   run; the call yields a `dataflow_policy_blocked` error) unless the
   *   sink is listed in `declassifySinks` (an audited operator override).
   *
   * Composes with `'code-mode'`: each in-script tool call flows through
   * the same executor gate. Absent (the default) leaves the loop
   * unchanged.
   */
  readonly dataFlowPolicy?: DataFlowPolicyConfig;
  /**
   * Additional result-handle readers (P1-4 / WI-13), tried after the
   * built-in spill-file reader. Wire an MCP resource reader
   * (`createMcpResourceReader` from `@graphorin/mcp/client`) here so the
   * model can resolve an MCP `resource_link` on demand via the built-in
   * `read_result` tool, instead of inlining the resource body. Supplying
   * any reader force-registers `read_result` even when no tool spills.
   */
  readonly resultReaders?: ReadonlyArray<ResultReader>;
  /**
   * Opt-in prompt-cache breakpoint policy (core-provider-02), forwarded
   * verbatim on every `ProviderRequest` the loop issues. With
   * `{ breakpoints: 'auto' }` the Anthropic path (vercel adapter) anchors
   * `cache_control` markers on the first and last conversation messages,
   * so the stable prefix (tools + system + early turns) is written to the
   * provider cache once and read at the discounted rate on every later
   * step. Providers with automatic caching ignore it. Pair with the
   * append-only transcript the loop already maintains - cache hit rate is
   * the #1 production cost lever for multi-step agents.
   */
  readonly cachePolicy?: ProviderCachePolicy;
  /**
   * When deferred-tool promotions (via `tool_search`) take effect (C1):
   *
   * - `'immediate'` (default) - a promoted tool joins the catalogue on the
   *   NEXT step. Costs one provider-cache invalidation per promotion
   *   (the tools block changes), which is the standard trade for tool
   *   discovery.
   * - `'run-boundary'` - the catalogue advertised to the model is frozen
   *   for the whole run; promotions are still recorded (and persisted on
   *   `RunState.promotedTools`) but only join the catalogue on the next
   *   run / resume. Keeps the provider prompt cache byte-stable across
   *   every step of a run.
   */
  readonly toolPromotion?: 'immediate' | 'run-boundary';
  /**
   * C3: rules-based verifiers that run when the model emits a terminal
   * (no-tool-call) response. A failing verifier's feedback is appended
   * to the transcript as a user message and the loop continues, up to
   * `maxVerifierRounds` extra rounds. Verifiers are DETERMINISTIC checks
   * (lint/test runners, format validators, exit codes) - deliberately
   * not an evidence-free "reflect on your answer" step, which the
   * self-correction literature shows degrades performance.
   */
  readonly verifiers?: ReadonlyArray<ResponseVerifier>;
  /**
   * Cap on verifier-triggered continuation rounds per run (C3).
   * @default 1
   */
  readonly maxVerifierRounds?: number;
  /**
   * C3: transparent bounded retry for transient tool failures, forwarded
   * to the executor. Defaults (when set): `maxAttempts: 3`,
   * `backoffMs: 250`, `kinds: ['rate_limited']`; retries only ever run
   * for `pure` / `read-only` tools or tools with an `idempotencyKey`.
   */
  readonly toolRetry?: {
    readonly maxAttempts?: number;
    readonly backoffMs?: number;
    readonly kinds?: ReadonlyArray<_graphorin_core0.ToolErrorKind>;
  };
  /**
   * C3: journal each step's raw model response (text + tool calls +
   * model id) onto `RunState.steps[].providerResponse`, enabling
   * deterministic replay via `createReplayProvider(state)` - reproduce
   * an entire run without live model calls.
   * @default false
   */
  readonly recordProviderResponses?: boolean;
  readonly tracer?: Tracer;
  readonly checkpointStore?: CheckpointStore;
  readonly sensitivity?: Sensitivity;
  /**
   * Agent-default capability restriction (D2). `'read-only'` builds a
   * side-effect-free agent: writer tools and handoffs are never
   * advertised and the executor blocks writer calls deterministically
   * (`capability_blocked`). Per-call override:
   * {@link AgentCallOptions.capability}. See {@link AgentCapability}.
   */
  readonly capability?: AgentCapability;
  /**
   * Declarative tool-argument policy (D4 / Progent). Forbid-before-allow
   * rules over tool name + validated args, evaluated by the executor on
   * every call; default-deny sensitive tools with `defaultDenySensitive`.
   * A forbid verdict blocks the call (`capability_blocked`). Composes on
   * top of {@link ruleOfTwo}. See `@graphorin/security/policy`.
   */
  readonly toolPolicy?: ToolArgumentPolicy;
  /**
   * Rule-of-Two capability profile (D4). Declares which of {untrusted
   * input, sensitive data, external side effects} this agent may hold;
   * denying external side effects forces a read-only capability floor
   * and blocks writer tools, denying sensitive data default-denies
   * sensitive tools. Holding all three is the dangerous configuration
   * the preset is designed to prevent. See `@graphorin/security/policy`.
   */
  readonly ruleOfTwo?: RuleOfTwoProfile;
  /**
   * Register the D6 structured plan tool (`update_plan`, TodoWrite-style)
   * and recite the plan back into each step's prompt (attention
   * recitation). The plan is journaled in `RunState.todos` and survives
   * resume. Default `false` - off keeps the tool surface unchanged.
   */
  readonly plan?: boolean;
  readonly sessionId?: string;
  readonly userId?: string;
  readonly deps?: TDeps;
}
/**
 * Outcome of one {@link ResponseVerifier} check (C3).
 *
 * @stable
 */
type VerifierResult = {
  readonly ok: true;
} | {
  readonly ok: false;
  readonly feedback: string;
};
/**
 * A deterministic check over the model's terminal response (C3). Runs
 * when the loop is about to complete; `ok: false` feeds `feedback` back
 * to the model (as a user message prefixed `[verifier:<id>]`) and the
 * loop continues for up to `AgentConfig.maxVerifierRounds` extra rounds.
 *
 * A verifier that THROWS is treated as passed (and logged): a buggy
 * verifier must never take down a run.
 *
 * @stable
 */
interface ResponseVerifier {
  readonly id: string;
  verify(ctx: {
    /** The model's terminal text output (raw, pre-structured-parse). */
    readonly output: string;
    readonly state: RunState;
    readonly stepNumber: number;
  }): VerifierResult | Promise<VerifierResult>;
}
/**
 * Single approval decision attached to a {@link ResumeDirective}.
 * Mirrors the directive surface the HITL caller supplies on resume
 * (per `Command(approval: { granted, reason? })` in the agent-loop
 * reference, renamed to `Directive` per Graphorin's own naming).
 *
 * @stable
 */
interface ApprovalDecision {
  readonly toolCallId: string;
  readonly granted: boolean;
  readonly reason?: string;
}
/**
 * Resume directive accepted by `agent.run(input | RunState, { directive })`.
 *
 * The library-mode pickup pattern is: the operator stores the
 * suspended `RunState` from the previous `agent.run(...)` call,
 * waits for the user / cron / webhook to resolve the pending
 * approval, and re-invokes `agent.run(savedState, { directive: {
 * approvals: [...] } })` to resume.
 *
 * @stable
 */
interface ResumeDirective {
  readonly approvals?: ReadonlyArray<ApprovalDecision>;
}
/**
 * Per-call options accepted by `agent.stream(...)` / `agent.run(...)`.
 *
 * @stable
 */
interface AgentCallOptions<TDeps> {
  readonly deps?: TDeps;
  readonly signal?: AbortSignal;
  readonly sessionId?: string;
  readonly userId?: string;
  /**
   * HITL resume directive. Supplied alongside a `RunState` to
   * resolve any approvals that were pending when the previous
   * `agent.run(...)` call suspended.
   */
  readonly directive?: ResumeDirective;
  /**
   * Per-run capability restriction (D2) - overrides
   * {@link AgentConfig.capability} for this invocation. See that field
   * for semantics. Not persisted in `RunState`: re-supply it when
   * resuming a suspended run.
   */
  readonly capability?: AgentCapability;
}
/**
 * Run-level capability restriction (D2 - the single-writer constraint
 * from multi-agent practice). `'read-only'` makes the run
 * side-effect-free by construction: writer tools (`side-effecting` /
 * `external-stateful`) and handoffs are never advertised to the model,
 * and the tool executor deterministically blocks any writer call the
 * model fabricates anyway (`capability_blocked`). Use it to run
 * parallel research / explorer sub-agents while exactly one agent in
 * the topology keeps write capability.
 *
 * @stable
 */
type AgentCapability = 'read-only';
/**
 * `agent.toTool({...})` options.
 *
 * @stable
 */
interface AgentToToolOptions {
  readonly name?: string;
  readonly description?: string;
  readonly exposeTurns?: 'final' | 'all' | 'none';
  /**
   * Shapes the sub-agent seed from the parent history (AG-17): when
   * supplied, the sub-agent is seeded with
   * `[...inputFilter(parentMessages), { role: 'user', content: input }]`.
   * Without a filter the sub-agent sees ONLY the input string - no
   * parent conversation crosses the boundary (least authority by
   * construction; there is no secret-inheritance mechanism at this
   * boundary at all).
   */
  readonly inputFilter?: HandoffFilter;
  /**
   * Run the sub-agent under a restricted capability (D2): a
   * `'read-only'` worker cannot execute or advertise writer tools. The
   * orchestrator-worker recipe is `parent (full capability) + workers
   * via toTool({ capability: 'read-only', contextFold: true })`.
   */
  readonly capability?: AgentCapability;
  /**
   * Context folding at the sub-agent boundary (D2): instead of the raw
   * final output, the parent receives a compact distilled outcome -
   * status, step/tool-call counts, tools used, and the final text
   * clamped to `maxChars` (default 2000). Keeps tool-heavy child runs
   * from flooding the parent window. Default off (raw output).
   */
  readonly contextFold?: boolean | {
    readonly maxChars?: number;
  };
  /**
   * Propagate the child run's coarse taint flags across the fold (D2,
   * default `true`): when the child saw untrusted / sensitive content,
   * the tool result carries a widen-only `taint` override
   * (`sourceKind: 'sub-agent'`) that re-arms the PARENT's data-flow
   * ledger. A no-op when the parent has no `dataFlowPolicy`. Set
   * `false` only for children whose inputs are fully trusted.
   */
  readonly propagateTaint?: boolean;
}
/**
 * Cancellation options accepted by `agent.abort({...})`.
 *
 * @stable
 */
interface AbortOptions {
  /**
   * When `true`, let the in-flight provider stream finish (the current step
   * reaches its boundary) instead of interrupting it mid-event, then stop at the
   * next step. Default `false` hard-kills the in-flight stream immediately. (The
   * step's tool calls still observe the cancellation once the signal is set.)
   */
  readonly drain?: boolean;
  /**
   * What to do with approvals that were already requested but not
   * resolved at abort time.
   *
   * - `'deny'` (default) - auto-deny pending approvals.
   * - `'hold'`            - keep the approvals on `RunState.pendingApprovals`.
   * - `'fail'`            - reject the run with `RunError(code: 'run-aborted')`.
   */
  readonly onPendingApprovals?: 'deny' | 'hold' | 'fail';
}
/**
 * `agent.compact({...})` options.
 *
 * @stable
 */
interface CompactOptions {
  readonly source?: 'manual' | 'pre-step';
  readonly preserveRecentTurns?: number;
}
/**
 * Result of `agent.compact({...})`.
 *
 * @stable
 */
interface CompactionApiResult {
  readonly beforeTokens: number;
  readonly afterTokens: number;
  readonly summaryTokens: number;
  readonly durationMs: number;
  readonly hooksFiredCount: number;
  readonly summary: string;
  /**
   * `true` when the compaction trimmed + spliced the live run buffer
   * (CE-3/AG-13). `false` results carry an explicit
   * {@link skippedReason} instead of silently reporting zeros.
   */
  readonly applied: boolean;
  /** Why nothing was spliced, when {@link applied} is `false`. */
  readonly skippedReason?: 'no-memory' | 'no-active-run' | 'nothing-to-trim' | 'sensitivity-gated';
}
/**
 * Per-call shape accepted by `Agent.fanOut(...)`. Mirrors the
 * pure-function {@link FanOutOptions} but omits the runtime-supplied
 * identifiers - the `Agent` instance carries those.
 *
 * @stable
 */
interface AgentFanOutOptions<TOutput = unknown> {
  readonly children: FanOutOptions<TOutput>['children'];
  readonly maxConcurrentChildren?: number;
  readonly perBudget?: PerChildBudget;
  readonly mergeStrategy?: MergeStrategy<TOutput>;
  readonly signal?: AbortSignal;
}
/**
 * Progress IO surface exposed on the `Agent` instance. The methods
 * default the `runId` cursor to the in-flight run when present, so
 * callers can use them inside an `agent.run(...)` boundary without
 * repeating the cursor.
 *
 * @stable
 */
interface AgentProgressIO {
  write(content: string, options?: ProgressWriteOptions): Promise<ProgressArtifactRef>;
  read(options?: ProgressReadOptions): Promise<ReadonlyArray<ProgressArtifactRef>>;
}
/**
 * Public agent surface returned by {@link createAgent}.
 *
 * @stable
 */
interface Agent<TDeps = unknown, TOutput = string> {
  readonly id: string;
  readonly config: AgentConfig<TDeps, TOutput>;
  stream(input: AgentInput | RunState, options?: AgentCallOptions<TDeps>): AsyncIterable<AgentEvent<TOutput>>;
  run(input: AgentInput | RunState, options?: AgentCallOptions<TDeps>): Promise<AgentResult<TOutput>>;
  steer(message: AgentInput): void;
  followUp(message: AgentInput): void;
  abort(options?: AbortOptions): void;
  toTool(options?: AgentToToolOptions): Tool<{
    readonly input: string;
  }, TOutput, TDeps>;
  compact(options?: CompactOptions): Promise<CompactionApiResult>;
  /**
   * Convenience wrapper around the standalone `runFanOut(...)`. The
   * returned `FanOutResult` carries per-child status + the merged
   * output. Per-child failures are captured in `children[].status`
   * - this method never throws on a child failure (the merge
   * strategy decides whether to propagate).
   */
  fanOut<TFanOutOutput = unknown>(options: AgentFanOutOptions<TFanOutOutput>): Promise<FanOutResult<TFanOutOutput>>;
  /**
   * Structured handoff-artifact APIs. Persists / reads UTF-8 text
   * artifacts under the configured artifact root; cross-run reads
   * require an explicit `runId` cursor on the read options.
   */
  readonly progress: AgentProgressIO;
  /**
   * The unified tool registry assembled at `createAgent(...)` warm-up
   * (Principle #12): every first-party + skill tool, with cross-source
   * name collisions resolved deterministically. Read-only and exposed
   * for inspection; the run loop and `tool_search` consume it. Always
   * present on agents built by `createAgent(...)`.
   */
  readonly registry?: ToolRegistry;
}
//#endregion
export { AbortOptions, Agent, AgentCallOptions, AgentCapability, AgentConfig, AgentInput, AgentToToolOptions, CompactOptions, CompactionApiResult, OutputSpec, PostCompactionHook$1 as PostCompactionHook, PrepareStepHook, PrepareStepOverrides, ResponseVerifier, ResumeDirective, SkillsRegistryLike, VerifierResult };
//# sourceMappingURL=types.d.ts.map