@schlenkr/ragents 0.1.5 → 0.1.6

package/packages/agent/dist/core/agent-session.d.ts

@@ -0,0 +1,234 @@
+/** One agent: model and thinking level, prompts, persistence, auto-compaction and retry, extension hooks and tools. */
+import type { Agent, AgentEvent, AgentMessage, ThinkingLevel } from "../loop/index.ts";
+import type { Model, UserAttachment } from "@ragents/ai";
+import { type CompactionResult } from "./compaction/index.ts";
+import { type ExtensionErrorListener, ExtensionRunner, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
+import type { ModelRuntime } from "./model-runtime.ts";
+import type { ResourceLoader } from "./resource-loader.ts";
+import type { SessionManager } from "./session-manager.ts";
+import type { AgentSettings } from "./agent-settings.ts";
+/** Session-specific events that extend the core AgentEvent */
+export type AgentSessionEvent = Exclude<AgentEvent, {
+    type: "agent_end";
+}> | {
+    type: "agent_end";
+    messages: AgentMessage[];
+    willRetry: boolean;
+} | {
+    type: "agent_settled";
+} | {
+    type: "compaction_start";
+    reason: "threshold" | "overflow";
+} | {
+    type: "thinking_level_changed";
+    level: ThinkingLevel;
+} | {
+    type: "compaction_end";
+    reason: "threshold" | "overflow";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+};
+/** Listener function for agent session events */
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+export interface AgentSessionConfig {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: AgentSettings;
+    cwd: string;
+    /** Resource loader for extensions, skills and the system prompt */
+    resourceLoader: ResourceLoader;
+    /** SDK custom tools registered outside extensions */
+    customTools?: ToolDefinition[];
+    /** Canonical model/auth runtime. */
+    modelRuntime: ModelRuntime;
+    /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
+    allowedToolNames?: string[];
+    /** Mutable ref used by Agent to access the current ExtensionRunner */
+    extensionRunnerRef?: {
+        current?: ExtensionRunner;
+    };
+}
+export interface ExtensionBindings {
+    onError?: ExtensionErrorListener;
+}
+/** Options for AgentSession.prompt() */
+export interface PromptOptions {
+    attachments?: UserAttachment[];
+    /** Observes whether the prompt was accepted or rejected before the agent run starts. */
+    preflightResult?: (success: boolean) => void;
+}
+export declare class AgentSession {
+    readonly agent: Agent;
+    readonly sessionManager: SessionManager;
+    readonly settings: AgentSettings;
+    private _unsubscribeAgent?;
+    private _eventListeners;
+    private _isAgentRunActive;
+    private _disposed;
+    private _idleWaitPromise;
+    private _resolveIdleWait;
+    private _autoCompactionAbortController;
+    private _overflowRecoveryAttempted;
+    private _retryAbortController;
+    private _retryAttempt;
+    private _extensionRunner;
+    private _resourceLoader;
+    private _customTools;
+    private _cwd;
+    private _extensionRunnerRef?;
+    private _allowedToolNames?;
+    private _extensionErrorUnsubscriber?;
+    private _modelRuntime;
+    private _toolRegistry;
+    private _toolDefinitions;
+    private _toolPromptSnippets;
+    private _toolPromptGuidelines;
+    private _baseSystemPrompt;
+    private _baseSystemPromptOptions;
+    private _systemPromptOverride?;
+    constructor(config: AgentSessionConfig);
+    private _getRequiredRequestAuth;
+    private _getSummarizationRequestAuth;
+    /** The tool result hook reads `this._extensionRunner` at execution time. */
+    private _installAgentToolHooks;
+    private _installAgentNextTurnRefresh;
+    /** Emit an event to all listeners */
+    private _emit;
+    private _getIdleWaitPromise;
+    private _resolveIdleWaitIfIdle;
+    private _emitAgentSettled;
+    private _lastAssistantMessage;
+    /** Internal handler for agent events - shared by subscribe and reconnect */
+    private _handleAgentEvent;
+    private _willRetryAfterAgentEnd;
+    /** Find the last assistant message in agent state (including aborted ones) */
+    private _findLastAssistantMessage;
+    /**
+     * Subscribe to agent events.
+     * Session persistence is handled internally (saves messages on message_end).
+     * Multiple listeners can be added. Returns unsubscribe function for this listener.
+     */
+    subscribe(listener: AgentSessionEventListener): () => void;
+    /**
+     * Remove all listeners and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose(): void;
+    waitForSettlement(): Promise<void>;
+    /** Current model (may be undefined if not yet selected) */
+    get model(): Model<any> | undefined;
+    /** Current thinking level */
+    get thinkingLevel(): ThinkingLevel;
+    /** Whether the session is currently processing an agent run or post-run continuation. */
+    get isStreaming(): boolean;
+    /** Whether the session has no active agent run, retry, auto-compaction, or queued continuation. */
+    get isIdle(): boolean;
+    /** Replace the custom system prompt and rebuild the effective prompt for the next model call. */
+    setSystemPrompt(prompt: string): void;
+    /**
+     * Get the names of currently active tools.
+     * Returns the names of tools currently set on the agent.
+     */
+    getActiveToolNames(): string[];
+    /**
+     * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
+     */
+    getAllTools(): ToolInfo[];
+    /**
+     * Set active tools by name.
+     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Also rebuilds the system prompt to reflect the new tool set.
+     * Changes take effect on the next agent turn.
+     */
+    setActiveToolsByName(toolNames: string[]): void;
+    /** All messages including custom types */
+    get messages(): AgentMessage[];
+    /** Current session file path, or undefined if sessions are disabled */
+    get sessionFile(): string | undefined;
+    /** Current session ID */
+    get sessionId(): string;
+    private _normalizePromptSnippet;
+    private _normalizePromptGuidelines;
+    private _rebuildSystemPrompt;
+    private _runAgentPrompt;
+    private _handlePostAgentRun;
+    /** Run a prompt; while the agent runs, or without model or key, it throws. */
+    prompt(text: string, options?: PromptOptions): Promise<void>;
+    private _assertNotDisposed;
+    /**
+     * Abort current operation and wait for agent to become idle.
+     */
+    abort(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    /**
+     * Set model directly.
+     * Validates that auth is configured, saves to session and settings.
+     * @throws Error if no auth is configured for the model
+     */
+    setModel(model: Model<any>): Promise<void>;
+    /**
+     * Set thinking level.
+     * Clamps to model capabilities based on available thinking levels.
+     * Saves to session and settings only if the level actually changes.
+     */
+    setThinkingLevel(level: ThinkingLevel): void;
+    /**
+     * Get available thinking levels for current model.
+     * The provider will clamp to what the specific model supports internally.
+     */
+    getAvailableThinkingLevels(): ThinkingLevel[];
+    /**
+     * Check if current model supports thinking/reasoning.
+     */
+    private supportsThinking;
+    private _getThinkingLevelForModelSwitch;
+    private _clampThinkingLevel;
+    /**
+     * Check if compaction is needed and run it.
+     * Called after agent_end and before prompt submission.
+     *
+     * Two cases:
+     * 1. Overflow: LLM returned context overflow error, remove error message from agent state, compact, auto-retry
+     * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     */
+    private _checkCompaction;
+    /**
+     * Internal: Run auto-compaction with events.
+     */
+    private _runAutoCompaction;
+    bindExtensions(bindings: ExtensionBindings): Promise<void>;
+    private _bindExtensionCore;
+    private _refreshToolRegistry;
+    private _buildRuntime;
+    /**
+     * Check if an error is retryable (overloaded, rate limit, server errors).
+     * Context overflow errors are NOT retryable (handled by compaction instead).
+     */
+    private _isRetryableError;
+    /**
+     * Prepare a retryable error for continuation with exponential backoff.
+     * @returns true if the caller should continue the agent, false otherwise
+     */
+    private _prepareRetry;
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry(): void;
+}
+//# sourceMappingURL=agent-session.d.ts.map

package/packages/agent/dist/core/agent-settings.d.ts

@@ -0,0 +1,27 @@
+/** The few knobs of an agent session; everything else is fixed. */
+export interface AgentSettings {
+    compaction: {
+        enabled: boolean;
+        reserveTokens: number;
+        keepRecentTokens: number;
+    };
+    /** Retries of the session after a retryable model error, with exponential backoff. */
+    retry: {
+        enabled: boolean;
+        maxRetries: number;
+        baseDelayMs: number;
+    };
+    /** Timeout and retries of a single provider request; unset values leave the SDK defaults. */
+    providerRequest: {
+        timeoutMs: number;
+        maxRetries?: number;
+        maxRetryDelayMs: number;
+    };
+}
+export interface AgentSettingsInput {
+    compaction?: Partial<AgentSettings["compaction"]>;
+    retry?: Partial<AgentSettings["retry"]>;
+    providerRequest?: Partial<AgentSettings["providerRequest"]>;
+}
+export declare const agentSettings: (input?: AgentSettingsInput) => AgentSettings;
+//# sourceMappingURL=agent-settings.d.ts.map

package/packages/agent/dist/core/auth-guidance.d.ts

@@ -0,0 +1,4 @@
+export declare function getProviderLoginHelp(): string;
+export declare function formatNoModelSelectedMessage(): string;
+export declare function formatNoApiKeyFoundMessage(provider: string): string;
+//# sourceMappingURL=auth-guidance.d.ts.map

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

@@ -0,0 +1,116 @@
+/**
+ * Context compaction for long sessions.
+ *
+ * Pure functions for compaction logic. The session manager handles I/O,
+ * and after compaction the session is reloaded.
+ */
+import type { AgentMessage, StreamFn, ThinkingLevel } from "../../loop/index.ts";
+import type { Model, Usage } from "@ragents/ai";
+import { type SessionEntry } from "../session-manager.ts";
+import { type FileOperations } from "./utils.ts";
+/** Details stored in CompactionEntry.details for file tracking */
+export interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+/** Result from compact() - SessionManager adds uuid/parentUuid when saving */
+export interface CompactionResult<T = unknown> {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    estimatedTokensAfter?: number;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+}
+export interface CompactionSettings {
+    enabled: boolean;
+    reserveTokens: number;
+    keepRecentTokens: number;
+}
+/**
+ * Calculate total context tokens from usage.
+ * Uses the native totalTokens field when available, falls back to computing from components.
+ */
+export declare function calculateContextTokens(usage: Usage): number;
+export interface ContextUsageEstimate {
+    tokens: number;
+    usageTokens: number;
+    trailingTokens: number;
+    lastUsageIndex: number | null;
+}
+/**
+ * Estimate context tokens from messages, using the last assistant usage when available.
+ * If there are messages after the last usage, estimate their tokens with estimateTokens.
+ */
+export declare function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate;
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/**
+ * Estimate token count for a message using chars/4 heuristic.
+ * This is conservative (overestimates tokens).
+ */
+export declare function estimateTokens(message: AgentMessage): number;
+/**
+ * Find the context-visible user-role message that starts the turn containing the given entry index.
+ * Returns -1 if no turn start found before the index.
+ */
+export declare function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number;
+export interface CutPointResult {
+    /** Index of first entry to keep */
+    firstKeptEntryIndex: number;
+    /** Index of user message that starts the turn being split, or -1 if not splitting */
+    turnStartIndex: number;
+    /** Whether this cut splits a turn (cut point is not a user message) */
+    isSplitTurn: boolean;
+}
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ *
+ * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
+ * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ *
+ * Can cut at user OR assistant messages (never tool results). When cutting at an
+ * assistant message with tool calls, its tool results come after and will be kept.
+ *
+ * Returns CutPointResult with:
+ * - firstKeptEntryIndex: the entry index to start keeping from
+ * - turnStartIndex: if cutting mid-turn, the user message that started that turn
+ * - isSplitTurn: whether we're cutting in the middle of a turn
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+/**
+ * Generate a summary of the conversation using the LLM.
+ * If previousSummary is provided, uses the update prompt to merge.
+ */
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>): Promise<string>;
+export interface CompactionPreparation {
+    /** UUID of first entry to keep */
+    firstKeptEntryId: string;
+    /** Messages that will be summarized and discarded */
+    messagesToSummarize: AgentMessage[];
+    /** Messages that will be turned into turn prefix summary (if splitting) */
+    turnPrefixMessages: AgentMessage[];
+    /** Whether this is a split turn (cut point in middle of turn) */
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    /** Summary from previous compaction, for iterative update */
+    previousSummary?: string;
+    /** File operations extracted from messagesToSummarize */
+    fileOps: FileOperations;
+    /** Compaction settions from settings.jsonl	*/
+    settings: CompactionSettings;
+}
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+/**
+ * Generate summaries for compaction using prepared data.
+ * Returns CompactionResult - SessionManager adds uuid/parentUuid when saving.
+ *
+ * @param preparation - Pre-calculated preparation from prepareCompaction()
+ * @param customInstructions - Optional custom focus for the summary
+ */
+export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>): Promise<CompactionResult>;
+//# sourceMappingURL=compaction.d.ts.map

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

