@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/loop/run-agent.d.ts

@@ -1,245 +0,0 @@
-import { type FinishReason } from "ai";
-import type { AgentSession } from "../auth/types.js";
-import type { UsageRecorder } from "../billing/usage-recorder.js";
-import type { Logger } from "../lib/logger.js";
-import { type CompactionPolicy } from "./compaction.js";
-import type { AgentChat, ChatRequest, ChatResponse, PromptCachePolicy, ReasoningPolicy } from "../providers/types.js";
-import { type AskApproval, type AskRequest } from "../tools/approval/contract.js";
-import { type AgentRunUsage } from "./metrics.js";
-import { type ToolBudget, type ToolMask } from "./tool-mask.js";
-import { type ToolOutputStore } from "./tool-output.js";
-import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
-export interface AgentFinish {
-    readonly reason: FinishReason | "aborted" | "max_iterations" | "denied";
-    /**
-     * The endpoint's own word for the stop, when the provider captured one —
-     * `reason` normalizes it (an Anthropic `refusal` becomes `content-filter`).
-     */
-    readonly rawFinishReason?: string;
-    readonly cappedOut: boolean;
-    readonly truncationRecoveries: number;
-    /**
-     * What this loop's own LLM calls reported, the forced wrap-up included.
-     * Absent when no call reported anything — never an all-zero figure.
-     */
-    readonly usage?: AgentRunUsage;
-    /**
-     * The whole turn's total, every descendant loop included. Present only on
-     * the loop that created the turn accumulator — the run whose options
-     * carried none, which is by construction the turn's root.
-     */
-    readonly turnUsage?: AgentRunUsage;
-}
-export interface RunAgentResult {
-    readonly messages: LoopMessage[];
-    readonly finish: AgentFinish;
-}
-/** A request that the provider refused for its content: the HTTP status and the text of the provider error. */
-export interface RequestRefusal {
-    readonly status: number;
-    readonly message: string;
-}
-/** The result of a segment. A segment that ends on a refusal of its request carries the refusal. */
-export interface SegmentResult extends RunAgentResult {
-    readonly refusal?: RequestRefusal;
-}
-/** The messages that the loop appended after the last call of the round sink. */
-export interface AgentRound {
-    readonly messages: readonly LoopMessage[];
-}
-export interface StepNameFormatter {
-    llm(iteration: number): string;
-    tool(toolName: string, toolUseId: string): string;
-}
-export declare const DEFAULT_STEP_NAME_FORMATTER: StepNameFormatter;
-export interface RunAgentOptions {
-    readonly provider: AgentChat;
-    readonly signal: AbortSignal;
-    readonly emit: EmitFn;
-    /**
-     * The round sink. The loop awaits it before each model request, at each exit, and before a throw.
-     * A durable loop passes no sink, because DBOS replays the loop body.
-     */
-    readonly onRound?: (round: AgentRound) => Promise<void>;
-    /**
-     * The compaction policy. Each request then sends the view of the transcript, and the loop compacts
-     * before a task request whose view passes the budget. A durable loop passes no policy, because
-     * `recordsAfter` reads the database outside a step.
-     */
-    readonly compaction?: CompactionPolicy;
-    /**
-     * The messages that open the turn of a chat thread: the user message and its context records. The loop appends
-     * them after the turn-start compaction, thus the conversation holds each message in the order that it was sent.
-     * Absent: `initial` holds the whole conversation.
-     */
-    readonly turnInput?: readonly LoopMessage[];
-    /**
-     * Per-turn user-approval seam threaded into every tool's `ToolContext` as
-     * `ctx.ask`. A conversation tool calls it to pause for an explicit user
-     * decision; the caller (the turn) wires the realization that surfaces the
-     * prompt and returns the reply. Omitted on non-interactive paths (workflow
-     * contexts, headless embedders): approval then resolves to the shipped
-     * deny-by-default `UnavailableAsk`, so a tool that asks where nothing can
-     * answer is denied rather than left waiting on a surface that never responds.
-     */
-    readonly ask?: (request: AskRequest) => Promise<AskApproval>;
-    readonly runStep: RunStep;
-    readonly formatStepName?: StepNameFormatter;
-    readonly isFatalLoopError?: (err: unknown) => boolean;
-    /**
-     * Tool choice for every request of this run: part of the prefix that the
-     * prompt cache and a signed thinking block bind to.
-     */
-    readonly toolChoice?: ChatRequest["toolChoice"];
-    /**
-     * An early cap. Read at the top of each iteration; when it answers true the
-     * loop leaves the tool phase as if `maxIterations` were reached and takes the
-     * same tool-less wrap-up path, thus a terminal wrapper salvages the run the
-     * same way. A host uses it to end a run that a policy has judged to be a
-     * loop, for example one the call guard refused too many times, without
-     * waiting for the iteration cap or the wall clock.
-     */
-    readonly stopWhen?: () => boolean;
-    /**
-     * Optional outcome predicate for loop-driving agents whose result is
-     * recorded by a tool into closure state. Checked immediately after each
-     * dispatch round, once every sibling tool result has been appended.
-     */
-    readonly resolved?: () => boolean;
-    /**
-     * Tools allowed to run per request. The full tool set stays declared either
-     * way, since it is part of the cache/thinking-block prefix.
-     */
-    readonly toolMask?: ToolMask;
-    /** Max calls per tool for this run; a call in the same round counts against the budget too. */
-    readonly toolBudget?: ToolBudget;
-    /**
-     * Prompt-cache policy for every LLM call this run makes. Defaults to
-     * `DEFAULT_PROMPT_CACHE` (5m) — an agent loop always re-sends its prefix, so
-     * it breaks even by the second iteration. A host whose endpoint ignores or
-     * charges badly for cache directives passes `"off"`.
-     *
-     * The policy lives here, on the run, rather than on the provider, precisely
-     * so it applies to loops and *not* to the one-shot LLM calls made elsewhere
-     * (report generation): those would pay the
-     * cache-write premium for a cache nothing ever reads back.
-     */
-    readonly promptCache?: PromptCachePolicy;
-    /**
-     * The reasoning effort for each LLM call of this run, the forced wrap-up
-     * included. Anthropic discards its message cache when the top-level
-     * effort changes, so the run must send the same value, or none, throughout.
-     */
-    readonly reasoning?: ReasoningPolicy;
-    /**
-     * Diagnostic sink for the run's own lifecycle. Optional because `runAgent` is
-     * called from tools, workflow bodies, and test rigs alike — silence is the
-     * correct behaviour for a caller that wires nothing, and the noop fallback
-     * gives it without every call site threading `?.`.
-     *
-     * Distinct from `emit`, which feeds a user-facing surface: every host filters
-     * sub-agent events off that surface by `callPath` depth, so a sub-agent's
-     * progress is emitted and then dropped. This is where it survives.
-     */
-    readonly logger?: Logger;
-    /**
-     * Per-call LLM usage-accounting seam. Omitted falls back to the no-op
-     * recorder. `record` is a notice: the loop does not wait for its result,
-     * and it logs the reason of an `err` when the result arrives.
-     */
-    readonly usageRecorder?: UsageRecorder;
-    /** Keeps the text of each cut tool result. A run with no store cuts, and it keeps nothing. */
-    readonly toolOutputStore?: ToolOutputStore;
-    /**
-     * The turn's usage accumulator, supplied by whatever ran this loop as part
-     * of a larger turn (a sub-agent-running tool passes `ctx.turnUsage`). A run
-     * that receives none creates its own and is therefore the turn's root: it
-     * alone reports `turnUsage` on its finish.
-     */
-    readonly turnUsage?: AgentRunUsage;
-    /**
-     * The id of the tool call this loop runs inside, supplied by a
-     * sub-agent-running tool from its `ctx.invocationId`. It is what separates
-     * two dispatches of the *same* sub-agent in one round — they share the run
-     * frame, the call path, and every loop-local step name — in the usage
-     * record key. The data profile gives the workflow id of its attempt,
-     * because each profile runs under the same constant frame. Absent for any
-     * other loop that is not nested inside a tool dispatch (a chat turn's
-     * root, a workflow step body, a background task).
-     */
-    readonly invocationId?: string;
-}
-/** A run that receives no turn accumulator is the turn's root. See `RunAgentOptions.turnUsage`. */
-export declare const isTurnRoot: (opts: RunAgentOptions) => boolean;
-export declare function runAgent(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions): Promise<RunAgentResult>;
-/** The harness request of the wrap-up at the iteration cap. */
-export declare const WRAP_UP_REQUEST = "You reached the limit of tool rounds for this run, thus no tool can run now. Answer in text with the results that you have.";
-/** The cap of wrap-up requests: one answer, and one more request after a refused call. */
-export declare const WRAP_UP_MAX_REQUESTS = 2;
-/** One stretch of model requests of a conversation, under one mask. */
-export interface LoopSegment {
-    /** The tools that can run for each request of the segment. Absent lets each declared tool run. */
-    readonly mask: ToolMask | undefined;
-    readonly maxRequests: number;
-    readonly stepNames: StepNameFormatter;
-    /** The `index` of the first request of the segment in its `iteration` events. */
-    readonly firstIndex: number;
-    /** A harness request that the segment appends, as a synthetic user message, before its first request. */
-    readonly requestText?: string;
-    /**
-     * The segment runs after the iteration cap: its requests do not count as
-     * iterations, and the last one always ends the run, whatever its reply.
-     */
-    readonly closesCappedRun?: boolean;
-    /** The loop compacts before a request of the segment whose view passes the budget of the policy. */
-    readonly checksBudget?: boolean;
-    /** A refusal of a request, a `provider` error with the status `400` or `413`, ends the segment with no new message. */
-    readonly endsOnRequestRefusal?: boolean;
-}
-/**
- * One conversation, open for its segments. Each segment extends the same
- * prefix (system prompt, tools, tool choice) as the one before it.
- */
-export interface OpenLoop {
-    /**
-     * Compact the conversation when the last request passed the turn-start budget, and then append the input of the
-     * turn. The result of the run when an abort ends the compaction, or `undefined` when the run continues.
-     */
-    startTurn(input: readonly LoopMessage[]): Promise<RunAgentResult | undefined>;
-    /** Run one segment: the result of the run when a reply ends it, or `"capped"` when the segment used its cap. */
-    runSegment(segment: LoopSegment): Promise<SegmentResult | "capped">;
-    /** End a run after its last segment used its cap. */
-    endCapped(): Promise<RunAgentResult>;
-}
-/**
- * Open the loop over one conversation. `metricAgentId` is the id that usage
- * and run metrics count under, which is not always `agent.id`.
- */
-export declare function openLoop(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, metricAgentId: string): OpenLoop;
-/** What one completed LLM call is accounted under. */
-export interface ChatCallAccounting {
-    readonly session: AgentSession;
-    readonly agentId: string;
-    readonly callPath: readonly string[];
-    /**
-     * The deterministic name inside the record key, for example `llm-{n}` for
-     * a loop call or `adhoc-route` for a direct call.
-     */
-    readonly stepName: string;
-    /** The id of the tool call that makes the call, when the call runs inside a tool dispatch. */
-    readonly invocationId?: string;
-    readonly usageRecorder: UsageRecorder;
-    /** The sink that the notice helper logs the reason of a recorder `err` to. */
-    readonly logger: Logger;
-    /** The accumulators that the usage of the call folds into, for example the run total and the turn total. */
-    readonly rollups: readonly AgentRunUsage[];
-}
-/**
- * Called at the fold point, before any run-ending branch, so an aborted or
- * dead run is still accounted. Token counters grow inside the call's step
- * body, not here, because a replay re-delivers the stored reply to this
- * function too; the record re-sends under the same idempotency key, which an
- * upserting sink counts once.
- */
-export declare function accountForChatCall(reply: ChatResponse, call: ChatCallAccounting): void;
-export declare function finalText(messages: readonly LoopMessage[]): string;