indusagi 0.12.32 → 0.12.33

package/dist/types/facade/bot/actions/read.d.ts

@@ -0,0 +1,36 @@
+import type { AgentTool } from "../types.js";
+import { type TruncationResult } from "./truncate.js";
+declare const readSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface ReadToolDetails {
+    truncation?: TruncationResult;
+}
+/**
+ * Pluggable filesystem callbacks for the read tool. Override them to fetch
+ * files from an alternate backend, for instance an SSH or remote-mount layer.
+ */
+export interface ReadOperations {
+    /** Read a file's raw bytes. */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Verify the file can be read, raising if not. */
+    access: (absolutePath: string) => Promise<void>;
+    /** Return the file's image MIME type, or null/undefined for non-image files. */
+    detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+export interface ReadToolOptions {
+    /** Default true; when set, large images are shrunk to fit within 2000x2000. */
+    autoResizeImages?: boolean;
+    /** Swap out the filesystem callbacks; the local disk is used by default. */
+    operations?: ReadOperations;
+}
+export declare function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema>;
+/** Ready-to-use read tool bound to the current working directory. */
+export declare const readTool: AgentTool<import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/registry.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTool } from "../types.js";
+export type ToolCategory = "core" | "search" | "management" | "web" | "filesystem" | "mcp";
+export interface ToolMetadata {
+    name: string;
+    label: string;
+    category: ToolCategory;
+    description?: string;
+}
+export declare abstract class ToolFactory<TTool extends AgentTool<any> = AgentTool<any>> {
+    abstract readonly metadata: ToolMetadata;
+    abstract create(): TTool;
+}
+export declare class ToolRegistry {
+    private readonly metadata;
+    private readonly factories;
+    register<TTool extends AgentTool<any>>(meta: ToolMetadata, create: () => TTool): void;
+    create(name: string): AgentTool<any>;
+    createMany(names: string[]): AgentTool<any>[];
+    listMetadata(): ToolMetadata[];
+}

package/dist/types/facade/bot/actions/todo-store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Todo Store - Persistent todo list management
+ *
+ * @module agent/tools/todo-store
+ * @description
+ * Manages a todo list with optional persistence callbacks.
+ * The coding-agent uses this to integrate with SessionManager for session persistence.
+ *
+ * ## Architecture
+ *
+ * The TodoStore supports two modes:
+ * 1. **Simple mode** (default): Stores todos in memory only
+ * 2. **Persistent mode**: Uses callbacks to persist/load todos
+ *
+ * ## Usage
+ *
+ * ### Simple mode
+ * ```typescript
+ * const store = new TodoStore();
+ * store.setTodos([{ content: "Task", status: "pending", priority: "high" }]);
+ * ```
+ *
+ * ### Persistent mode (coding-agent style)
+ * ```typescript
+ * const store = new TodoStore({
+ *   persist: (todos) => sessionManager.appendCustomEntry('todo', { todos }),
+ *   load: () => loadFromSession(),
+ *   rebuildFromBranch: () => rebuildFromSession(),
+ * });
+ * ```
+ */
+import type { TodoItem, TodoStatus, TodoStoreOptions } from "./todo-types.js";
+export type { TodoItem, TodoStatus, TodoPriority, TodoStoreOptions, TodoToolDetails } from "./todo-types.js";
+declare const TODO_STATUSES: readonly ["pending", "in_progress", "completed", "cancelled"];
+declare const TODO_PRIORITIES: readonly ["high", "medium", "low"];
+/**
+ * Simple Todo Store for the todo tool.
+ * Supports optional persistence callbacks for session integration.
+ */
+export declare class TodoStore {
+    private todos;
+    private options?;
+    /**
+     * Create a new TodoStore
+     * @param initialTodos - Optional initial todos (takes precedence over load callback)
+     * @param options - Optional persistence callbacks
+     */
+    constructor(initialTodos?: TodoItem[], options?: TodoStoreOptions);
+    constructor(options?: TodoStoreOptions);
+    /**
+     * Get all todos (returns a copy)
+     */
+    getTodos(): TodoItem[];
+    /**
+     * Set todos and persist
+     */
+    setTodos(todos: TodoItem[]): void;
+    /**
+     * Find todos matching a query
+     */
+    find(query: string): TodoItem[];
+    /**
+     * Filter todos by status
+     */
+    filterByStatus(status: TodoStatus): TodoItem[];
+    /**
+     * Rebuild todos from session branch
+     * Called when navigating the session tree
+     */
+    rebuildFromBranch(): void;
+    /**
+     * Remove expired todos
+     */
+    private removeExpired;
+}
+export { TODO_STATUSES, TODO_PRIORITIES };