@@ -0,0 +1,6 @@
+/**
+ * Compaction and summarization utilities.
+ */
+export * from "./compaction.ts";
+export * from "./utils.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/dist/core/compaction/utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+import type { AgentMessage } from "../../loop/index.ts";
+import type { Message, UserAttachment } from "@ragents/ai";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export declare function computeFileLists(fileOps: FileOperations): {
+    readFiles: string[];
+    modifiedFiles: string[];
+};
+/**
+ * Format file operations as XML tags for summary.
+ */
+export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ *
+ * Tool results are truncated to keep the summarization request within
+ * reasonable token budgets. Full content is not needed for summarization.
+ */
+export declare function serializeConversation(messages: Message[]): string;
+export declare function collectUserAttachments(messages: Message[]): UserAttachment[];
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1,3 @@
+import type { ThinkingLevel } from "../loop/index.ts";
+export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1,11 @@
+/**
+ * Extension system for agent hooks and custom tools.
+ */
+export type { SourceInfo } from "../source-info.ts";
+export { createExtensionRuntime, loadExtensionFromFactory } from "./loader.ts";
+export type { ExtensionContextSource, ExtensionErrorListener } from "./runner.ts";
+export { ExtensionRunner, STALE_EXTENSION_MESSAGE } from "./runner.ts";
+export type { AgentToolResult, AgentToolUpdateCallback, BeforeAgentStartEvent, BeforeAgentStartEventResult, BuildSystemPromptOptions, ContextEvent, ContextEventResult, Extension, ExtensionActions, ExtensionAPI, ExtensionContext, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFactoryContext, ExtensionFactorySettlementObserver, ExtensionHandler, ExtensionRuntime, InlineExtension, LoadExtensionsResult, RegisteredTool, ToolDefinition, ToolExecutionMode, ToolInfo, ToolResultEvent, ToolResultEventResult, } from "./types.ts";
+export { defineTool } from "./types.ts";
+export { wrapRegisteredTools } from "./wrapper.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/dist/core/extensions/loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extension loader - creates extensions from inline factories.
+ */
+import type { Extension, ExtensionFactory, ExtensionFactorySettlementObserver, ExtensionRuntime } from "./types.ts";
+/**
+ * Create a runtime with throwing stubs for action methods.
+ * Runner.bindCore() replaces these with real implementations.
+ */
+export declare function createExtensionRuntime(): ExtensionRuntime;
+/** Create an Extension from an inline factory function. */
+export declare function loadExtensionFromFactory(factory: ExtensionFactory, runtime: ExtensionRuntime, extensionPath: string, signal?: AbortSignal, onFactorySettlement?: ExtensionFactorySettlementObserver): Promise<Extension>;
+//# sourceMappingURL=loader.d.ts.map

