@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/agent/dist/core/messages.d.ts

@@ -0,0 +1,30 @@
+/** Custom message types of the agent runtime and their conversion to LLM messages. */
+import type { AgentMessage } from "../loop/index.ts";
+import type { Message, UserContent } from "@ragents/ai";
+export declare const COMPACTION_SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
+export declare const COMPACTION_SUMMARY_SUFFIX = "\n</summary>";
+/** A hidden note that a hook adds to one model call; it is not part of the context. */
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: string | UserContent[];
+    display: boolean;
+    details?: T;
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    tokensBefore: number;
+    timestamp: number;
+}
+declare module "../loop/types.ts" {
+    interface CustomAgentMessages {
+        custom: CustomMessage;
+        compactionSummary: CompactionSummaryMessage;
+    }
+}
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: number): CompactionSummaryMessage;
+/** Transform AgentMessages, including hook notes and compaction summaries, to LLM messages. */
+export declare function convertToLlm(messages: AgentMessage[]): Message[];
+//# sourceMappingURL=messages.d.ts.map

package/packages/agent/dist/core/model-runtime.d.ts

@@ -0,0 +1,32 @@
+import { type Api, type AssistantMessage, type AssistantMessageEventStream, type AuthCheck, type AuthResult, type Context, type Model, type SimpleStreamOptions } from "@ragents/ai";
+import { type ProviderConfigInput } from "./provider-composer.ts";
+/** A name under which a model of another provider is offered; only the alias is visible to callers. */
+export interface ModelAlias {
+    readonly alias: string;
+    readonly upstream: string;
+    readonly model: string;
+}
+/** The metadata of the target under the alias as id and name, with the alias provider as provider. */
+export declare function aliasedModel(providerId: string, alias: string, target: Model<Api>): Model<Api>;
+/** The built-in providers plus the ones registered at runtime; a key comes from the registration or the environment. */
+export declare class ModelRuntime {
+    private readonly models;
+    private readonly builtins;
+    private readonly registrations;
+    private aliasRegistration;
+    private constructor();
+    static create(): ModelRuntime;
+    getModels(providerId?: string): readonly Model<Api>[];
+    getModel(providerId: string, modelId: string): Model<Api> | undefined;
+    checkAuth(providerId: string): Promise<AuthCheck | undefined>;
+    getAuth(model: Model<Api>): Promise<AuthResult | undefined>;
+    streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+    completeSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;
+    /** A repeated registration keeps the earlier values it does not set; an invalid one throws and changes nothing. */
+    registerProvider(providerId: string, config: ProviderConfigInput): void;
+    /** Offers models of registered providers under alias names; requests go to the target, answers carry the alias. */
+    registerAliases(providerId: string, aliases: readonly ModelAlias[]): void;
+    private aliasModels;
+    private targetOf;
+}
+//# sourceMappingURL=model-runtime.d.ts.map

package/packages/agent/dist/core/provider-composer.d.ts

@@ -0,0 +1,25 @@
+import { type Api, type InputModality, type Model, type Provider } from "@ragents/ai";
+/** A provider registered at runtime: its models and a literal API key, over the built-in provider of the same id. */
+export interface ProviderConfigInput {
+    name?: string;
+    baseUrl?: string;
+    /** The key itself; it is sent as given, never read from the environment or a command. */
+    apiKey?: string;
+    api?: Api;
+    models?: Array<{
+        id: string;
+        name: string;
+        api?: Api;
+        baseUrl?: string;
+        reasoning: boolean;
+        thinkingLevelMap?: Model<Api>["thinkingLevelMap"];
+        input: InputModality[];
+        cost: Model<Api>["cost"];
+        contextWindow: number;
+        maxTokens: number;
+        compat?: Model<Api>["compat"];
+    }>;
+}
+/** Composes the built-in provider of the same id, if any, with a runtime registration. */
+export declare function composeModelProvider(providerId: string, base: Provider | undefined, config: ProviderConfigInput): Provider;
+//# sourceMappingURL=provider-composer.d.ts.map

package/packages/agent/dist/core/skills.d.ts