package/dist/types/facade/bot/actions/todo-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Todo Tool Types - Interfaces for extensible todo storage
+ *
+ * These interfaces allow the todo tool to be extended with custom persistence.
+ * The coding-agent uses these to integrate with SessionManager for session persistence.
+ */
+/**
+ * Todo item status
+ */
+export type TodoStatus = "pending" | "in_progress" | "completed" | "cancelled";
+/**
+ * Todo item priority
+ */
+export type TodoPriority = "high" | "medium" | "low";
+/**
+ * Todo item structure
+ */
+export interface TodoItem {
+    content: string;
+    status: TodoStatus;
+    priority: TodoPriority;
+    expiresAt?: number;
+}
+/**
+ * Todo tool details - returned after todo operations
+ */
+export interface TodoToolDetails {
+    todos: TodoItem[];
+    incompleteCount: number;
+}
+/**
+ * Options for TodoStore - allows custom persistence
+ *
+ * The coding-agent implements these to:
+ * - persist: Save todos to session entries
+ * - load: Load todos from session on startup
+ * - rebuildFromBranch: Restore todos when navigating session tree
+ */
+export interface TodoStoreOptions {
+    /**
+     * Persist todos to storage
+     * Called whenever todos are updated
+     */
+    persist?: (todos: TodoItem[]) => void;
+    /**
+     * Load todos from storage
+     * Called on TodoStore construction
+     */
+    load?: () => TodoItem[];
+    /**
+     * Rebuild todos from session branch
+     * Called when navigating the session tree
+     */
+    rebuildFromBranch?: () => TodoItem[];
+    /**
+     * Callback when todos change
+     * Useful for triggering UI updates
+     */
+    onChange?: (todos: TodoItem[]) => void;
+}
+/**
+ * Session manager interface for type safety
+ * The coding-agent's SessionManager implements this
+ */
+export interface TodoSessionManager {
+    appendCustomEntry(type: string, data: unknown): void;
+    getBranch(): Array<{
+        type?: string;
+        customType?: string;
+        data?: unknown;
+    }>;
+}

package/dist/types/facade/bot/actions/todo.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Todo Tools - Read and write todo lists
+ *
+ * @module agent/tools/todo
+ * @description
+ * Provides tools for managing todo lists. The todos are stored in a TodoStore
+ * which can optionally persist to external storage (e.g., session entries).
+ *
+ * ## Architecture
+ *
+ * Two tools are provided:
+ * - `todoread`: Read the current todo list
+ * - `todowrite`: Update the todo list
+ *
+ * Both tools share the same TodoStore instance for consistency.
+ *
+ * ## Usage
+ *
+ * ### Simple mode
+ * ```typescript
+ * import { todoReadTool, todoWriteTool } from "indusvx/agent";
+ * // Uses default in-memory store
+ * ```
+ *
+ * ### With custom store (persistent mode)
+ * ```typescript
+ * import { createTodoReadTool, createTodoWriteTool, TodoStore } from "indusvx/agent";
+ *
+ * const store = new TodoStore({
+ *   persist: (todos) => sessionManager.appendCustomEntry('todo', { todos }),
+ *   load: () => loadFromSession(),
+ * });
+ *
+ * const todoReadTool = createTodoReadTool(store);
+ * const todoWriteTool = createTodoWriteTool(store);
+ * ```
+ */
+import type { AgentTool } from "../types.js";
+import { TodoStore } from "./todo-store.js";
+import type { TodoToolDetails } from "./todo-types.js";
+export type { TodoItem, TodoStatus, TodoPriority, TodoStoreOptions, TodoToolDetails } from "./todo-types.js";
+export { TodoStore, TODO_PRIORITIES, TODO_STATUSES } from "./todo-store.js";
+declare const TodoReadSchema: import("@sinclair/typebox").TObject<{}>;
+declare const TodoWriteSchema: import("@sinclair/typebox").TObject<{
+    todos: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        content: import("@sinclair/typebox").TString;
+        status: import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">;
+        priority: import("@sinclair/typebox").TUnsafe<"low" | "medium" | "high">;
+    }>>;
+    search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">>;
+}>;
+/**
+ * Create a todo read tool
+ * @param store - The TodoStore to read from
+ * @returns The todoread tool
+ */
+export declare function createTodoReadTool(store: TodoStore): AgentTool<typeof TodoReadSchema, TodoToolDetails>;
+/**
+ * Create a todo write tool
+ * @param store - The TodoStore to write to
+ * @returns The todowrite tool
+ */
+export declare function createTodoWriteTool(store: TodoStore): AgentTool<typeof TodoWriteSchema, TodoToolDetails>;
+/** Default todo read tool using in-memory store */
+export declare const todoReadTool: AgentTool<import("@sinclair/typebox").TObject<{}>, TodoToolDetails>;
+/** Default todo write tool using in-memory store */
+export declare const todoWriteTool: AgentTool<import("@sinclair/typebox").TObject<{
+    todos: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        content: import("@sinclair/typebox").TString;
+        status: import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">;
+        priority: import("@sinclair/typebox").TUnsafe<"low" | "medium" | "high">;
+    }>>;
+    search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"completed" | "cancelled" | "pending" | "in_progress">>;
+}>, TodoToolDetails>;

