@sschepis/oboto-agent 0.1.4 → 0.2.1

package/dist/index.d.ts

@@ -1,14 +1,22 @@
-import { Session, ConversationMessage } from '@sschepis/as-agent';
-import { BaseProvider } from '@sschepis/llm-wrapper';
-import { Router, BranchNode } from '@sschepis/swiss-army-tool';
+import * as _sschepis_as_agent from '@sschepis/as-agent';
+import { Session, PermissionPolicy, PermissionPrompter, CompactionConfig, HookRunner, AgentRuntime, ConversationMessage, UsageTracker, TokenUsage, HookRunResult, SlashCommandSpec, PermissionOutcome, PermissionMode, CompactionResult, UsageCostEstimate, ModelPricing as ModelPricing$1 } from '@sschepis/as-agent';
+import * as _sschepis_llm_wrapper from '@sschepis/llm-wrapper';
+import { BaseProvider, LLMRouter, HealthState, StandardChatParams } from '@sschepis/llm-wrapper';
+import { Router, Middleware, BranchNode, DynamicBranchNode, SessionManager } from '@sschepis/swiss-army-tool';
+import { MiddlewareHooks, ModelPricing, BudgetConfig, RateLimitConfig, EmbeddingProvider, VectorStore, VectorSearchResult, LScriptRuntime, LScriptFunction, ExecutionResult, RAGPipeline, CostTracker, ToolDefinition, ChatMessage, LLMProvider, Pipeline, PipelineResult } from '@sschepis/lmscript';
+import * as zod from 'zod';
 import { z } from 'zod';
-import { ToolDefinition, ChatMessage, LLMProvider, LScriptRuntime, LScriptFunction } from '@sschepis/lmscript';
 