package/packages/agent/dist/core/extensions/runner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Extension runner - executes extension handlers against one agent session.
+ */
+import type { AgentMessage } from "../../loop/index.ts";
+import type { Model, UserAttachment } from "@ragents/ai";
+import type { SessionManager } from "../session-manager.ts";
+import type { BuildSystemPromptOptions } from "../system-prompt.ts";
+import type { Extension, ExtensionActions, ExtensionContext, ExtensionError, ExtensionRuntime, RegisteredTool, ToolResultEvent, ToolResultEventResult } from "./types.ts";
+export type ExtensionErrorListener = (error: ExtensionError) => void;
+/** What the runner reads from its session when it builds a handler context. */
+export interface ExtensionContextSource {
+    getModel: () => Model<any> | undefined;
+    getSignal: () => AbortSignal | undefined;
+}
+export declare const STALE_EXTENSION_MESSAGE = "This extension is stale: its agent session was disposed.";
+export declare class ExtensionRunner {
+    private readonly extensions;
+    private readonly runtime;
+    private readonly sessionManager;
+    private readonly errorListeners;
+    private contextSource;
+    private staleMessage;
+    constructor(extensions: Extension[], runtime: ExtensionRuntime, sessionManager: SessionManager);
+    bindCore(actions: ExtensionActions, contextSource: ExtensionContextSource): void;
+    /** Get all registered tools from all extensions (first registration per name wins). */
+    getAllRegisteredTools(): RegisteredTool[];
+    invalidate(message?: string): void;
+    private assertActive;
+    onError(listener: ExtensionErrorListener): () => void;
+    private emitError;
+    hasHandlers(eventType: string): boolean;
+    /** Context values are resolved at call time, so a disposed session is detected on every access. */
+    createContext(): ExtensionContext;
+    emitToolResult(event: ToolResultEvent): Promise<ToolResultEventResult | undefined>;
+    emitContext(messages: AgentMessage[]): Promise<AgentMessage[]>;
+    /** Chains the system prompt through all before_agent_start handlers; undefined when none changed it. */
+    emitBeforeAgentStart(prompt: string, systemPrompt: string, systemPromptOptions: BuildSystemPromptOptions, attachments?: UserAttachment[]): Promise<string | undefined>;
+}
+//# sourceMappingURL=runner.d.ts.map