package/dist/types/facade/bot/actions/truncate.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Routines that trim oversized tool output before it reaches the model.
+ *
+ * Two separate ceilings are checked at once, and trimming kicks in the moment
+ * either is reached:
+ *   - a maximum count of lines that may be returned (2500 by default)
+ *   - a maximum count of bytes that may be returned (64KB by default)
+ *
+ * Trims occur at line breaks, so output is never left holding a partial line.
+ * The single exception is when trimming from the tail: should the very last line
+ * by itself blow past the byte ceiling, that line gets cut mid-way.
+ */
+export declare const DEFAULT_MAX_LINES = 2500;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const GREP_MAX_LINE_LENGTH = 512;
+export interface TruncationResult {
+    /** Final text once the budgets have been enforced. */
+    content: string;
+    /** Whether any budget actually forced something to be dropped. */
+    truncated: boolean;
+    /** Which budget caused the cut, or null if everything fit. */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Number of lines the original input had prior to any trimming. */
+    totalLines: number;
+    /** Number of bytes the original input had prior to any trimming. */
+    totalBytes: number;
+    /** How many complete lines survived into the result. */
+    outputLines: number;
+    /** How many bytes the result occupies. */
+    outputBytes: number;
+    /** Set only in the tail case where the closing line had to be cut mid-line. */
+    lastLinePartial: boolean;
+    /** Set when even the leading line by itself blows past the byte budget (head case). */
+    firstLineExceedsLimit: boolean;
+    /** The active line budget. */
+    maxLines: number;
+    /** The active byte budget. */
+    maxBytes: number;
+}
+export interface TruncationOptions {
+    /** Custom line budget; defaults to 2500 when omitted. */
+    maxLines?: number;
+    /** Custom byte budget; defaults to 64KB when omitted. */
+    maxBytes?: number;
+}
+export interface TruncationStrategy {
+    truncate(content: string, options?: TruncationOptions): TruncationResult;
+}
+/**
+ * Render a raw byte count as a compact label a person can read at a glance,
+ * picking B, KB, or MB depending on magnitude.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Retain the leading slice of the content (its first lines/bytes) and discard
+ * what follows. Suited to reading files, where the beginning is most relevant.
+ *
+ * Whole lines are preserved. Should the opening line on its own exceed the byte
+ * budget, an empty result is returned with firstLineExceedsLimit set.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Retain the trailing slice of the content (its last lines/bytes) and discard
+ * what precedes it. Suited to command output, where errors and results land at
+ * the end.
+ *
+ * When the closing line by itself overshoots the byte budget, the returned text
+ * can start partway through that line.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Shorten one line to a character budget, tacking on a marker if it was cut.
+ * Used on search hits whose lines would otherwise run too long.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};

package/dist/types/facade/bot/actions/webfetch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Web Fetch Tool
+ *
+ * Fetches content from a specified URL.
+ * Supports text, markdown, and HTML format options.
+ */
+import type { AgentTool } from "../types.js";
+declare const webFetchSchema: import("@sinclair/typebox").TObject<{
+    url: import("@sinclair/typebox").TString;
+    format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"markdown">, import("@sinclair/typebox").TLiteral<"html">]>>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface WebFetchToolDetails {
+    url: string;
+    format?: "text" | "markdown" | "html";
+    timeout?: number;
+    contentType?: string;
+    fetchedBytes?: number;
+}
+export interface WebFetchToolOptions {
+    /** Maximum response size in bytes (default: 5MB) */
+    maxResponseSize?: number;
+    /** Default timeout in milliseconds (default: 30000) */
+    defaultTimeout?: number;
+    /** Optional proxy base URL that forwards target URL via ?url= */
+    proxyUrl?: string;
+}
+export declare function createWebFetchTool(options?: WebFetchToolOptions): AgentTool<typeof webFetchSchema>;
+/** Default web fetch tool */
+export declare const webFetchTool: AgentTool<import("@sinclair/typebox").TObject<{
+    url: import("@sinclair/typebox").TString;
+    format: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"text">, import("@sinclair/typebox").TLiteral<"markdown">, import("@sinclair/typebox").TLiteral<"html">]>>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/websearch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Web Search Tool
+ *
+ * Performs real-time web searches using DuckDuckGo API.
+ * Provides up-to-date information for current events and recent data.
+ */
+import type { AgentTool } from "../types.js";
+declare const webSearchSchema: import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    numResults: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface WebSearchToolDetails {
+    query: string;
+    numResults?: number;
+}
+export interface WebSearchToolOptions {
+    /** Custom API base URL (for testing or alternative endpoints) */
+    baseUrl?: string;
+    /** API key for Exa AI (if required) */
+    apiKey?: string;
+    /** Max requests per process window */
+    rateLimitPerMinute?: number;
+    /** Optional result filtering hook */
+    filterResult?: (raw: string) => string;
+    /** Optional fallback implementation */
+    fallbackSearch?: (query: string, numResults?: number, signal?: AbortSignal) => Promise<string>;
+}
+export declare function createWebSearchTool(options?: WebSearchToolOptions): AgentTool<typeof webSearchSchema>;
+/** Default web search tool */
+export declare const webSearchTool: AgentTool<import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    numResults: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/write.d.ts

