import { type CompiledGraph } from '../graph/graph.js';
import type { GraphCheckpointer, NodeContext } from '../types/graph.js';
import type { CompletionRequest, Message, ToolDefinition } from '../types/messages.js';
import type { NexusResponse } from '../types/response.js';
import type { Store } from '../types/store.js';
/**
 * An agent as a graph.
 *
 * `AgentLoop` is a `while` loop: it cannot be paused, resumed after a restart, inspected halfway, or
 * made to run two tool calls at once, because a loop has nowhere to keep that state. The same agent
 * expressed as a graph inherits all of it — checkpoints, human approval through `interrupt()`,
 * parallel tool tasks through `Send`, forks, events, and a Mermaid diagram — without this module
 * implementing any of them. `AgentLoop` stays for the simple case that wants none of that.
 */
/** The model call an agent makes. Injected, so this module needs no provider runtime. */
export interface AgentModelClient {
    /** Runs one completion. */
    complete(request: CompletionRequest): Promise<NexusResponse>;
}
/** A tool call the agent is about to make. */
export interface AgentToolCall {
    /** The model's id for the call. */
    id: string;
    /** The tool's name. */
    name: string;
    /** Arguments, parsed from the model's JSON. */
    args: Record<string, unknown>;
}
/** What an approver may answer: allow, refuse with a reason, or allow with corrected arguments. */
export type AgentApproval = boolean | {
    approved: true;
    args?: Record<string, unknown>;
} | {
    approved: false;
    reason?: string;
};
/** How a call to a tool that needs approval is presented to the operator. */
export interface AgentApprovalPolicy {
    /** The question an operator sees. Defaults to naming the tool and its arguments. */
    reason?: (call: AgentToolCall) => string;
}
/** Hooks around the agent's model calls and tool calls. Each hook is optional. */
export interface AgentMiddleware {
    /** Names the middleware in traces and errors. */
    name?: string;
    /** Adjusts the request before it is sent: trim history, add context, swap the model. */
    beforeModel?(context: {
        request: CompletionRequest;
        state: AgentState;
        store?: Store;
    }): CompletionRequest | void | Promise<CompletionRequest | void>;
    /** Inspects or replaces the response: redact, validate, count. */
    afterModel?(context: {
        response: NexusResponse;
        state: AgentState;
        store?: Store;
    }): NexusResponse | void | Promise<NexusResponse | void>;
    /** Wraps a tool call, so a policy can log it, time it, or refuse it. */
    wrapToolCall?(call: AgentToolCall, next: () => Promise<AgentToolResult>): Promise<AgentToolResult> | AgentToolResult;
}
/** What a tool call produced. */
export interface AgentToolResult {
    /** True when the tool returned a value. */
    ok: boolean;
    /** The value returned. */
    result?: unknown;
    /** Why the tool failed. */
    error?: string;
}
/** Options for `createAgent()`. */
export interface CreateAgentOptions {
    /** Client the model is called through. */
    client: AgentModelClient;
    /** Model to use. Defaults to the client's routing. */
    model?: string;
    /** Tools the model may call. */
    tools?: ToolDefinition[];
    /** System prompt placed before the conversation. */
    systemPrompt?: string;
    /** Model calls before the agent stops with `stopReason: 'max_iterations'`. Defaults to 8. */
    maxIterations?: number;
    /** Tool calls run at once. Defaults to 8; `1` runs them one at a time. */
    toolConcurrency?: number;
    /** Tools that need human approval before they run, keyed by tool name. */
    interruptOn?: Record<string, AgentApprovalPolicy | true>;
    /** Hooks around model and tool calls, applied in order. */
    middleware?: AgentMiddleware[];
    /** Long-term memory, available to tools and middleware as `store`. */
    store?: Store;
    /**
     * Where checkpoints go. Defaults to the graph's in-process checkpointer; `false` disables them,
     * and with them approvals.
     */
    checkpointer?: GraphCheckpointer | false;
    /** Names the agent in checkpoints and traces. */
    name?: string;
    /** Sampling temperature. */
    temperature?: number;
    /** Output token limit. */
    maxTokens?: number;
    /** Structured output format for answers. */
    responseFormat?: CompletionRequest['responseFormat'];
    /** Application data sent with every model request. */
    metadata?: Record<string, unknown>;
}
declare const agentChannels: () => {
    messages: import("../types/graph.js").Channel<Message[]>;
    iterations: import("../types/graph.js").Channel<number>;
    answer: import("../types/graph.js").Channel<string>;
    stopReason: import("../types/graph.js").Channel<AgentStopReason | undefined>;
};
/** The agent's state channels, as a graph schema. */
export type AgentChannels = ReturnType<typeof agentChannels>;
/** The agent's state. */
export type AgentState = {
    /** The conversation, tool calls and results included. */
    messages: Message[];
    /** Model calls made so far. */
    iterations: number;
    /** The final answer, once the model stops calling tools. */
    answer: string;
    /** Why the agent stopped. */
    stopReason?: AgentStopReason;
};
/** `completed` when the model answered, `max_iterations` when it ran out of model calls. */
export type AgentStopReason = 'completed' | 'max_iterations';
/** An agent: a compiled graph over the agent's channels. */
export type AgentGraph = CompiledGraph<AgentChannels>;
/** Wraps a question into the state an agent starts from. */
export declare function agentInput(goal: string): {
    messages: Message[];
};
/**
 * Builds an agent and returns it as a compiled graph.
 *
 * Run it like any graph: `agent.invoke(agentInput('...'), { threadId })`. The result's `answer` is
 * the final text, and `stopReason` says whether the agent finished or ran out of iterations.
 */
export declare function createAgent(options: CreateAgentOptions): AgentGraph;
/**
 * Turns an agent into a tool another agent can call.
 *
 * The simplest multi-agent shape: a supervisor keeps control and delegates, rather than handing over
 * the conversation. The specialist runs as its own graph, with its own memory and approvals, and
 * returns its answer as the tool result.
 */
export declare function agentAsTool(options: {
    agent: AgentGraph;
    name: string;
    description: string;
    /** Threads the specialist's runs, so its work is resumable too. Defaults to a fresh thread. */
    threadId?: (goal: string) => string;
}): ToolDefinition;
export type { NodeContext };