package/packages/agent/dist/core/extensions/types.d.ts

@@ -0,0 +1,156 @@
+/** Extensions are inline factories: they adjust the system prompt, the messages of a model call and tool results, and register tools. */
+import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../../loop/index.ts";
+import type { ImageContent, Model, TextContent, UserAttachment } from "@ragents/ai";
+import type { Static, TSchema } from "typebox";
+import type { ReadonlySessionManager } from "../session-manager.ts";
+import type { SourceInfo } from "../source-info.ts";
+import type { BuildSystemPromptOptions } from "../system-prompt.ts";
+export type { BuildSystemPromptOptions } from "../system-prompt.ts";
+export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
+/** Context passed to extension event handlers and tools. */
+export interface ExtensionContext {
+    /** Session manager (read-only) */
+    sessionManager: ReadonlySessionManager;
+    /** Current model (may be undefined) */
+    model: Model<any> | undefined;
+    /** The current abort signal, or undefined when the agent is not streaming. */
+    signal: AbortSignal | undefined;
+}
+/** Tool definition for registerTool(). */
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any> {
+    /** Tool name (used in LLM tool calls) */
+    name: string;
+    /** Human-readable label */
+    label: string;
+    /** Description for LLM */
+    description: string;
+    /** Optional one-line snippet for the Available tools section in the default system prompt. */
+    promptSnippet?: string;
+    /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+    promptGuidelines?: string[];
+    /** Parameter schema (TypeBox) */
+    parameters: TParams;
+    /** Optional compatibility shim to prepare raw tool call arguments before schema validation. */
+    prepareArguments?: (args: unknown) => Static<TParams>;
+    /** Per-tool execution mode override; if omitted, the default execution mode applies. */
+    executionMode?: ToolExecutionMode;
+    /** Execute the tool. */
+    execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ExtensionContext): Promise<AgentToolResult<TDetails>>;
+}
+type AnyToolDefinition = ToolDefinition<any, any, any>;
+/** Preserve parameter inference for standalone tool definitions. */
+export declare function defineTool<TParams extends TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
+/** Fired before each LLM call. Can modify messages. */
+export interface ContextEvent {
+    type: "context";
+    messages: AgentMessage[];
+}
+/** Fired after the user submits a prompt but before the agent loop. */
+export interface BeforeAgentStartEvent {
+    type: "before_agent_start";
+    /** The raw user prompt text. */
+    prompt: string;
+    attachments?: UserAttachment[];
+    /** The fully assembled system prompt string. */
+    systemPrompt: string;
+    /** Structured options used to build the system prompt. */
+    systemPromptOptions: BuildSystemPromptOptions;
+}
+/** Fired after a tool executes. Can modify the result. */
+export interface ToolResultEvent {
+    type: "tool_result";
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    content: (TextContent | ImageContent)[];
+    details: unknown;
+    isError: boolean;
+}
+export type ExtensionEvent = ContextEvent | BeforeAgentStartEvent | ToolResultEvent;
+export interface ContextEventResult {
+    messages?: AgentMessage[];
+}
+export interface ToolResultEventResult {
+    content?: (TextContent | ImageContent)[];
+    details?: unknown;
+    isError?: boolean;
+}
+export interface BeforeAgentStartEventResult {
+    /** Replace the system prompt for this turn. If multiple extensions return this, they are chained. */
+    systemPrompt?: string;
+}
+/** Handler function type for events */
+export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
+/** ExtensionAPI passed to extension factory functions. */
+export interface ExtensionAPI {
+    on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
+    on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
+    on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
+    /** Register a tool that the LLM can call. */
+    registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): void;
+    /** Append a custom entry to the session for state persistence (not sent to LLM). */
+    appendEntry<T = unknown>(customType: string, data?: T): void;
+    /** Get all configured tools with parameter schema, prompt guidelines, and source metadata. */
+    getAllTools(): ToolInfo[];
+    /** Set the active tools by name. */
+    setActiveTools(toolNames: string[]): void;
+}
+export interface ExtensionFactoryContext {
+    readonly signal: AbortSignal;
+}
+/** Extension factory function type. Supports both sync and async initialization. */
+export type ExtensionFactory = (agent: ExtensionAPI, context: ExtensionFactoryContext) => void | Promise<void>;
+/** Observes the actual lifetime of an async extension factory, independently of an aborted loader wait. */
+export type ExtensionFactorySettlementObserver = (settlement: Promise<void>) => void;
+export type InlineExtension = ExtensionFactory | {
+    /** Display name shown as `<inline:name>`. */
+    name: string;
+    factory: ExtensionFactory;
+};
+export interface RegisteredTool {
+    definition: ToolDefinition;
+    sourceInfo: SourceInfo;
+}
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
+    sourceInfo: SourceInfo;
+};
+/** Action implementations behind the ExtensionAPI, provided by the session. */
+export interface ExtensionActions {
+    appendEntry: <T = unknown>(customType: string, data?: T) => void;
+    getAllTools: () => ToolInfo[];
+    setActiveTools: (toolNames: string[]) => void;
+    refreshTools: () => void;
+}
+/** Shared state created by the loader; actions are throwing stubs until the runner binds the session. */
+export interface ExtensionRuntime extends ExtensionActions {
+    /** Throws when this extension instance is stale. */
+    assertActive: () => void;
+    /** Marks this extension instance as stale. */
+    invalidate: (message?: string) => void;
+}
+/** Loaded extension with all registered items. */
+export interface Extension {
+    path: string;
+    sourceInfo: SourceInfo;
+    handlers: Map<string, HandlerFn[]>;
+    tools: Map<string, RegisteredTool>;
+}
+/** Result of loading extensions. */
+export interface LoadExtensionsResult {
+    extensions: Extension[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+    /** Shared runtime - actions are throwing stubs until the runner binds the session */
+    runtime: ExtensionRuntime;
+}
+export interface ExtensionError {
+    extensionPath: string;
+    event: string;
+    error: string;
+    stack?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/agent/dist/core/extensions/wrapper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tool wrappers for extension-registered tools.
+ *
+ * These wrappers only adapt tool execution so extension tools receive the runner context.
+ * Tool result interception is handled by AgentSession via the hooks of the agent loop.
+ */
+import type { AgentTool } from "../../loop/index.ts";
+import type { ExtensionRunner } from "./runner.ts";
+import type { RegisteredTool } from "./types.ts";
+/** Wrap registered tools into AgentTools that receive the runner context on every call. */
+export declare function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: ExtensionRunner): AgentTool[];
+//# sourceMappingURL=wrapper.d.ts.map