@@ -0,0 +1,30 @@
+import type { AgentTool } from "../types.js";
+declare const writeSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    content: import("@sinclair/typebox").TString;
+}>;
+/**
+ * Pluggable filesystem callbacks for the write tool. Override them to direct
+ * writes at an alternate backend, for instance an SSH or remote-mount layer.
+ */
+export interface WriteOperations {
+    /** Write text out to a file. */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Make sure a directory is present, building any missing parents along the way. */
+    mkdir: (dir: string) => Promise<void>;
+    /** Optional callback for taking a snapshot of a file ahead of overwriting it. */
+    copyFile?: (from: string, to: string) => Promise<void>;
+}
+export interface WriteToolOptions {
+    /** Swap out the filesystem callbacks; the local disk is used by default. */
+    operations?: WriteOperations;
+    /** If set, duplicate any existing file to a sibling .bak before it is overwritten. */
+    createBackup?: boolean;
+}
+export declare function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema>;
+/** Ready-to-use write tool bound to the current working directory. */
+export declare const writeTool: AgentTool<import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    content: import("@sinclair/typebox").TString;
+}>, any>;
+export {};

package/dist/types/facade/bot/agent-loop.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The engine that runs the agent's turn cycle.
+ *
+ * Throughout this module the conversation is carried as AgentMessage values.
+ * They are only flattened into the provider's Message[] representation at the
+ * last possible moment — immediately before a model call inside
+ * streamAssistantResponse — and never anywhere else.
+ */
+import { EventStream } from "../ml/index.js";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+/**
+ * Begin a brand-new run. The supplied prompt messages are appended to the
+ * conversation up front, then the turn cycle starts.
+ */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Pick a run back up from wherever the context currently sits, without adding
+ * any new prompt messages.
+ */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;

package/dist/types/facade/bot/agent.d.ts