@@ -0,0 +1,20 @@
+/** A skill the host has read and checked; the agent runtime reads no skill files itself. */
+export interface Skill {
+    name: string;
+    description: string;
+    /** Where the host reads the SKILL.md. */
+    filePath: string;
+    baseDir: string;
+    /** How the model's tools reach the SKILL.md; its folder holds the skill's other files. */
+    location: string;
+    disableModelInvocation: boolean;
+}
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt.
+ */
+export declare function formatSkillsForPrompt(skills: readonly Skill[]): string;
+//# sourceMappingURL=skills.d.ts.map

package/packages/agent/dist/core/tool-definition.d.ts

@@ -0,0 +1,17 @@
+/** The form of the read, write, edit and bash tools; the host runs them in its workspace executor. */
+import type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../loop/index.ts";
+import type { Static, TSchema } from "typebox";
+export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown> {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TParams;
+    /** Optional compatibility shim to prepare raw tool call arguments before schema validation. */
+    prepareArguments?: (args: unknown) => Static<TParams>;
+    executionMode?: ToolExecutionMode;
+    execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined): Promise<AgentToolResult<TDetails>>;
+}
+/** Preserve parameter inference for standalone tool definitions. */
+export declare function defineTool<TParams extends TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): ToolDefinition<TParams, TDetails>;
+//# sourceMappingURL=tool-definition.d.ts.map

package/packages/agent/dist/core/tools/bash.d.ts