+/**
+ * A provider-like object that has `chat()` and `stream()` methods.
+ * Accepts both llm-wrapper `BaseProvider` and `LLMRouter`.
+ */
+type ProviderLike$1 = BaseProvider | LLMRouter;
 interface ObotoAgentConfig {
     /** Small, fast model for triage and summarization (e.g. Ollama, LMStudio) */
-    localModel: BaseProvider;
+    localModel: ProviderLike$1;
     /** Powerful model for complex reasoning (e.g. Anthropic, OpenAI, Gemini) */
-    remoteModel: BaseProvider;
+    remoteModel: ProviderLike$1;
     /** Model identifier for the local provider (e.g. "llama3:8b") */
     localModelName: string;
     /** Model identifier for the remote provider (e.g. "claude-sonnet-4-20250514") */
@@ -25,8 +33,48 @@ interface ObotoAgentConfig {
     systemPrompt?: string;
     /** Called with each token chunk during LLM streaming. Enables real-time output. */
     onToken?: (token: string) => void;
+    /** Middleware hooks for the lmscript execution lifecycle */
+    middleware?: MiddlewareHooks[];
+    /** Model pricing map for cost tracking (model name -> per-1k-token costs) */
+    modelPricing?: ModelPricing;
+    /** Budget limits for the remote runtime */
+    budget?: BudgetConfig;
+    /** Rate limiting configuration for remote API calls */
+    rateLimit?: RateLimitConfig;
+    /** TTL in ms for execution cache. 0 or undefined disables caching. Default: 0 */
+    cacheTtlMs?: number;
+    /** TTL in ms for triage cache. Separate from main cache. Default: 60000 */
+    triageCacheTtlMs?: number;
+    /** Middleware to apply to the swiss-army-tool Router */
+    toolMiddleware?: Middleware[];
+    /** Embedding provider for RAG-augmented conversation retrieval */
+    embeddingProvider?: EmbeddingProvider;
+    /** Custom vector store for RAG. Defaults to MemoryVectorStore. */
+    vectorStore?: VectorStore;
+    /** Number of past context chunks to retrieve via RAG. Default: 5 */
+    ragTopK?: number;
+    /** Minimum similarity score for RAG retrieval (0-1). Default: 0.3 */
+    ragMinScore?: number;
+    /** Embedding model identifier for RAG. Default: provider's default */
+    ragEmbeddingModel?: string;
+    /** Whether to automatically index conversation messages for RAG. Default: true */
+    ragAutoIndex?: boolean;
+    /** Whether to index tool execution results for RAG. Default: true */
+    ragIndexToolResults?: boolean;
+    /** Custom formatter for RAG-retrieved context */
+    ragFormatContext?: (results: VectorSearchResult[]) => string;
+    /** Permission policy for tool authorization (from @sschepis/as-agent) */
+    permissionPolicy?: PermissionPolicy;
+    /** Permission prompter for interactive permission decisions */
+    permissionPrompter?: PermissionPrompter;
+    /** Session compaction config — auto-compact when estimated tokens exceed limit */
+    compactionConfig?: CompactionConfig;
+    /** Hook runner for pre/post tool-use shell hooks */
+    hookRunner?: HookRunner;
+    /** as-agent Wasm runtime for slash commands and utilities */
+    agentRuntime?: AgentRuntime;
 }
-type AgentEventType = "user_input" | "agent_thought" | "token" | "triage_result" | "tool_execution_start" | "tool_execution_complete" | "tool_round_complete" | "state_updated" | "interruption" | "error" | "turn_complete";
+type AgentEventType = "user_input" | "agent_thought" | "token" | "triage_result" | "tool_execution_start" | "tool_execution_complete" | "tool_round_complete" | "state_updated" | "interruption" | "error" | "cost_update" | "turn_complete" | "permission_denied" | "session_compacted" | "hook_denied" | "hook_message" | "router_event" | "slash_command";
 interface AgentEvent<T = unknown> {
     type: AgentEventType;
     payload: T;
@@ -48,21 +96,555 @@ interface ToolExecutionEvent {
     durationMs?: number;
 }
 
+interface ConversationRAGConfig {
+    /** The embedding provider (e.g. OpenAI, local model) */
+    embeddingProvider: EmbeddingProvider;
+    /** Optional custom vector store. Defaults to MemoryVectorStore. */
+    vectorStore?: VectorStore;
+    /** Number of past context chunks to retrieve. Default: 5 */
+    topK?: number;
+    /** Minimum similarity score (0-1). Default: 0.3 */
+    minScore?: number;
+    /** Embedding model identifier. Default: provider's default */
+    embeddingModel?: string;
+    /**
+     * Whether to automatically index conversation messages as they're added.
+     * Default: true
+     */
+    autoIndex?: boolean;
+    /**
+     * Whether to index tool execution results.
+     * Default: true
+     */
+    indexToolResults?: boolean;
+    /** Maximum characters per indexed chunk. Longer messages are split. Default: 2000 */
+    maxChunkSize?: number;
+    /**
+     * Custom context formatter for retrieved documents.
+     * Default: numbered list with scores.
+     */
+    formatContext?: (results: VectorSearchResult[]) => string;
+}
+interface RAGRetrievalResult {
+    /** Retrieved context string ready for prompt injection */
+    context: string;
+    /** Raw search results */
+    results: VectorSearchResult[];
+    /** Number of documents in the store */
+    totalDocuments: number;
+}
+/**
+ * ConversationRAG bridges lmscript's RAG pipeline with the agent's
+ * conversation history and tool results.
+ *
+ * It maintains a vector store of conversation chunks and can retrieve
+ * relevant past context for new queries. This is useful for:
+ * - Long-running agent sessions where early context is pruned
+ * - Multi-topic conversations where relevant past decisions need retrieval
+ * - Tool result recall without re-execution
+ *
+ * ```ts
+ * const rag = new ConversationRAG(runtime, {
+ *   embeddingProvider: openaiEmbeddings,
+ *   topK: 5,
+ *   minScore: 0.3,
+ * });
+ *
+ * // Index existing session history
+ * await rag.indexSession(session);
+ *
+ * // Retrieve relevant context for a new query
+ * const { context } = await rag.retrieve("What database schema did we discuss?");
+ *
+ * // Or use RAG-augmented execution directly
+ * const result = await rag.executeWithContext(myFn, input, "search query");
+ * ```
+ */
+declare class ConversationRAG {
+    private vectorStore;
+    private embeddingProvider;
+    private ragPipeline;
+    private config;
+    private indexedMessageCount;
+    private runtime;
+    constructor(runtime: LScriptRuntime, config: ConversationRAGConfig);
+    /**
+     * Index an entire as-agent Session into the vector store.
+     * Each message becomes one or more chunks (split by maxChunkSize).
+     */
+    indexSession(session: Session): Promise<number>;
+    /**
+     * Index a single conversation message.
+     * Call this after adding a message to the session for real-time indexing.
+     */
+    indexMessage(msg: ConversationMessage, messageIndex?: number): Promise<void>;
+    /**
+     * Index a tool execution result for later retrieval.
+     */
+    indexToolResult(command: string, kwargs: Record<string, unknown>, result: string): Promise<void>;
+    /**
+     * Retrieve relevant past context for a query.
+     * Returns formatted context string and raw results.
+     */
+    retrieve(query: string): Promise<RAGRetrievalResult>;
+    /**
+     * Execute an lmscript function with RAG-augmented context from the
+     * conversation history.
+     *
+     * This is the primary integration point — it uses lmscript's RAGPipeline
+     * to inject relevant past conversation into the function's system prompt.
+     */
+    executeWithContext<I, O extends zod.ZodType>(fn: LScriptFunction<I, O>, input: I, queryText?: string): Promise<{
+        result: ExecutionResult<zod.infer<O>>;
+        retrievedDocuments: VectorSearchResult[];
+        context: string;
+    }>;
+    /** Get the number of indexed messages. */
+    get messageCount(): number;
+    /** Get the total number of document chunks in the vector store. */
+    documentCount(): Promise<number>;
+    /** Clear the vector store and reset counters. */
+    clear(): Promise<void>;
+    /** Get the underlying vector store (for advanced usage). */
+    getVectorStore(): VectorStore;
+    /** Get the underlying RAG pipeline (for advanced usage). */
+    getRagPipeline(): RAGPipeline;
+    private messageToChunks;
+    private splitChunks;
+}
+
 type EventHandler$1 = (event: AgentEvent) => void;
+/**
+ * Platform-agnostic typed event bus.
+ * Uses a plain Map instead of Node.js EventEmitter for browser/Deno/Bun compatibility.
+ */
+declare class AgentEventBus {
+    private listeners;
+    /** Subscribe to an event type. Returns an unsubscribe function. */
+    on(type: AgentEventType, handler: EventHandler$1): () => void;
+    /** Unsubscribe a handler from an event type. */
+    off(type: AgentEventType, handler: EventHandler$1): void;
+    /** Subscribe to an event type for a single emission. */
+    once(type: AgentEventType, handler: EventHandler$1): () => void;
+    /** Emit an event to all subscribers. */
+    emit(type: AgentEventType, payload: unknown): void;
+    /** Remove all listeners for all event types. */
+    removeAllListeners(): void;
+}
+
+/**
+ * as-agent-features.ts — Deep integration of @sschepis/as-agent's advanced features.
+ *
+ * This module bridges the following as-agent subsystems into oboto-agent:
+ *
+ * 1. **Permissions** — PermissionPolicy + PermissionPrompter for tool authorization
+ * 2. **Session Compaction** — CompactionConfig for auto-compacting long sessions
+ * 3. **Hooks** — HookRunner for pre/post tool-use shell hooks
+ * 4. **Slash Commands** — AgentRuntime's slash command registry
+ * 5. **Usage Tracking** — UsageTracker bridge (detailed impl in Task 11)
+ */
+
+/**
+ * Wraps an as-agent PermissionPolicy to provide tool-call authorization
+ * that integrates with the agent's event bus.
+ *
+ * Before each tool execution, `authorize()` is called. If the policy
+ * denies the call, a `permission_denied` event is emitted and the tool
+ * execution is skipped.
+ *
+ * ```ts
+ * const guard = new PermissionGuard(policy, prompter, bus);
+ * const outcome = guard.checkPermission("bash", '{"cmd":"rm -rf /"}');
+ * if (outcome.kind === "deny") { ... }
+ * ```
+ */
+declare class PermissionGuard {
+    private policy;
+    private prompter;
+    private bus?;
+    constructor(policy: PermissionPolicy, prompter: PermissionPrompter | null, bus?: AgentEventBus | undefined);
+    /**
+     * Check whether a tool call is authorized.
+     * Emits `permission_denied` on the event bus if denied.
+     */
+    checkPermission(toolName: string, toolInput: string): PermissionOutcome;
+    /** Get the current active permission mode. */
+    get activeMode(): PermissionMode;
+    /** Get the required permission mode for a specific tool. */
+    requiredModeFor(toolName: string): PermissionMode;
+}
+/**
+ * Manages automatic and manual session compaction using as-agent's
+ * CompactionConfig. Compaction summarizes older messages to stay within
+ * token limits while preserving recent context.
+ *
+ * ```ts
+ * const compactor = new SessionCompactor(bus, {
+ *   preserveRecentMessages: 10,
+ *   maxEstimatedTokens: 100_000,
+ * });
+ *
+ * // Check and compact if needed
+ * const result = compactor.compactIfNeeded(session, estimatedTokens);
+ * ```
+ */
+declare class SessionCompactor {
+    private config;
+    private bus?;
+    private compactionCount;
+    private totalRemovedMessages;
+    constructor(bus: AgentEventBus | undefined, config: CompactionConfig);
+    /**
+     * Check if the session needs compaction and perform it if so.
+     * Uses a simple heuristic: ~4 chars per token for estimation.
+     *
+     * Since the actual compaction logic lives in the Wasm runtime
+     * (ConversationRuntime.compact()), this method provides a JS-side
+     * implementation that creates a summary of older messages and
+     * preserves recent ones.
+     *
+     * Returns null if compaction is not needed.
+     */
+    compactIfNeeded(session: Session, estimatedTokens?: number): CompactionResult | null;
+    /**
+     * Force compaction of the session regardless of token count.
+     */
+    compact(session: Session): CompactionResult;
+    /** Get compaction statistics. */
+    get stats(): {
+        compactionCount: number;
+        totalRemovedMessages: number;
+    };
+    /** Update the compaction config at runtime. */
+    updateConfig(config: Partial<CompactionConfig>): void;
+    /** Estimate token count for a session (~4 chars per token). */
+    private estimateTokens;
+}
+/**
+ * Wraps an as-agent HookRunner and integrates it with the agent's
+ * event bus. Hooks are shell commands that run before and after
+ * tool executions, allowing external validation/transformation.
+ *
+ * ```ts
+ * const hooks = new HookIntegration(hookRunner, bus);
+ * const pre = hooks.runPreToolUse("bash", '{"cmd":"ls"}');
+ * if (pre.denied) { /* skip tool call *\/ }
+ *
+ * // After tool executes:
+ * const post = hooks.runPostToolUse("bash", '{"cmd":"ls"}', "file1\nfile2", false);
+ * ```
+ */
+declare class HookIntegration {
+    private runner;
+    private bus?;
+    constructor(runner: HookRunner, bus?: AgentEventBus | undefined);
+    /**
+     * Run pre-tool-use hooks. If any hook denies the call,
+     * the tool execution should be skipped.
+     */
+    runPreToolUse(toolName: string, toolInput: string): HookRunResult;
+    /**
+     * Run post-tool-use hooks. These can log, transform, or audit
+     * tool results but cannot retroactively deny execution.
+     */
+    runPostToolUse(toolName: string, toolInput: string, toolOutput: string, isError: boolean): HookRunResult;
+}
+/**
+ * Bridges the as-agent Wasm runtime's slash command system with
+ * oboto-agent. The Wasm runtime provides 21 built-in slash commands
+ * (e.g. /help, /compact, /clear, /model, etc.).
+ *
+ * This class provides:
+ * - Access to command specs and help text from the Wasm runtime
+ * - An extensible registry for adding custom slash commands
+ * - Parsing and dispatching of slash command input
+ *
+ * ```ts
+ * const registry = new SlashCommandRegistry(agentRuntime);
+ * const specs = registry.getCommandSpecs();
+ * const help = registry.getHelpText();
+ *
+ * // Add custom commands
+ * registry.registerCommand({
+ *   name: "status",
+ *   summary: "Show agent status",
+ *   argumentHint: "",
+ *   resumeSupported: false,
+ * }, async (args) => "Agent is running");
+ * ```
+ */
+declare class SlashCommandRegistry {
+    private customCommands;
+    private wasmRuntime?;
+    constructor(wasmRuntime?: AgentRuntime);
+    /**
+     * Get all slash command specs (built-in from Wasm + custom).
+     */
+    getCommandSpecs(): SlashCommandSpec[];
+    /**
+     * Get the full help text for all commands.
+     * Uses the Wasm runtime's formatted help if available.
+     */
+    getHelpText(): string;
+    /**
+     * Register a custom slash command.
+     */
+    registerCommand(spec: SlashCommandSpec, handler: (args: string) => string | Promise<string>): void;
+    /**
+     * Unregister a custom slash command.
+     */
+    unregisterCommand(name: string): boolean;
+    /**
+     * Parse a user input string to check if it's a slash command.
+     * Returns the command name and arguments, or null if not a command.
+     */
+    parseCommand(input: string): {
+        name: string;
+        args: string;
+    } | null;
+    /**
+     * Execute a custom slash command by name.
+     * Returns the command output, or null if the command is not found
+     * in the custom registry (it may be a built-in Wasm command).
+     */
+    executeCustomCommand(name: string, args: string): Promise<string | null>;
+    /**
+     * Check if a command name exists (either built-in or custom).
+     */
+    hasCommand(name: string): boolean;
+    /**
+     * Get only commands that support resume (useful for session restoration).
+     */
+    getResumeSupportedCommands(): SlashCommandSpec[];
+}
+/**
+ * A JS-side implementation of the as-agent UsageTracker interface.
+ * This adapter accumulates token usage across turns, matching the
+ * as-agent contract (inputTokens, outputTokens, cache tokens).
+ *
+ * The bridge to lmscript's CostTracker (which uses different field names)
+ * is handled in Task 11.
+ */
+declare class AgentUsageTracker implements UsageTracker {
+    private turnUsages;
+    private currentTurn;
+    record(usage: TokenUsage): void;
+    currentTurnUsage(): TokenUsage;
+    cumulativeUsage(): TokenUsage;
+    turns(): number;
+    /**
+     * Finalize the current turn and start a new one.
+     * Call this at the end of each agent turn.
+     */
+    endTurn(): void;
+    /** Reset all usage data. */
+    reset(): void;
+    private hasTurnActivity;
+}
+
+/**
+ * router-events.ts — Bridge LLMRouter health/failover events into the agent event bus.
+ *
+ * The LLMRouter (from @sschepis/llm-wrapper) exposes a `RouterEventEmitter` that
+ * fires typed events for routing decisions, fallbacks, circuit breaker state changes,
+ * and request completions/errors.
+ *
+ * This module:
+ * 1. Subscribes to all LLMRouter events
+ * 2. Forwards them to the agent's AgentEventBus as `router_event` events
+ * 3. Provides a health snapshot method for observability
+ */
+
+/**
+ * Bridge that forwards LLMRouter events to the agent event bus.
+ *
+ * Usage:
+ * ```ts
+ * const bridge = new RouterEventBridge(bus);
+ * bridge.attach(localRouter, "local");
+ * bridge.attach(remoteRouter, "remote");
+ *
+ * // Later, get a health snapshot
+ * const health = bridge.getHealthSnapshot();
+ * ```
+ */
+declare class RouterEventBridge {
+    private bus;
+    private attachedRouters;
+    constructor(bus: AgentEventBus);
+    /**
+     * Attach an LLMRouter and forward all its events to the agent bus.
+     *
+     * @param router - The LLMRouter to monitor
+     * @param label - A label to identify this router in events (e.g. "local", "remote")
+     */
+    attach(router: LLMRouter, label: string): void;
+    /**
+     * Detach a previously attached router.
+     */
+    detach(label: string): void;
+    /**
+     * Detach all attached routers.
+     */
+    detachAll(): void;
+    /**
+     * Get a health snapshot from all attached routers.
+     * Returns a map of router label -> endpoint name -> HealthState.
+     */
+    getHealthSnapshot(): Map<string, Map<string, HealthState>>;
+    /**
+     * Check if any attached router has an endpoint in "open" (tripped) circuit state.
+     */
+    hasTrippedCircuits(): boolean;
+    /**
+     * Get the labels of all attached routers.
+     */
+    get labels(): string[];
+}
+/**
+ * Helper to check if a ProviderLike is an LLMRouter (has `events` property).
+ */
+declare function isLLMRouter(provider: unknown): provider is LLMRouter;
+
+/**
+ * usage-bridge.ts — Bidirectional bridge between as-agent's UsageTracker
+ * and lmscript's CostTracker.
+ *
+ * Field mapping:
+ *   as-agent                      lmscript
+ *   ─────────                     ────────
+ *   inputTokens              →    promptTokens
+ *   outputTokens             →    completionTokens
+ *   cacheCreationInputTokens →    (no equivalent, tracked separately)
+ *   cacheReadInputTokens     →    (no equivalent, tracked separately)
+ *   (sum of all)             →    totalTokens
+ *
+ * The bridge records every usage event into both systems, ensuring
+ * unified cost accounting regardless of which subsystem reports usage.
+ */
+
+/**
+ * Convert as-agent TokenUsage to lmscript usage format.
+ */
+declare function asTokenUsageToLmscript(usage: TokenUsage): {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+/**
+ * Convert lmscript usage format to as-agent TokenUsage.
+ * Cache tokens default to 0 since lmscript doesn't track them separately.
+ */
+declare function lmscriptToAsTokenUsage(usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}): TokenUsage;
+/**
+ * Estimate costs using as-agent's ModelPricing (per-million-token pricing).
+ */
+declare function estimateCostFromAsAgent(usage: TokenUsage, pricing: ModelPricing$1): UsageCostEstimate;
+/**
+ * Bidirectional bridge that keeps an as-agent UsageTracker and an
+ * lmscript CostTracker in sync.
+ *
+ * When usage is reported from either side, the bridge records it in
+ * both tracking systems.
+ *
+ * ```ts
+ * const bridge = new UsageBridge(usageTracker, costTracker);
+ *
+ * // Record from LLM response (lmscript format)
+ * bridge.recordFromLmscript("gpt-4", { promptTokens: 100, completionTokens: 50, totalTokens: 150 });
+ *
+ * // Record from API response (as-agent format)
+ * bridge.recordFromAsAgent({ inputTokens: 100, outputTokens: 50, cacheCreationInputTokens: 0, cacheReadInputTokens: 0 });
+ *
+ * // Get unified cost summary
+ * const summary = bridge.getCostSummary(lmModelPricing, asModelPricing);
+ * ```
+ */
+declare class UsageBridge {
+    private asTracker;
+    private lmTracker?;
+    constructor(asTracker: AgentUsageTracker, lmTracker?: CostTracker | undefined);
+    /**
+     * Record usage from an lmscript-format source (e.g. from the streaming path
+     * or AgentLoop result).
+     *
+     * Converts to as-agent format and records in both trackers.
+     */
+    recordFromLmscript(functionName: string, usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    }): void;
+    /**
+     * Record usage from an as-agent-format source (e.g. from ConversationRuntime
+     * or the Wasm runtime).
+     *
+     * Converts to lmscript format and records in both trackers.
+     */
+    recordFromAsAgent(usage: TokenUsage, functionName?: string): void;
+    /**
+     * End the current turn in the as-agent tracker.
+     */
+    endTurn(): void;
+    /**
+     * Get unified cost summary combining both tracking systems.
+     */
+    getCostSummary(lmPricing?: ModelPricing, asPricing?: ModelPricing$1): UnifiedCostSummary;
+    /**
+     * Reset both tracking systems.
+     */
+    reset(): void;
+    /** Get the as-agent usage tracker. */
+    getAsTracker(): AgentUsageTracker;
+    /** Get the lmscript cost tracker (if available). */
+    getLmTracker(): CostTracker | undefined;
+}
+interface UnifiedCostSummary {
+    /** as-agent's view: per-turn token counts and optional cost estimate. */
+    asAgent: {
+        usage: TokenUsage;
+        turns: number;
+        costEstimate?: UsageCostEstimate;
+    };
+    /** lmscript's view: total tokens, cost, and per-function breakdown. */
+    lmscript?: {
+        totalTokens: number;
+        totalCost: number;
+        byFunction: Record<string, {
+            calls: number;
+            totalTokens: number;
+            promptTokens: number;
+            completionTokens: number;
+        }>;
+    };
+}
+
+type EventHandler = (event: AgentEvent) => void;
 /**
  * ObotoAgent is the central orchestrator for dual-LLM agent execution.
  *
  * It binds together:
- * - llm-wrapper (LLM communication via local and remote providers)
- * - lmscript (structured/schema-validated calls for triage)
+ * - llm-wrapper (LLM communication via local and remote providers / LLMRouter)
+ * - lmscript (structured/schema-validated calls, agent loop, infrastructure)
  * - swiss-army-tool (tool execution via Router)
  * - as-agent (session state and conversation history)
  *
  * All interaction flows through an event-driven architecture.
+ *
+ * Key integration improvements (v0.2):
+ * - Accepts LLMRouter for automatic failover and health tracking
+ * - Uses lmscript's AgentLoop instead of a custom tool-calling loop
+ * - Wires lmscript infrastructure: cache, cost tracking, rate limiting, middleware
+ * - Bridges streaming via chatStream through the full lmscript stack
  */
 declare class ObotoAgent {
     private bus;
     private localRuntime;
+    private remoteRuntime;
     private localProvider;
     private remoteProvider;
     private contextManager;
@@ -75,36 +657,116 @@ declare class ObotoAgent {
     private maxIterations;
     private config;
     private onToken?;
+    private costTracker?;
+    private modelPricing?;
+    private rateLimiter?;
+    private middleware;
+    private budget?;
+    private conversationRAG?;
+    private permissionGuard?;
+    private sessionCompactor?;
+    private hookIntegration?;
+    private slashCommands;
+    private usageTracker;
+    private usageBridge;
+    private routerEventBridge;
     constructor(config: ObotoAgentConfig);
     /** Subscribe to agent events. Returns an unsubscribe function. */
-    on(type: AgentEventType, handler: EventHandler$1): () => void;
+    on(type: AgentEventType, handler: EventHandler): () => void;
     /** Subscribe to an event for a single emission. */
-    once(type: AgentEventType, handler: EventHandler$1): () => void;
+    once(type: AgentEventType, handler: EventHandler): () => void;
     /** Submit user input to the agent. Triggers the execution loop. */
     submitInput(text: string): Promise<void>;
     /**
      * Interrupt the current execution loop.
      * Optionally inject new directives into the context.
      */
-    interrupt(newDirectives?: string): void;
+    interrupt(newDirectives?: string): Promise<void>;
     /** Get the current session state. */
     getSession(): Session;
     /** Whether the agent is currently processing input. */
     get processing(): boolean;
-    /** Remove all event listeners. */
+    /** Get cost tracking summary (if cost tracking is enabled). */
+    getCostSummary(): {
+        totalCost: number;
+        totalTokens: number;
+        byFunction: Record<string, {
+            calls: number;
+            totalTokens: number;
+            promptTokens: number;
+            completionTokens: number;
+        }>;
+    } | undefined;
+    /**
+     * Get unified cost summary combining both as-agent and lmscript tracking.
+     * Uses the UsageBridge to provide a single view of all token/cost data.
+     */
+    getUnifiedCostSummary(asPricing?: _sschepis_as_agent.ModelPricing): UnifiedCostSummary;
+    /** Get the usage bridge for direct access to unified tracking. */
+    getUsageBridge(): UsageBridge;
+    /** Remove all event listeners and detach router event subscriptions. */
     removeAllListeners(): void;
+    /** Sync session and repopulate context manager (for reuse across turns). */
+    syncSession(session: Session): Promise<void>;
+    /** Update the streaming token callback between turns. */
+    setOnToken(callback: ((token: string) => void) | undefined): void;
+    /** Get the ConversationRAG instance (if RAG is enabled). */
+    getConversationRAG(): ConversationRAG | undefined;
+    /** Get the slash command registry. */
+    getSlashCommands(): SlashCommandRegistry;
+    /** Get the as-agent usage tracker. */
+    getUsageTracker(): AgentUsageTracker;
+    /** Get the permission guard (if permissions are configured). */
+    getPermissionGuard(): PermissionGuard | undefined;
+    /** Get the session compactor (if compaction is configured). */
+    getSessionCompactor(): SessionCompactor | undefined;
+    /** Get the router event bridge for observability into LLMRouter health. */
+    getRouterEventBridge(): RouterEventBridge;
+    /**
+     * Manually compact the session. Returns null if compaction is not configured.
+     */
+    compactSession(): _sschepis_as_agent.CompactionResult | null;
+    /**
+     * Retrieve relevant past context for a query via the RAG pipeline.
+     * Returns undefined if RAG is not configured.
+     */
+    retrieveContext(query: string): Promise<string | undefined>;
+    /**
+     * Record a message in the session, context manager, and optionally RAG index.
+     * Centralizes message recording to ensure RAG indexing stays in sync.
+     */
+    private recordMessage;
+    /**
+     * Record a tool execution result in the RAG index.
+     */
+    private recordToolResult;
     private executionLoop;
     private triage;
-    /** Maximum characters per tool result before truncation. */
-    private static readonly MAX_TOOL_RESULT_CHARS;
-    /** Maximum times the same tool+args can repeat before forcing a text response. */
-    private static readonly MAX_DUPLICATE_CALLS;
     /**
-     * Execute the agent loop using llm-wrapper directly.
-     * When onToken is configured, uses streaming for real-time token output.
-     * No JSON mode, no schema enforcement — just natural chat with tool calling.
+     * Execute using lmscript's AgentLoop for iterative tool calling.
+     * This replaces the old custom tool loop with lmscript's battle-tested implementation.
+     *
+     * Benefits:
+     * - Schema validation on final output
+     * - Budget checking via CostTracker
+     * - Rate limiting via RateLimiter
+     * - Middleware lifecycle hooks
+     * - Automatic retry with backoff
      */
-    private executeWithModel;
+    private executeWithAgentLoop;
+    /**
+     * Execute with streaming token emission.
+     * Uses the raw llm-wrapper provider for streaming, combined with
+     * manual tool calling (since streaming + structured agent loops are complex).
+     *
+     * This preserves real-time token delivery while still leveraging
+     * the lmscript infrastructure:
+     * - Rate limiting (acquire/reportTokens per call)
+     * - Cost tracking (trackUsage per call)
+     * - Budget checking (checkBudget before each call)
+     * - Middleware lifecycle hooks (onBeforeExecute/onComplete per turn)
+     */
+    private executeWithStreaming;
     /**
      * Stream an LLM call, emitting tokens in real-time, then aggregate into
      * a full StandardChatResponse (including accumulated tool calls).
@@ -112,25 +774,6 @@ declare class ObotoAgent {
     private streamAndAggregate;
 }
 
-type EventHandler = (event: AgentEvent) => void;
-/**
- * Platform-agnostic typed event bus.
- * Uses a plain Map instead of Node.js EventEmitter for browser/Deno/Bun compatibility.
- */
-declare class AgentEventBus {
-    private listeners;
-    /** Subscribe to an event type. Returns an unsubscribe function. */
-    on(type: AgentEventType, handler: EventHandler): () => void;
-    /** Unsubscribe a handler from an event type. */
-    off(type: AgentEventType, handler: EventHandler): void;
-    /** Subscribe to an event type for a single emission. */
-    once(type: AgentEventType, handler: EventHandler): () => void;
-    /** Emit an event to all subscribers. */
-    emit(type: AgentEventType, payload: unknown): void;
-    /** Remove all listeners for all event types. */
-    removeAllListeners(): void;
-}
-
 /** Parameter schema for the omni-tool bridge. */
 declare const RouterToolParams: z.ZodObject<{
     command: z.ZodString;
@@ -160,12 +803,323 @@ declare function sessionToHistory(session: Session): ChatMessage[];
 declare function createEmptySession(): Session;
 
 /**
- * Adapt a llm-wrapper BaseProvider into lmscript's LLMProvider interface.
+ * A provider-like object that has `chat()` and `stream()` methods.
+ * Both `BaseProvider` and `LLMRouter` implement this interface.
+ */
+type ProviderLike = {
+    chat(params: StandardChatParams): Promise<_sschepis_llm_wrapper.StandardChatResponse>;
+    stream(params: StandardChatParams): AsyncIterable<_sschepis_llm_wrapper.StandardChatChunk>;
+    readonly providerName?: string;
+};
+/**
+ * Adapt a llm-wrapper BaseProvider (or LLMRouter) into lmscript's LLMProvider interface.
  *
  * This allows lmscript's LScriptRuntime to use llm-wrapper providers for
  * structured calls (e.g. triage) that need schema validation.
+ *
+ * Bridges both `chat()` and `chatStream()` — enabling streaming through the
+ * full lmscript stack (including `executeStream()`).
+ */
+declare function toLmscriptProvider(provider: ProviderLike, name?: string): LLMProvider;
+
+/**
+ * tool-extensions.ts — Swiss-army-tool integration extensions for oboto-agent.
+ *
+ * This module provides:
+ * 1. AgentDynamicTools  — A DynamicBranchNode subclass for runtime tool discovery
+ * 2. createToolTimingMiddleware — Swiss-army-tool Middleware that emits timing events
+ * 3. createAgentToolTree — Helper to build a pre-wired tool tree with memory + dynamic tools
+ */
+
+interface DynamicToolProvider {
+    /**
+     * Called when the branch needs refreshing.
+     * Return an array of leaf node configs to populate the dynamic branch.
+     */
+    discover(): Promise<DynamicToolEntry[]> | DynamicToolEntry[];
+}
+interface DynamicToolEntry {
+    name: string;
+    description: string;
+    requiredArgs?: string[] | Record<string, {
+        type?: string;
+        description?: string;
+    }>;
+    optionalArgs?: string[] | Record<string, {
+        type?: string;
+        description?: string;
+        default?: unknown;
+    }>;
+    handler: (kwargs: Record<string, unknown>) => string | Promise<string>;
+}
+interface AgentToolTreeConfig {
+    /** Session manager for the swiss-army-tool Router */
+    session: SessionManager;
+    /** Whether to include the memory module (set/get/list/pin). Default: true */
+    includeMemory?: boolean;
+    /** Additional static branches to add to the tree */
+    staticBranches?: BranchNode[];
+    /** Dynamic tool providers to register. Each entry becomes a DynamicBranchNode */
+    dynamicProviders?: Array<{
+        name: string;
+        description: string;
+        provider: DynamicToolProvider;
+        /** TTL in ms before the provider is re-queried. Default: 60000 */
+        ttlMs?: number;
+    }>;
+}
+/**
+ * A DynamicBranchNode that discovers tools at runtime from a provider.
+ *
+ * Use this to integrate external tool sources (MCP servers, plugin systems,
+ * API discovery endpoints, etc.) into the swiss-army-tool command tree.
+ *
+ * The provider's `discover()` method is called when the TTL expires,
+ * and the returned entries are registered as LeafNode children.
+ *
+ * ```ts
+ * const mcpTools = new AgentDynamicTools({
+ *   name: "mcp",
+ *   description: "Tools discovered from MCP servers",
+ *   provider: myMcpProvider,
+ *   ttlMs: 30_000, // refresh every 30s
+ * });
+ * ```
+ */
+declare class AgentDynamicTools extends DynamicBranchNode {
+    private provider;
+    constructor(config: {
+        name: string;
+        description: string;
+        provider: DynamicToolProvider;
+        ttlMs?: number;
+    });
+    protected refresh(): Promise<void>;
+    /** Manually register a tool entry without waiting for refresh. */
+    registerTool(entry: DynamicToolEntry): void;
+    /** Remove a dynamically registered tool by name. */
+    unregisterTool(name: string): boolean;
+}
+/**
+ * Creates a swiss-army-tool Middleware that emits tool execution timing
+ * and results through the agent's event bus.
+ *
+ * This bridges swiss-army-tool's execution context into oboto-agent's
+ * event-driven architecture, enabling:
+ * - Real-time tool execution duration monitoring
+ * - Tool execution logging / tracing
+ * - Performance analytics
+ *
+ * ```ts
+ * const timingMw = createToolTimingMiddleware(agent.bus);
+ * router.use(timingMw);
+ * ```
+ */
+declare function createToolTimingMiddleware(bus: AgentEventBus): Middleware;
+/**
+ * Creates a swiss-army-tool Middleware that enforces a maximum execution
+ * time for any tool call. Useful as a safety net.
+ */
+declare function createToolTimeoutMiddleware(maxMs: number): Middleware;
+/**
+ * Creates a swiss-army-tool Middleware that logs all tool calls to the
+ * session's KV store for later review. The agent can access these via
+ * the memory module.
+ */
+declare function createToolAuditMiddleware(session: SessionManager): Middleware;
+/**
+ * Build a pre-wired swiss-army-tool command tree that includes:
+ * - Memory module (set/get/list/search/pin/unpin/delete/tag)
+ * - Dynamic tool branches from providers
+ * - Any additional static branches
+ *
+ * Returns the root BranchNode, ready to be passed to `new Router(root, session)`.
+ *
+ * ```ts
+ * const root = createAgentToolTree({
+ *   session,
+ *   includeMemory: true,
+ *   dynamicProviders: [
+ *     { name: "mcp", description: "MCP tools", provider: mcpProvider },
+ *   ],
+ *   staticBranches: [myFilesystemBranch, myDatabaseBranch],
+ * });
+ * const router = new Router(root, session);
+ * ```
+ */
+declare function createAgentToolTree(config: AgentToolTreeConfig): BranchNode;
+
+/**
+ * pipeline-workflows.ts — Multi-step agent workflows using lmscript's Pipeline.
+ *
+ * This module provides pre-built and composable pipeline patterns for
+ * chaining LLM calls where the typed output of one step feeds into the next.
+ *
+ * Key patterns:
+ * 1. Triage → Execute → Summarize
+ * 2. Analyze → Plan → Execute
+ * 3. Custom pipeline builder for agent-specific workflows
+ */
+
+/** Output of a triage step — determines routing and intent. */
+declare const TriagePipelineSchema: z.ZodObject<{
+    intent: z.ZodString;
+    complexity: z.ZodEnum<["simple", "moderate", "complex"]>;
+    requiresTools: z.ZodBoolean;
+    suggestedApproach: z.ZodString;
+    escalate: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    escalate: boolean;
+    intent: string;
+    complexity: "simple" | "moderate" | "complex";
+    requiresTools: boolean;
+    suggestedApproach: string;
+}, {
+    escalate: boolean;
+    intent: string;
+    complexity: "simple" | "moderate" | "complex";
+    requiresTools: boolean;
+    suggestedApproach: string;
+}>;
+type TriagePipelineOutput = z.infer<typeof TriagePipelineSchema>;
+/** Output of a planning step — breaks work into steps. */
+declare const PlanSchema: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        toolRequired: z.ZodOptional<z.ZodString>;
+        expectedOutput: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        toolRequired?: string | undefined;
+        expectedOutput?: string | undefined;
+    }, {
+        description: string;
+        toolRequired?: string | undefined;
+        expectedOutput?: string | undefined;
+    }>, "many">;
+    estimatedComplexity: z.ZodEnum<["low", "medium", "high"]>;
+    reasoning: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    steps: {
+        description: string;
+        toolRequired?: string | undefined;
+        expectedOutput?: string | undefined;
+    }[];
+    estimatedComplexity: "low" | "high" | "medium";
+}, {
+    reasoning: string;
+    steps: {
+        description: string;
+        toolRequired?: string | undefined;
+        expectedOutput?: string | undefined;
+    }[];
+    estimatedComplexity: "low" | "high" | "medium";
+}>;
+type PlanOutput = z.infer<typeof PlanSchema>;
+/** Output of an execution step — the actual work result. */
+declare const ExecutionSchema: z.ZodObject<{
+    response: z.ZodString;
+    stepsCompleted: z.ZodNumber;
+    toolsUsed: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    confidence: z.ZodEnum<["low", "medium", "high"]>;
+}, "strip", z.ZodTypeAny, {
+    response: string;
+    stepsCompleted: number;
+    confidence: "low" | "high" | "medium";
+    toolsUsed?: string[] | undefined;
+}, {
+    response: string;
+    stepsCompleted: number;
+    confidence: "low" | "high" | "medium";
+    toolsUsed?: string[] | undefined;
+}>;
+type ExecutionOutput = z.infer<typeof ExecutionSchema>;
+/** Output of a summarization step — condenses results. */
+declare const SummarySchema: z.ZodObject<{
+    summary: z.ZodString;
+    keyPoints: z.ZodArray<z.ZodString, "many">;
+    followUpSuggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    summary: string;
+    keyPoints: string[];
+    followUpSuggestions?: string[] | undefined;
+}, {
+    summary: string;
+    keyPoints: string[];
+    followUpSuggestions?: string[] | undefined;
+}>;
+type SummaryOutput = z.infer<typeof SummarySchema>;
+/**
+ * Create a triage step function for the pipeline.
  */
-declare function toLmscriptProvider(provider: BaseProvider, name?: string): LLMProvider;
+declare function createTriageStep(modelName: string, systemPrompt?: string): LScriptFunction<string, typeof TriagePipelineSchema>;
+/**
+ * Create a planning step that takes triage output and produces a plan.
+ */
+declare function createPlanStep(modelName: string, systemPrompt?: string): LScriptFunction<TriagePipelineOutput, typeof PlanSchema>;
+/**
+ * Create an execution step that takes a plan and produces results.
+ */
+declare function createExecutionStep(modelName: string, tools?: LScriptFunction<any, any>["tools"], systemPrompt?: string): LScriptFunction<PlanOutput, typeof ExecutionSchema>;
+/**
+ * Create a summarization step that condenses execution results.
+ */
+declare function createSummaryStep(modelName: string, systemPrompt?: string): LScriptFunction<ExecutionOutput, typeof SummarySchema>;
+/**
+ * Build a Triage → Plan → Execute pipeline.
+ *
+ * Takes raw user input, classifies it, plans the approach,
+ * and executes the plan.
+ *
+ * ```ts
+ * const pipeline = createTriagePlanExecutePipeline("gpt-4");
+ * const result = await pipeline.execute(runtime, "Refactor the auth module");
+ * console.log(result.finalData.response);
+ * ```
+ */
+declare function createTriagePlanExecutePipeline(modelName: string, tools?: LScriptFunction<any, any>["tools"]): Pipeline<string, ExecutionOutput>;
+/**
+ * Build a Triage → Plan → Execute → Summarize pipeline.
+ *
+ * Full end-to-end pipeline that classifies, plans, executes,
+ * and then summarizes the results.
+ *
+ * ```ts
+ * const pipeline = createFullPipeline("gpt-4");
+ * const result = await pipeline.execute(runtime, "Build a REST API");
+ * console.log(result.finalData.summary);
+ * console.log(`Total tokens: ${result.totalUsage.totalTokens}`);
+ * ```
+ */
+declare function createFullPipeline(modelName: string, tools?: LScriptFunction<any, any>["tools"]): Pipeline<string, SummaryOutput>;
+/**
+ * Build a simple Analyze → Respond pipeline.
+ * Good for straightforward queries that don't need planning.
+ */
+declare function createAnalyzeRespondPipeline(modelName: string): Pipeline<string, ExecutionOutput>;
+/**
+ * Configuration for running a pipeline within the agent context.
+ */
+interface AgentPipelineConfig {
+    /** The lmscript runtime to execute the pipeline on. */
+    runtime: LScriptRuntime;
+    /** The model name for all pipeline steps (can be overridden per-step). */
+    modelName: string;
+    /** Optional tools available to the execution step. */
+    tools?: LScriptFunction<any, any>["tools"];
+    /** Callback for each pipeline step completion. */
+    onStepComplete?: (stepName: string, data: unknown, usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    } | undefined) => void;
+}
+/**
+ * Run a pipeline and emit step completion events.
+ * This is a convenience wrapper that adds observability.
+ */
+declare function runAgentPipeline<I, O>(pipeline: Pipeline<I, O>, input: I, config: AgentPipelineConfig): Promise<PipelineResult<O>>;
 
 /**
  * Manages the sliding context window with automatic summarization.
@@ -192,7 +1146,7 @@ declare class ContextManager {
 declare const TriageSchema: z.ZodObject<{
     escalate: z.ZodBoolean;
     reasoning: z.ZodString;
-    directResponse: z.ZodOptional<z.ZodString>;
+    directResponse: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | undefined, string | null | undefined>;
 }, "strip", z.ZodTypeAny, {
     escalate: boolean;
     reasoning: string;
@@ -200,7 +1154,7 @@ declare const TriageSchema: z.ZodObject<{
 }, {
     escalate: boolean;
     reasoning: string;
-    directResponse?: string | undefined;
+    directResponse?: string | null | undefined;
 }>;
 type TriageInput = {
     userInput: string;
@@ -213,4 +1167,4 @@ type TriageInput = {
  */
 declare function createTriageFunction(modelName: string): LScriptFunction<TriageInput, typeof TriageSchema>;
 
-export { type AgentEvent, AgentEventBus, type AgentEventType, ContextManager, ObotoAgent, type ObotoAgentConfig, type ToolExecutionEvent, type TriageResult, TriageSchema, createEmptySession, createRouterTool, createTriageFunction, fromChat, sessionToHistory, toChat, toLmscriptProvider };
+export { AgentDynamicTools, type AgentEvent, AgentEventBus, type AgentEventType, type AgentPipelineConfig, type AgentToolTreeConfig, AgentUsageTracker, ContextManager, ConversationRAG, type ConversationRAGConfig, type DynamicToolEntry, type DynamicToolProvider, type ExecutionOutput, ExecutionSchema, HookIntegration, ObotoAgent, type ObotoAgentConfig, PermissionGuard, type PlanOutput, PlanSchema, type ProviderLike$1 as ProviderLike, type RAGRetrievalResult, RouterEventBridge, SessionCompactor, SlashCommandRegistry, type SummaryOutput, SummarySchema, type ToolExecutionEvent, type TriagePipelineOutput, TriagePipelineSchema, type TriageResult, TriageSchema, type UnifiedCostSummary, UsageBridge, asTokenUsageToLmscript, createAgentToolTree, createAnalyzeRespondPipeline, createEmptySession, createExecutionStep, createFullPipeline, createPlanStep, createRouterTool, createSummaryStep, createToolAuditMiddleware, createToolTimeoutMiddleware, createToolTimingMiddleware, createTriageFunction, createTriagePlanExecutePipeline, createTriageStep, estimateCostFromAsAgent, fromChat, isLLMRouter, lmscriptToAsTokenUsage, runAgentPipeline, sessionToHistory, toChat, toLmscriptProvider };