@@ -0,0 +1,132 @@
+/**
+ * High-level Agent wrapper around the streaming loop. It keeps the mutable run
+ * state, exposes the public prompt/steer/follow-up surface, and forwards work to
+ * the loop functions directly. There is no transport indirection here: by
+ * default the model is reached through streamSimple.
+ */
+import { type ImageContent, type Message, type Model, type ThinkingBudgets } from "../ml/index.js";
+import type { AgentEvent, AgentMessage, AgentState, AgentTool, StreamFn, ThinkingLevel } from "./types.js";
+type QueueMode = "all" | "one-at-a-time";
+export interface AgentOptions {
+    initialState?: Partial<AgentState>;
+    /**
+     * Hook that maps the agent's AgentMessage[] onto the provider-facing
+     * Message[] right before every model call. When omitted, the built-in
+     * reducer keeps only user/assistant/toolResult messages and converts
+     * attachments.
+     */
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Runs ahead of convertToLlm and may rewrite the message list — handy for
+     * trimming long histories or splicing in extra context.
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * How queued steering messages are released: "all" flushes the whole queue
+     * in one go, "one-at-a-time" releases a single message per turn.
+     */
+    steeringMode?: QueueMode;
+    /**
+     * How queued follow-up messages are released: "all" flushes the whole queue
+     * in one go, "one-at-a-time" releases a single message per turn.
+     */
+    followUpMode?: QueueMode;
+    /**
+     * Swap in an alternative streaming implementation — e.g. a remote proxy
+     * backend. Falls back to streamSimple when not provided.
+     */
+    streamFn?: StreamFn;
+    /**
+     * Stable identifier passed through to providers that key their server-side
+     * caches on a session, so repeated turns can reuse prior context.
+     */
+    sessionId?: string;
+    /**
+     * Supplies a fresh API key per call. Useful when credentials rotate or
+     * expire, such as short-lived OAuth access tokens.
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Per-level token allowances for thinking; only meaningful for providers
+     * whose reasoning effort is expressed as a token budget.
+     */
+    thinkingBudgets?: ThinkingBudgets;
+}
+export declare class Agent {
+    private _state;
+    private readonly eventBus;
+    private readonly stateManager;
+    private readonly queuePolicy;
+    private abortController?;
+    private convertToLlm;
+    private transformContext?;
+    streamFn: StreamFn;
+    private _sessionId?;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    private runningPrompt?;
+    private resolveRunningPrompt?;
+    private _thinkingBudgets?;
+    constructor(opts?: AgentOptions);
+    /**
+     * The session identifier currently forwarded to providers for caching.
+     */
+    get sessionId(): string | undefined;
+    /**
+     * Update the provider-caching session identifier. Set a new value whenever
+     * the conversation changes identity — a brand-new session, a branch, or a
+     * resumed run.
+     */
+    set sessionId(value: string | undefined);
+    /**
+     * The thinking-level token budgets currently in effect, if any.
+     */
+    get thinkingBudgets(): ThinkingBudgets | undefined;
+    /**
+     * Override the thinking-level token budgets for providers that meter
+     * reasoning by token count.
+     */
+    set thinkingBudgets(value: ThinkingBudgets | undefined);
+    get state(): AgentState;
+    subscribe(fn: (e: AgentEvent) => void): () => void;
+    setSystemPrompt(v: string): void;
+    setModel(m: Model<any>): void;
+    setThinkingLevel(l: ThinkingLevel): void;
+    setSteeringMode(mode: QueueMode): void;
+    getSteeringMode(): QueueMode;
+    setFollowUpMode(mode: QueueMode): void;
+    getFollowUpMode(): QueueMode;
+    setTools(t: AgentTool<any>[]): void;
+    replaceMessages(ms: AgentMessage[]): void;
+    appendMessage(m: AgentMessage): void;
+    /**
+     * Enqueue a steering message to redirect the agent while it is running. It
+     * lands once the in-flight tool finishes and causes any still-pending tool
+     * calls in that turn to be skipped.
+     */
+    steer(m: AgentMessage): void;
+    /**
+     * Enqueue a follow-up message that is held back until the agent has gone
+     * idle — i.e. there are no outstanding tool calls and no steering left to
+     * process.
+     */
+    followUp(m: AgentMessage): void;
+    clearSteeringQueue(): void;
+    clearFollowUpQueue(): void;
+    clearAllQueues(): void;
+    clearMessages(): void;
+    abort(): void;
+    waitForIdle(): Promise<void>;
+    reset(): void;
+    /** Submit a new prompt, given either raw text or one or more AgentMessages. */
+    prompt(message: AgentMessage | AgentMessage[]): Promise<void>;
+    prompt(input: string, images?: ImageContent[]): Promise<void>;
+    /** Resume the existing conversation, e.g. to retry after a context overflow. */
+    continue(): Promise<void>;
+    /**
+     * Core driver for a run. Passing a messages array opens a new turn seeded
+     * with them; passing nothing resumes the conversation already in state.
+     */
+    private _runLoop;
+    private emit;
+}
+export {};

package/dist/types/facade/bot/error-handler.d.ts

@@ -0,0 +1,7 @@
+export interface AgentErrorContext {
+    phase: "llm_stream" | "tool_execution" | "steering" | "unknown";
+    toolName?: string;
+}
+export declare class AgentErrorHandler {
+    handle(error: unknown, context: AgentErrorContext): Error;
+}

package/dist/types/facade/bot/event-bus.d.ts

@@ -0,0 +1,8 @@
+import type { AgentEvent } from "./types.js";
+export type AgentEventListener = (event: AgentEvent) => void;
+export declare class AgentEventBus {
+    private listeners;
+    subscribe(listener: AgentEventListener): () => void;
+    emit(event: AgentEvent): void;
+    clear(): void;
+}

package/dist/types/facade/bot/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./agent.js";
+export * from "./agent-loop.js";
+export * from "./proxy.js";
+export * from "./types.js";
+export * from "./actions/index.js";
+export * from "./messages.js";
+export * from "./session-manager.js";