@@ -0,0 +1,58 @@
+import { Type } from "typebox";
+import type { ToolDefinition } from "../tool-definition.ts";
+import { type TruncationResult } from "./truncate.ts";
+export declare const BASH_MAX_BYTES: number;
+export declare const BASH_MAX_LINE_CHARS = 1000;
+declare const bashSchema: Type.TObject<{
+    command: Type.TString;
+    timeout: Type.TOptional<Type.TNumber>;
+    cwd: Type.TOptional<Type.TString>;
+}>;
+export interface BashToolDetails {
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (for example SSH).
+ */
+export interface BashOperations {
+    /**
+     * Execute a command and stream output.
+     * @param command The command to execute
+     * @param cwd Working directory
+     * @param options Execution options
+     * @returns Promise resolving to exit code (null if killed)
+     */
+    exec: (command: string, cwd: string, options: {
+        onData: (data: Buffer) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+/** Bash operations on the built-in local shell. */
+export declare function createLocalBashOperations(options?: {
+    shellPath?: string;
+}): BashOperations;
+export interface BashSpawnContext {
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+export interface BashToolOptions {
+    /** Custom operations for command execution. Default: local shell */
+    operations?: BashOperations;
+    /** Command prefix prepended to every command (for example shell setup commands) */
+    commandPrefix?: string;
+    /** Optional explicit shell path from settings */
+    shellPath?: string;
+    /** Hook to adjust command, cwd, or env before execution */
+    spawnHook?: BashSpawnHook;
+}
+export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): ToolDefinition<typeof bashSchema, BashToolDetails | undefined>;
+export {};
+//# sourceMappingURL=bash.d.ts.map

package/packages/agent/dist/core/tools/edit-diff.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared diff computation utilities for the edit and similar tools.
+ */
+export declare function detectLineEnding(content: string): "\r\n" | "\n";
+export declare function normalizeToLF(text: string): string;
+export declare function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string;
+/**
+ * Normalize text for fuzzy matching. Applies progressive transformations:
+ * - Strip trailing whitespace from each line
+ * - Normalize smart quotes to ASCII equivalents
+ * - Normalize Unicode dashes/hyphens to ASCII hyphen
+ * - Normalize special Unicode spaces to regular space
+ */
+export declare function normalizeForFuzzyMatch(text: string): string;
+interface MatchedEdit {
+    editIndex: number;
+    matchIndex: number;
+    matchLength: number;
+    newText: string;
+}
+type TextReplacement = Pick<MatchedEdit, "matchIndex" | "matchLength" | "newText">;
+/**
+ * Apply replacements matched against `baseContent` to `originalContent` while
+ * preserving unchanged line blocks from the original.
+ *
+ * This is useful when `baseContent` is a normalized view of the original. Each
+ * replacement is widened to the lines it actually touches, those touched lines
+ * are rewritten from the normalized base, and all other lines are copied back
+ * from `originalContent`. The actual replacement ranges drive preservation so
+ * duplicate normalized lines cannot be aligned to the wrong occurrence.
+ */
+export declare function applyReplacementsPreservingUnchangedLines(originalContent: string, baseContent: string, replacements: TextReplacement[]): string;
+export interface FuzzyMatchResult {
+    /** Whether a match was found */
+    found: boolean;
+    /** The index where the match starts (in the content that should be used for replacement) */
+    index: number;
+    /** Length of the matched text */
+    matchLength: number;
+    /** Whether fuzzy matching was used (false = exact match) */
+    usedFuzzyMatch: boolean;
+    /**
+     * The content to use for replacement operations.
+     * When exact match: original content. When fuzzy match: normalized content.
+     */
+    contentForReplacement: string;
+}
+export interface Edit {
+    oldText: string;
+    newText: string;
+    /** 1-based index of the occurrence to replace when oldText is not unique */
+    occurrence?: number;
+    /** Line number close to the intended occurrence; the closest occurrence wins */
+    nearLine?: number;
+    /** Replace every occurrence instead of requiring a unique match */
+    replaceAll?: boolean;
+}
+export interface AppliedEditsResult {
+    baseContent: string;
+    newContent: string;
+    /** Number of replaced regions, which is larger than edits.length when replaceAll is used */
+    replacementCount: number;
+}
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+export declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
+/** Strip UTF-8 BOM if present, return both the BOM (if any) and the text without it */
+export declare function stripBom(content: string): {
+    bom: string;
+    text: string;
+};
+/**
+ * Apply one or more exact-text replacements to LF-normalized content.
+ *
+ * All edits are matched against the same original content. An edit replaces its
+ * unique match, the match picked by occurrence or nearLine, or every match when
+ * replaceAll is set. Replacements are applied in reverse order so offsets remain
+ * stable. If any edit needs fuzzy matching, the operation runs in fuzzy-normalized
+ * content space and then overlays those line-level changes onto the original
+ * content so unchanged line blocks keep their original bytes.
+ */
+export declare function applyEditsToNormalizedContent(normalizedContent: string, edits: Edit[], path: string): AppliedEditsResult;
+/** Generate a standard unified patch. */
+export declare function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines?: number): string;
+/**
+ * Generate a display-oriented diff string with line numbers and context.
+ * Returns both the diff string and the first changed line number (in the new file).
+ */
+export declare function generateDiffString(oldContent: string, newContent: string, contextLines?: number): {
+    diff: string;
+    firstChangedLine: number | undefined;
+};
+export {};
+//# sourceMappingURL=edit-diff.d.ts.map

package/packages/agent/dist/core/tools/edit.d.ts

@@ -0,0 +1,41 @@
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../tool-definition.ts";
+declare const editSchema: Type.TObject<{
+    path: Type.TString;
+    edits: Type.TArray<Type.TObject<{
+        oldText: Type.TString;
+        newText: Type.TString;
+        occurrence: Type.TOptional<Type.TNumber>;
+        nearLine: Type.TOptional<Type.TNumber>;
+        replaceAll: Type.TOptional<Type.TBoolean>;
+    }>>;
+}>;
+export type EditToolInput = Static<typeof editSchema>;
+export interface EditToolDetails {
+    /** Display-oriented diff of the changes made */
+    diff: string;
+    /** Standard unified patch of the changes made */
+    patch: string;
+    /** Line number of the first change in the new file (for editor navigation) */
+    firstChangedLine?: number;
+    contentHash: string;
+}
+/**
+ * Pluggable operations for the edit tool.
+ * Override these to delegate file editing to remote systems (for example SSH).
+ */
+export interface EditOperations {
+    /** Read file contents as a Buffer */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Check if file is readable and writable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+}
+export interface EditToolOptions {
+    /** Custom operations for file editing. Default: local filesystem */
+    operations?: EditOperations;
+}
+export declare function createEditToolDefinition(cwd: string, options?: EditToolOptions): ToolDefinition<typeof editSchema, EditToolDetails | undefined>;
+export {};
+//# sourceMappingURL=edit.d.ts.map

package/packages/agent/dist/core/tools/file-mutation-queue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Serialize file mutation operations targeting the same file.
+ * Operations for different files still run in parallel.
+ */
+export declare function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=file-mutation-queue.d.ts.map

package/packages/agent/dist/core/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { type BashOperations, createBashToolDefinition } from "./bash.ts";
+export { createEditToolDefinition } from "./edit.ts";
+export { createReadToolDefinition } from "./read.ts";
+export { createWriteToolDefinition } from "./write.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/dist/core/tools/output-accumulator.d.ts

@@ -0,0 +1,58 @@
+import { type TruncationResult } from "./truncate.ts";
+export interface OutputAccumulatorOptions {
+    maxLines?: number;
+    maxBytes?: number;
+    /** Lines longer than this are shortened in snapshots and marked; the temp file keeps them whole. */
+    maxLineChars?: number;
+    tempFilePrefix?: string;
+}
+export interface OutputSnapshot {
+    content: string;
+    truncation: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Incrementally tracks streaming output with bounded memory.
+ *
+ * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
+ * tail for display snapshots, and opens a temp file when the full output needs
+ * to be preserved.
+ */
+export declare class OutputAccumulator {
+    private readonly maxLines;
+    private readonly maxBytes;
+    private readonly maxLineChars;
+    private readonly maxRollingBytes;
+    private readonly tempFilePrefix;
+    private readonly decoder;
+    private rawChunks;
+    private tailText;
+    private tailBytes;
+    private tailStartsAtLineBoundary;
+    private totalRawBytes;
+    private totalDecodedBytes;
+    private completedLines;
+    private totalLines;
+    private currentLineBytes;
+    private currentLineChars;
+    private longestLineChars;
+    private hasOpenLine;
+    private finished;
+    private tempFilePath;
+    private tempFileStream;
+    constructor(options?: OutputAccumulatorOptions);
+    append(data: Buffer): void;
+    finish(): void;
+    snapshot(options?: {
+        persistIfTruncated?: boolean;
+    }): OutputSnapshot;
+    closeTempFile(): Promise<void>;
+    getLastLineBytes(): number;
+    hasShortenedLines(): boolean;
+    private appendDecodedText;
+    private trimTail;
+    private getSnapshotText;
+    private shouldUseTempFile;
+    private ensureTempFile;
+}
+//# sourceMappingURL=output-accumulator.d.ts.map

package/packages/agent/dist/core/tools/path-utils.d.ts

@@ -0,0 +1,8 @@
+export declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export declare function resolveToCwd(filePath: string, cwd: string): string;
+export declare function resolveReadPathAsync(filePath: string, cwd: string): Promise<string>;
+//# sourceMappingURL=path-utils.d.ts.map

package/packages/agent/dist/core/tools/read.d.ts

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+import type { ToolDefinition } from "../tool-definition.ts";
+import { type TruncationResult } from "./truncate.ts";
+declare const readSchema: Type.TObject<{
+    path: Type.TString;
+    offset: Type.TOptional<Type.TNumber>;
+    limit: Type.TOptional<Type.TNumber>;
+}>;
+export interface ReadToolDetails {
+    truncation?: TruncationResult;
+    contentHash?: string;
+}
+/**
+ * Pluggable operations for the read tool.
+ * Override these to delegate file reading to remote systems (for example SSH).
+ */
+export interface ReadOperations {
+    /** Read file contents as a Buffer */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Check if file is readable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+    /** Detect image MIME type, return null or undefined for non-images */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+export interface ReadToolOptions {
+    /** Whether to auto-resize images to 2000x2000 max. Default: true */
+    autoResizeImages?: boolean;
+    /** Custom operations for file reading. Default: local filesystem */
+    operations?: ReadOperations;
+}
+export declare function createReadToolDefinition(cwd: string, options?: ReadToolOptions): ToolDefinition<typeof readSchema, ReadToolDetails | undefined>;
+export {};
+//# sourceMappingURL=read.d.ts.map

package/packages/agent/dist/core/tools/truncate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+export interface TruncationResult {
+    /** The truncated content */
+    content: string;
+    /** Whether truncation occurred */
+    truncated: boolean;
+    /** Which limit was hit: "lines", "bytes", or null if not truncated */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Total number of lines in the original content */
+    totalLines: number;
+    /** Total number of bytes in the original content */
+    totalBytes: number;
+    /** Number of complete lines in the truncated output */
+    outputLines: number;
+    /** Number of bytes in the truncated output */
+    outputBytes: number;
+    /** Whether the last line was partially truncated (only for tail truncation edge case) */
+    lastLinePartial: boolean;
+    /** Whether the first line exceeded the byte limit (for head truncation) */
+    firstLineExceedsLimit: boolean;
+    /** The max lines limit that was applied */
+    maxLines: number;
+    /** The max bytes limit that was applied */
+    maxBytes: number;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 2000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+//# sourceMappingURL=truncate.d.ts.map

package/packages/agent/dist/core/tools/write.d.ts

@@ -0,0 +1,23 @@
+import { Type } from "typebox";
+import type { ToolDefinition } from "../tool-definition.ts";
+declare const writeSchema: Type.TObject<{
+    path: Type.TString;
+    content: Type.TString;
+}>;
+/**
+ * Pluggable operations for the write tool.
+ * Override these to delegate file writing to remote systems (for example SSH).
+ */
+export interface WriteOperations {
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Create directory recursively */
+    mkdir: (dir: string) => Promise<void>;
+}
+export interface WriteToolOptions {
+    /** Custom operations for file writing. Default: local filesystem */
+    operations?: WriteOperations;
+}
+export declare function createWriteToolDefinition(cwd: string, options?: WriteToolOptions): ToolDefinition<typeof writeSchema, undefined>;
+export {};
+//# sourceMappingURL=write.d.ts.map

package/packages/agent/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { aliasedModel, type ModelAlias, ModelRuntime } from "./core/model-runtime.ts";
+export { type AgentSettings, type AgentSettingsInput, agentSettings } from "./core/agent-settings.ts";
+export { activeContextEntries, type ContextCompaction, type ContextLogEntry, contextMessages, latestCompaction, } from "./core/context-log.ts";
+export { calculateContextTokens, compact, estimateContextTokens, prepareCompaction, shouldCompact, } from "./core/compaction/index.ts";
+export { convertToLlm } from "./core/messages.ts";
+export { formatSkillsForPrompt, type Skill } from "./core/skills.ts";
+export { defineTool, type ToolDefinition } from "./core/tool-definition.ts";
+export { type BashOperations, createBashToolDefinition, createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "./core/tools/index.ts";
+export { Agent, type AgentEvent, type AgentLoopTurnUpdate, type AgentMessage, type AgentTool, type AgentToolResult, EMPTY_RESPONSE_NUDGE, isRunFailure, type ThinkingLevel, } from "./loop/index.ts";
+export { parseFrontmatter, stripFrontmatter } from "./utils/frontmatter.ts";
+export { getShellConfig, killProcessTree, type ShellConfig } from "./utils/shell.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,13 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.ts";
+export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
+/** User message that follows a stop without text and without tool call, typically reasoning-only output. */
+export declare const EMPTY_RESPONSE_NUDGE = "Deine Antwort enthielt weder Text noch Werkzeugaufruf. Antworte jetzt mit dem n\u00E4chsten Werkzeugaufruf oder Deiner Antwort.";
+/** Error message of the assistant message that ends the loop after the nudge stayed unanswered. */
+export declare const EMPTY_RESPONSE_FAILURE = "Modell lieferte zweimal eine leere Antwort.";
+export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
+export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
+//# sourceMappingURL=agent-loop.d.ts.map

package/packages/agent/dist/loop/agent.d.ts

@@ -0,0 +1,99 @@
+import { type ImageContent, type Message, type ThinkingBudgets, type Transport } from "@ragents/ai";
+import type { AfterToolCallContext, AfterToolCallResult, AgentEvent, AgentLoopConfig, AgentLoopTurnUpdate, AgentMessage, AgentState, PrepareNextTurnContext, StreamFn, ToolExecutionMode } from "./types.ts";
+/** Options for constructing an {@link Agent}. */
+export interface AgentOptions {
+    initialState?: Partial<Omit<AgentState, "pendingToolCalls" | "isStreaming" | "streamingMessage" | "errorMessage">>;
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    streamFn?: StreamFn;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    formatUnknownToolError?: AgentLoopConfig["formatUnknownToolError"];
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+    prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
+    prepareNextTurnWithContext?: (context: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
+    steeringSource?: AgentLoopConfig["getSteeringMessages"];
+    sessionId?: string;
+    thinkingBudgets?: ThinkingBudgets;
+    transport?: Transport;
+    maxRetryDelayMs?: number;
+    toolExecution?: ToolExecutionMode;
+}
+/** Whether a message is the stand-in the agent reports for a failed run; no model produced it. */
+export declare const isRunFailure: (message: AgentMessage) => boolean;
+export declare class Agent {
+    private _state;
+    private readonly listeners;
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    streamFn: StreamFn;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    formatUnknownToolError?: AgentLoopConfig["formatUnknownToolError"];
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+    prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
+    prepareNextTurnWithContext?: (context: PrepareNextTurnContext, signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
+    private activeRun?;
+    /** Session identifier forwarded to providers for cache-aware backends. */
+    sessionId?: string;
+    /** Optional per-level thinking token budgets forwarded to the stream function. */
+    thinkingBudgets?: ThinkingBudgets;
+    /** Preferred transport forwarded to the stream function. */
+    transport: Transport;
+    /** Optional cap for provider-requested retry delays. */
+    maxRetryDelayMs?: number;
+    /** Tool execution strategy for assistant messages that contain multiple tool calls. */
+    toolExecution: ToolExecutionMode;
+    /** Messages to inject into the running prompt before its next model request. */
+    steeringSource?: AgentLoopConfig["getSteeringMessages"];
+    constructor(options?: AgentOptions);
+    /**
+     * Subscribe to agent lifecycle events.
+     *
+     * Listener promises are awaited in subscription order and are included in
+     * the current run's settlement. Listeners also receive the active abort
+     * signal for the current run.
+     *
+     * `agent_end` is the final emitted event for a run, but the agent does not
+     * become idle until all awaited listeners for that event have settled.
+     */
+    subscribe(listener: (event: AgentEvent, signal: AbortSignal) => Promise<void> | void): () => void;
+    /**
+     * Current agent state.
+     *
+     * Assigning `state.tools` or `state.messages` copies the provided top-level array.
+     */
+    get state(): AgentState;
+    /** Active abort signal for the current run, if any. */
+    get signal(): AbortSignal | undefined;
+    /** Abort the current run, if one is active. */
+    abort(): void;
+    /**
+     * Resolve when the current run and all awaited event listeners have finished.
+     *
+     * This resolves after `agent_end` listeners settle.
+     */
+    waitForIdle(): Promise<void>;
+    /** Clear transcript state and runtime state. */
+    reset(): void;
+    /** Start a new prompt from text, a single message, or a batch of messages. */
+    prompt(message: AgentMessage | AgentMessage[]): Promise<void>;
+    prompt(input: string, images?: ImageContent[]): Promise<void>;
+    /** Continue from the current transcript. The last message must be a user or tool-result message. */
+    continue(): Promise<void>;
+    private normalizePromptInput;
+    private runPromptMessages;
+    private runContinuation;
+    private createContextSnapshot;
+    private createLoopConfig;
+    private runWithLifecycle;
+    private handleRunFailure;
+    private finishRun;
+    /**
+     * Reduce internal state for a loop event, then await listeners.
+     *
+     * `agent_end` only means no further loop events will be emitted. The run is
+     * considered idle later, after all awaited listeners for `agent_end` finish
+     * and `finishRun()` clears runtime-owned state.
+     */
+    private processEvents;
+}
+//# sourceMappingURL=agent.d.ts.map