@princetheprogrammerbtw/husk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,702 @@
+/**
+ * Husk — core type definitions.
+ *
+ * This file is the foundation of the public API. Every other module
+ * (agent loop, providers, tools, memory, steering) depends on the
+ * types defined here. Treat changes to this file as breaking changes
+ * unless the change is purely additive (a new optional field).
+ *
+ * Design principle: model the LARGEST common subset of provider
+ * APIs (Anthropic + OpenAI), then let provider adapters translate
+ * provider-specific formats into these shapes.
+ */
+/** Roles a message can take. `tool` is used for tool execution results. */
+type Role = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * The content of a message. Most simple messages are plain strings.
+ * Messages that involve tool use or tool results are arrays of blocks.
+ *
+ * String content is the common case (user prompts, simple replies).
+ * Block content is used when the message contains tool calls (from the
+ * assistant) or tool results (in response to a tool call).
+ */
+type MessageContent = string | ContentBlock[];
+type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
+interface TextBlock {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** A request from the assistant to invoke a tool. */
+interface ToolUseBlock {
+    readonly type: 'tool_use';
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+/** The result of a tool invocation, fed back to the assistant. */
+interface ToolResultBlock {
+    readonly type: 'tool_result';
+    readonly toolUseId: string;
+    readonly content: string | ContentBlock[];
+    readonly isError?: boolean;
+}
+interface Message {
+    readonly role: Role;
+    readonly content: MessageContent;
+    /** Used for `tool` role messages to identify which tool produced the result. */
+    readonly name?: string;
+    /** Used for `tool` role messages to link back to the originating ToolUseBlock. */
+    readonly toolCallId?: string;
+}
+/**
+ * A minimal JSON Schema type. We don't try to model the full spec —
+ * just the shape that tools actually need: object with properties,
+ * required fields, descriptions. Provider adapters can downcast to
+ * their own schema types.
+ */
+interface JSONSchema {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, JSONSchemaField>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+interface JSONSchemaField {
+    readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+    readonly description?: string;
+    readonly enum?: readonly unknown[];
+    readonly items?: JSONSchemaField;
+    readonly properties?: Readonly<Record<string, JSONSchemaField>>;
+    readonly required?: readonly string[];
+}
+interface ToolContext {
+    /** Abort signal to support cancellation. */
+    readonly signal?: AbortSignal;
+    /** Structured logger the tool can use. */
+    readonly logger?: Logger;
+}
+/**
+ * The result of running a tool. `output` is what the LLM sees.
+ * `isError` distinguishes a successful "no results found" from
+ * an actual exception.
+ */
+interface ToolResult {
+    readonly output: string;
+    readonly isError?: boolean;
+}
+/**
+ * A tool the agent can invoke. Providers translate this to their
+ * native tool format (Anthropic's `tools` array, OpenAI's
+ * `functions` array, etc.).
+ */
+interface ToolDefinition<TInput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JSONSchema;
+    readonly execute: (input: TInput, ctx: ToolContext) => Promise<ToolResult>;
+}
+/** Why the model stopped generating. */
+type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error';
+interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+interface ChatRequest {
+    readonly model: string;
+    readonly messages: readonly Message[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly system?: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly stopSequences?: readonly string[];
+}
+interface ChatResponse {
+    readonly message: Message;
+    readonly usage: TokenUsage;
+    readonly stopReason: StopReason;
+    readonly model: string;
+}
+interface ChatChunk {
+    readonly type: 'text' | 'tool_use_start' | 'tool_use_delta' | 'message_end';
+    readonly text?: string;
+    readonly toolUse?: {
+        id: string;
+        name: string;
+        inputDelta?: string;
+    };
+    readonly usage?: TokenUsage;
+    readonly stopReason?: StopReason;
+}
+/**
+ * A model provider. Implementations translate the provider-agnostic
+ * `ChatRequest` to the provider's wire format and back.
+ *
+ * `name` is the provider family ("anthropic", "openai", "ollama").
+ * `model` is the specific model id the provider is configured for
+ * (e.g. "claude-opus-4-6"). The agent loop reads `model` when building
+ * requests, so providers should be configured with a model at
+ * construction time.
+ */
+interface Provider {
+    readonly name: string;
+    readonly model: string;
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    stream?(request: ChatRequest): AsyncIterable<ChatChunk>;
+}
+/**
+ * A memory store. Two backends ship in v0.1.0:
+ * - InMemoryStore: session-scoped, lost on process exit
+ * - FileStore: persistent, JSONL on disk
+ */
+interface MemoryStore {
+    /** Load all messages for a session, in order. */
+    read(sessionId: string): Promise<readonly Message[]>;
+    /** Append a message to a session. */
+    append(sessionId: string, message: Message): Promise<void>;
+    /** Clear all messages for a session. */
+    clear(sessionId: string): Promise<void>;
+    /** List all session IDs the store knows about. */
+    listSessions(): Promise<readonly string[]>;
+}
+interface Example {
+    readonly user: string;
+    readonly assistant: string;
+}
+interface SteeringConfig {
+    /** A system prompt prepended to every conversation. */
+    readonly systemPrompt?: string;
+    /** Behavioral rules injected into the system prompt as a numbered list. */
+    readonly rules?: readonly string[];
+    /** Few-shot examples prepended to the conversation as user/assistant pairs. */
+    readonly examples?: readonly Example[];
+}
+interface AgentConfig {
+    readonly model: Provider;
+    readonly tools?: readonly ToolDefinition[];
+    readonly memory?: MemoryStore;
+    readonly steering?: SteeringConfig;
+    /** Hard cap on agent loop iterations. Default: 25. */
+    readonly maxIterations?: number;
+    /** Sampling temperature. Default: 0 (deterministic). */
+    readonly temperature?: number;
+    /** Max output tokens per model call. Provider-specific defaults apply. */
+    readonly maxTokens?: number;
+    /** Abort signal for cancellation. */
+    readonly signal?: AbortSignal;
+    /** Session ID for memory continuity. Default: 'default'. */
+    readonly sessionId?: string;
+}
+interface AgentResult {
+    readonly output: string;
+    readonly messages: readonly Message[];
+    readonly iterations: number;
+    readonly usage: TokenUsage;
+    readonly durationMs: number;
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+
+/**
+ * Husk — typed event emitter for observability.
+ *
+ * Every interesting thing that happens inside the agent loop fires
+ * an event. Downstream consumers (loggers, tracers, dashboards, test
+ * assertions) subscribe to these events to observe behavior without
+ * having to monkey-patch the agent.
+ *
+ * Design choice: a discriminated-union event type instead of a generic
+ * EventEmitter. The compiler can verify that handlers receive the right
+ * payload shape, and tooling can autocomplete event names.
+ */
+
+type AgentEvent = {
+    readonly type: 'agent:start';
+    readonly input: string;
+    readonly sessionId: string;
+} | {
+    readonly type: 'agent:iteration';
+    readonly iteration: number;
+} | {
+    readonly type: 'agent:message';
+    readonly message: Message;
+} | {
+    readonly type: 'provider:request';
+    readonly request: ChatRequest;
+} | {
+    readonly type: 'provider:response';
+    readonly response: ChatResponse;
+    readonly durationMs: number;
+} | {
+    readonly type: 'tool:call';
+    readonly id: string;
+    readonly name: string;
+    readonly input: unknown;
+} | {
+    readonly type: 'tool:result';
+    readonly id: string;
+    readonly name: string;
+    readonly result: ToolResult;
+    readonly durationMs: number;
+} | {
+    readonly type: 'agent:end';
+    readonly output: string;
+    readonly iterations: number;
+    readonly durationMs: number;
+} | {
+    readonly type: 'agent:error';
+    readonly error: Error;
+};
+/** A handler for a specific event type. */
+type AgentEventHandler<E extends AgentEvent = AgentEvent> = (event: E) => void | Promise<void>;
+/**
+ * A minimal, type-safe event bus. We could use Node's EventEmitter,
+ * but the untyped `on('event', handler)` API loses the discriminated-
+ * union narrowing we get from per-type handlers.
+ */
+declare class AgentEventEmitter {
+    private readonly handlers;
+    private readonly wildcardHandlers;
+    /**
+     * Subscribe to a specific event type. The handler receives only
+     * events of that type with the correct payload shape.
+     */
+    on<E extends AgentEvent['type']>(type: E, handler: AgentEventHandler<Extract<AgentEvent, {
+        type: E;
+    }>>): () => void;
+    /**
+     * Subscribe to all events. Useful for loggers and tracers.
+     */
+    onAny(handler: AgentEventHandler): () => void;
+    off<E extends AgentEvent['type']>(type: E, handler: AgentEventHandler<Extract<AgentEvent, {
+        type: E;
+    }>>): void;
+    /**
+     * Emit an event. Handlers are awaited sequentially; an async handler
+     * that throws is logged but doesn't stop subsequent handlers.
+     */
+    emit(event: AgentEvent): Promise<void>;
+}
+/**
+ * A simple console-based logger. Useful for development and as a
+ * reference implementation for custom loggers.
+ */
+declare class ConsoleLogger implements Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+    private format;
+}
+/**
+ * Convert an event stream into structured log lines via a Logger.
+ * Drop-in for stdout/JSON observability.
+ */
+declare function logEventsTo(logger: Logger): AgentEventHandler;
+
+/**
+ * Husk — memory store implementations.
+ *
+ * Two stores ship in v0.1.0:
+ * - InMemoryStore: session-scoped, fast, lost on process exit
+ * - FileStore: persistent across sessions, JSONL on disk
+ *
+ * Both implement the MemoryStore interface from ./types.js. The agent
+ * loop doesn't care which one it gets — it just calls read/append/clear.
+ *
+ * Design choice: separate stores per file but exported from the same
+ * module. Users can import what they need: `import { InMemory, File } from
+ * '@princetheprogrammerbtw/husk'`.
+ */
+
+/**
+ * Session-scoped memory. Messages live in a Map in process memory.
+ * Fast, zero-dep, but ephemeral — perfect for single-run agents.
+ */
+declare class InMemoryStore implements MemoryStore {
+    private readonly sessions;
+    read(sessionId: string): Promise<readonly Message[]>;
+    append(sessionId: string, message: Message): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+    listSessions(): Promise<readonly string[]>;
+}
+/**
+ * Persistent memory backed by a JSONL file. One file per session by
+ * default, or a single file with a `__session` field per line if you
+ * want a unified log.
+ *
+ * JSONL is the format because:
+ * - Append-only writes are O(1) (no read-modify-write race)
+ * - Corruption is line-scoped, not file-scoped
+ * - It's grep-friendly for debugging
+ */
+interface FileStoreOptions {
+    /** Directory where session files live. Default: './.husk/memory'. */
+    readonly path?: string;
+    /** Use a single file with session markers (default: false, one file per session). */
+    readonly unified?: boolean;
+}
+declare class FileStore implements MemoryStore {
+    private readonly rootDir;
+    private readonly unified;
+    private readonly writeLocks;
+    constructor(options?: FileStoreOptions);
+    read(sessionId: string): Promise<readonly Message[]>;
+    append(sessionId: string, message: Message): Promise<void>;
+    private doAppend;
+    clear(sessionId: string): Promise<void>;
+    listSessions(): Promise<readonly string[]>;
+    private fileFor;
+}
+
+/**
+ * Husk — steering prompt builder.
+ *
+ * "Steering" is the config that shapes agent behavior: system prompt,
+ * rules, and few-shot examples. The builder takes a SteeringConfig
+ * and produces the artifacts the agent loop needs:
+ *   - buildSystemPrompt() → the string to send as the system message
+ *   - buildExamples() → the user/assistant message pairs to seed history
+ *
+ * Why a separate module? Two reasons:
+ * 1. The agent loop stays focused on the loop logic, not prompt assembly.
+ * 2. Steering is the most-likely-to-be-customized piece; users can
+ *    subclass or replace the builder without touching the agent.
+ */
+
+/**
+ * Combine systemPrompt + rules into a single system prompt string.
+ * Rules are numbered for explicit citation ("see rule 3") and
+ * appended after a header so models parse them as a separate list.
+ */
+declare function buildSystemPrompt(steering: SteeringConfig): string | undefined;
+/**
+ * Convert few-shot examples into a sequence of user/assistant message
+ * pairs that get prepended to the conversation history. The model
+ * sees these as if they had happened earlier in the conversation,
+ * which is how few-shot prompting works mechanically.
+ *
+ * Examples are emitted in order; the first user message of an example
+ * comes right after the previous example's assistant message (or right
+ * after the system prompt for the first example).
+ */
+declare function buildExampleMessages(examples: readonly Example[]): readonly Message[];
+
+/**
+ * Husk — the agent loop.
+ *
+ * This is the heartbeat of the harness. The loop is small but every
+ * line matters:
+ *
+ *   1. Compose the conversation (examples + memory + new input)
+ *   2. Call the model
+ *   3. Decide what to do based on stopReason
+ *   4. If tool_use, execute tools and feed results back, then loop
+ *   5. If end_turn, return the final output
+ *
+ * Design choices worth knowing:
+ *
+ * - Tools are executed in parallel within a single iteration. The
+ *   model can request multiple tools in one turn; we honor that and
+ *   feed all results back at once. Most agent frameworks get this wrong
+ *   by serializing tool calls.
+ *
+ * - A faulty tool does not crash the loop. The error becomes a
+ *   tool_result with isError=true, the model sees it, and can either
+ *   retry with corrected input or report back to the user. This is
+ *   how a real assistant would behave.
+ *
+ * - The loop is bounded by maxIterations. Default 25 is enough for
+ *   most agent tasks without running away on infinite loops.
+ *
+ * - The system prompt is rebuilt on every iteration from the steering
+ *   config. Cheap, and means hot-reloading rules works.
+ */
+
+declare class Agent {
+    readonly events: AgentEventEmitter;
+    readonly provider: AgentConfig['model'];
+    readonly tools: readonly ToolDefinition[];
+    readonly steering: AgentConfig['steering'];
+    readonly maxIterations: number;
+    readonly temperature: number;
+    readonly maxTokens: number | undefined;
+    readonly signal: AbortSignal | undefined;
+    readonly sessionId: string;
+    readonly memory: AgentConfig['memory'];
+    readonly logger: Logger;
+    constructor(config: AgentConfig);
+    /**
+     * Subscribe to a specific event type. Returns an unsubscribe fn.
+     */
+    on: AgentEventEmitter['on'];
+    /**
+     * Subscribe to all events. Returns an unsubscribe fn.
+     */
+    onAny: AgentEventEmitter['onAny'];
+    /**
+     * Run the agent loop to completion on the given input.
+     * Returns the final result with output text, full message history,
+     * token usage, and duration.
+     */
+    run(input: string): Promise<AgentResult>;
+    private recordMessage;
+    private executeTool;
+}
+
+/**
+ * Husk — Anthropic Claude provider adapter.
+ *
+ * Translates Husk's provider-agnostic ChatRequest to the Anthropic
+ * Messages API format and back. This is the only file in the project
+ * that knows what Anthropic's wire format looks like.
+ *
+ * Wire-format mapping (Husk → Anthropic):
+ *   - MessageRole 'assistant' + ToolUseBlock   → assistant message with tool_use blocks
+ *   - MessageRole 'user' + ToolResultBlock[]   → user message with tool_result blocks
+ *   - ToolDefinition (Husk JSON Schema)        → Anthropic input_schema (passes through)
+ *   - StopReason 'end_turn' / 'tool_use' / 'max_tokens' / 'stop_sequence'
+ *                                                → returned as-is from stop_reason
+ *
+ * Defaults:
+ *   - model: 'claude-opus-4-6' (override via constructor)
+ *   - max_tokens: 8192 (Anthropic requires this on every request)
+ *   - apiKey: process.env.ANTHROPIC_API_KEY
+ */
+
+interface AnthropicProviderOptions {
+    /** Override the API key. Default: process.env.ANTHROPIC_API_KEY. */
+    readonly apiKey?: string;
+    /** Model id. Default: 'claude-opus-4-6'. */
+    readonly model?: string;
+    /** Override the API base URL (for proxies, self-hosted, etc). */
+    readonly baseURL?: string;
+    /** Default max_tokens for requests. Anthropic requires this. Default: 8192. */
+    readonly maxTokens?: number;
+}
+declare class AnthropicProvider implements Provider {
+    readonly name = "anthropic";
+    readonly model: string;
+    private readonly client;
+    private readonly defaultMaxTokens;
+    constructor(options?: AnthropicProviderOptions);
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}
+
+/**
+ * Husk — OpenAI provider adapter.
+ *
+ * Translates Husk's provider-agnostic ChatRequest to the OpenAI
+ * Chat Completions API format and back. The shape is similar to
+ * Anthropic but with two important differences:
+ *
+ * 1. Tool results are their own message role ('tool'), not blocks in
+ *    a user message. The Husk agent loop emits tool results as user-
+ *    role messages with tool_result content blocks; we split them
+ *    out into individual tool-role messages here.
+ *
+ * 2. Assistant tool calls are an array of tool_call objects on the
+ *    assistant message, not content blocks. We map Husk's tool_use
+ *    blocks to OpenAI's tool_calls shape.
+ *
+ * 3. Tools use the legacy 'functions' shape via the 'tools' field with
+ *    'function' type. (OpenAI's new 'tools' format is the same; we
+ *    use it.)
+ */
+
+interface OpenAIProviderOptions {
+    /** Override the API key. Default: process.env.OPENAI_API_KEY. */
+    readonly apiKey?: string;
+    /** Model id. Default: 'gpt-5'. */
+    readonly model?: string;
+    /** Override the API base URL (for proxies, Azure OpenAI, etc). */
+    readonly baseURL?: string;
+    /** Organization id (for OpenAI orgs). */
+    readonly organization?: string;
+}
+declare class OpenAIProvider implements Provider {
+    readonly name = "openai";
+    readonly model: string;
+    private readonly client;
+    constructor(options?: OpenAIProviderOptions);
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}
+
+/**
+ * Husk — tool registry helpers.
+ *
+ * Tools in Husk are just objects that implement ToolDefinition. There's
+ * no "register" call — you just pass an array to the Agent. These helpers
+ * exist to make the common cases (naming, validation, common schemas)
+ * less verbose.
+ *
+ * Why no global registry? Global state makes testing harder, breaks
+ * tree-shaking, and prevents running multiple agents with different
+ * tool sets in the same process. Explicit arrays are clearer.
+ */
+
+/**
+ * Helper to build a tool definition with less boilerplate. The runtime
+ * behavior is identical to a hand-written ToolDefinition object; this
+ * just makes the common case (typed name, description, schema, executor)
+ * read like a function call.
+ */
+declare function defineTool<TInput>(tool: {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    execute: (input: TInput) => Promise<string> | string;
+}): ToolDefinition<TInput>;
+/** String field with optional enum. */
+declare function stringField(description: string, options?: {
+    enum?: readonly string[];
+}): JSONSchemaField;
+/** Number field (integer or float). */
+declare function numberField(description: string): JSONSchemaField;
+/** Integer field. */
+declare function integerField(description: string): JSONSchemaField;
+/** Boolean field. */
+declare function booleanField(description: string): JSONSchemaField;
+/** Array field of a given element type. */
+declare function arrayField(description: string, items: JSONSchemaField): JSONSchemaField;
+/** Object field with nested properties. */
+declare function objectField(description: string, properties: Readonly<Record<string, JSONSchemaField>>, required?: readonly string[]): JSONSchemaField;
+/**
+ * Build an object schema (the typical top-level shape for tool inputs).
+ * Convenience wrapper around JSONSchema that defaults to type 'object'.
+ */
+declare function objectSchema(properties: Readonly<Record<string, JSONSchemaField>>, required?: readonly string[]): JSONSchema;
+
+/**
+ * Husk — built-in Read tool.
+ *
+ * Reads a file from the local filesystem and returns its contents.
+ * Supports offset (line number) and limit (max lines) for paging
+ * through large files.
+ *
+ * Safety: paths are resolved relative to the working directory. We
+ * refuse to read paths that escape the workspace (e.g. '../etc/passwd')
+ * unless an explicit 'allowOutsideWorkspace' flag is set.
+ */
+interface ReadInput {
+    /** Path to the file, relative to the working directory. */
+    path: string;
+    /** Line number to start reading from (1-indexed). Default: 1. */
+    offset?: number;
+    /** Maximum number of lines to read. Default: 2000. */
+    limit?: number;
+}
+declare const Read: ToolDefinition<ReadInput>;
+
+/**
+ * Husk — built-in Write tool.
+ *
+ * Writes a file to the local filesystem. Creates parent directories
+ * if they don't exist. Overwrites the file if it already exists.
+ *
+ * Returns the number of bytes written and the absolute path so the
+ * model can confirm where the content landed.
+ */
+interface WriteInput {
+    /** Path to the file, relative to the working directory. */
+    path: string;
+    /** Content to write. */
+    content: string;
+}
+declare const Write: ToolDefinition<WriteInput>;
+
+/**
+ * Husk — built-in Edit tool.
+ *
+ * Performs a string replacement in a file. The 'oldText' must match
+ * exactly (including whitespace) and must appear exactly once in the
+ * file. This single-match requirement is what makes the operation
+ * safe: ambiguous replacements fail loudly rather than corrupting
+ * unrelated sections.
+ *
+ * For multi-occurrence replacements, the agent should read the file
+ * first to identify the exact context, then call Edit with enough
+ * surrounding lines to make the match unique.
+ */
+interface EditInput {
+    /** Path to the file, relative to the working directory. */
+    path: string;
+    /** The exact text to replace. Must match exactly one location. */
+    oldText: string;
+    /** The text to replace it with. */
+    newText: string;
+}
+declare const Edit: ToolDefinition<EditInput>;
+
+/**
+ * Husk — built-in Bash tool.
+ *
+ * Executes a shell command and returns stdout/stderr/exit code. The
+ * harness is the model running with developer-level filesystem
+ * access, so a "rm -rf /" mistake is catastrophic. The safety rails
+ * here are a first line of defense — they catch the obvious
+ * footguns, not all of them.
+ *
+ * Safety rails (v0.1.0):
+ * - Block a denylist of catastrophic command patterns. The denylist
+ *   is regex-based, scoped to the command string, and intentionally
+ *   conservative. False positives (a command that looks dangerous
+ *   but isn't) are acceptable; false negatives are not.
+ * - Time out after 60 seconds by default. The model can request a
+ *   longer timeout (max 10 minutes).
+ *
+ * Not in scope for v0.1.0 (deferred to v0.2 with config flag):
+ * - Per-command confirmation prompts
+ * - Network egress filtering
+ * - Filesystem sandboxing
+ * - Audit logging to a separate file
+ */
+interface BashInput {
+    /** The shell command to execute. */
+    command: string;
+    /** Optional description of what the command does (for logging). */
+    description?: string;
+    /** Timeout in milliseconds. Default: 60000 (1 min). Max: 600000 (10 min). */
+    timeout?: number;
+}
+declare const Bash: ToolDefinition<BashInput>;
+
+/**
+ * Husk — built-in Grep tool.
+ *
+ * Searches files for a regex pattern. Uses ripgrep ('rg') if available
+ * for speed; falls back to grep with --line-numbers --no-heading.
+ * Returns matching lines with file:line:content format.
+ *
+ * Default scope: the current working directory, recursively, respecting
+ * .gitignore. The model can scope to a specific path or file.
+ */
+interface GrepInput {
+    /** Regex pattern to search for. */
+    pattern: string;
+    /** File or directory to search in. Default: current directory. */
+    path?: string;
+    /** File glob to filter by (e.g. '*.ts'). Default: all files. */
+    glob?: string;
+    /** Case-insensitive search. Default: false. */
+    ignoreCase?: boolean;
+    /** Maximum number of matching lines to return. Default: 100. */
+    limit?: number;
+}
+declare const Grep: ToolDefinition<GrepInput>;
+
+/**
+ * Husk — public API entry point.
+ *
+ * Single import surface for users:
+ *   import { Agent, Anthropic, OpenAI, Read, Write, Bash, Edit, Grep,
+ *           InMemoryStore, FileStore, ConsoleLogger } from '@princetheprogrammerbtw/husk';
+ *
+ * Re-exports are added incrementally as features land (see commit history).
+ */
+declare const VERSION = "0.0.1";
+
+export { Agent, type AgentConfig, type AgentEvent, AgentEventEmitter, type AgentEventHandler, type AgentResult, AnthropicProvider, type AnthropicProviderOptions, Bash, type BashInput, type ChatChunk, type ChatRequest, type ChatResponse, ConsoleLogger, type ContentBlock, Edit, type EditInput, type Example, FileStore, type FileStoreOptions, Grep, type GrepInput, InMemoryStore, type JSONSchema, type JSONSchemaField, type LogLevel, type Logger, type MemoryStore, type Message, type MessageContent, OpenAIProvider, type OpenAIProviderOptions, type Provider, Read, type ReadInput, type Role, type SteeringConfig, type StopReason, type TextBlock, type TokenUsage, type ToolContext, type ToolDefinition, type ToolResult, type ToolResultBlock, type ToolUseBlock, VERSION, Write, type WriteInput, arrayField, booleanField, buildExampleMessages, buildSystemPrompt, defineTool, integerField, logEventsTo, numberField, objectField, objectSchema, stringField };