@soederpop/luca 0.1.2 → 0.1.3

package/dist/agi/features/conversation.d.ts

@@ -0,0 +1,464 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import type { OpenAIClient } from '../../clients/openai';
+import type OpenAI from 'openai';
+import type { ConversationHistory } from './conversation-history';
+declare module '@soederpop/luca/feature' {
+    interface AvailableFeatures {
+        conversation: typeof Conversation;
+    }
+}
+export type Message = OpenAI.Chat.Completions.ChatCompletionMessageParam;
+export type ContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'low' | 'high' | 'auto';
+    };
+} | {
+    type: 'input_audio';
+    data: string;
+    format: 'mp3' | 'wav';
+} | {
+    type: 'input_file';
+    file_data: string;
+    filename: string;
+};
+export interface ConversationTool {
+    handler: (...args: any[]) => Promise<any>;
+    description: string;
+    parameters: Record<string, any>;
+}
+export interface ConversationMCPServer {
+    url: string;
+    headers?: Record<string, string>;
+    allowedTools?: string[] | {
+        tool_names?: string[];
+    };
+    requireApproval?: 'always' | 'never' | {
+        always?: {
+            tool_names?: string[];
+        };
+        never?: {
+            tool_names?: string[];
+        };
+    };
+}
+export declare const ConversationOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    thread: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    history: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    api: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        responses: "responses";
+        chat: "chat";
+    }>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    clientOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    local: z.ZodOptional<z.ZodBoolean>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    topK: z.ZodOptional<z.ZodNumber>;
+    frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+    presencePenalty: z.ZodOptional<z.ZodNumber>;
+    stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    autoCompact: z.ZodOptional<z.ZodBoolean>;
+    compactThreshold: z.ZodOptional<z.ZodNumber>;
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    compactKeepRecent: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const ConversationStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    id: z.ZodString;
+    thread: z.ZodString;
+    model: z.ZodString;
+    messages: z.ZodArray<z.ZodAny>;
+    streaming: z.ZodBoolean;
+    lastResponse: z.ZodString;
+    toolCalls: z.ZodNumber;
+    api: z.ZodEnum<{
+        responses: "responses";
+        chat: "chat";
+    }>;
+    lastResponseId: z.ZodNullable<z.ZodString>;
+    tokenUsage: z.ZodObject<{
+        prompt: z.ZodNumber;
+        completion: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    estimatedInputTokens: z.ZodNumber;
+    compactionCount: z.ZodNumber;
+    contextWindow: z.ZodNumber;
+    tools: z.ZodRecord<z.ZodString, z.ZodAny>;
+    callMaxTokens: z.ZodNullable<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const ConversationEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    userMessage: z.ZodTuple<[z.ZodAny], null>;
+    turnStart: z.ZodTuple<[z.ZodObject<{
+        turn: z.ZodNumber;
+        isFollowUp: z.ZodBoolean;
+    }, z.core.$strip>], null>;
+    turnEnd: z.ZodTuple<[z.ZodObject<{
+        turn: z.ZodNumber;
+        hasToolCalls: z.ZodBoolean;
+    }, z.core.$strip>], null>;
+    toolCallsStart: z.ZodTuple<[z.ZodAny], null>;
+    toolCall: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    toolResult: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    toolError: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    toolCallsEnd: z.ZodTuple<[], null>;
+    chunk: z.ZodTuple<[z.ZodString], null>;
+    preview: z.ZodTuple<[z.ZodString], null>;
+    response: z.ZodTuple<[z.ZodString], null>;
+    responseCompleted: z.ZodTuple<[z.ZodAny], null>;
+    rawEvent: z.ZodTuple<[z.ZodAny], null>;
+    mcpEvent: z.ZodTuple<[z.ZodAny], null>;
+    summarizeStart: z.ZodTuple<[], null>;
+    summarizeEnd: z.ZodTuple<[z.ZodString], null>;
+    compactStart: z.ZodTuple<[z.ZodObject<{
+        messageCount: z.ZodNumber;
+        keepRecent: z.ZodNumber;
+    }, z.core.$strip>], null>;
+    compactEnd: z.ZodTuple<[z.ZodObject<{
+        summary: z.ZodString;
+        removedCount: z.ZodNumber;
+        estimatedTokens: z.ZodNumber;
+        compactionCount: z.ZodNumber;
+    }, z.core.$strip>], null>;
+    autoCompactTriggered: z.ZodTuple<[z.ZodObject<{
+        estimated: z.ZodNumber;
+        limit: z.ZodNumber;
+        contextWindow: z.ZodNumber;
+    }, z.core.$strip>], null>;
+}, z.core.$strip>;
+export type ConversationOptions = z.infer<typeof ConversationOptionsSchema>;
+export type ConversationState = z.infer<typeof ConversationStateSchema>;
+export type AskOptions = {
+    maxTokens?: number;
+    /**
+     * When provided, enables OpenAI Structured Outputs. The model is constrained
+     * to return JSON matching this Zod schema. The return value of ask() will be
+     * the parsed object instead of a raw string.
+     */
+    schema?: z.ZodType;
+};
+/**
+ * A self-contained conversation with OpenAI that supports streaming,
+ * tool calling, and message state management.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const conversation = container.feature('conversation', {
+ *   model: 'gpt-4.1',
+ *   tools: myToolMap,
+ *   history: [{ role: 'system', content: 'You are a helpful assistant.' }]
+ * })
+ * const reply = await conversation.ask('What is the meaning of life?')
+ * ```
+ */
+export declare class Conversation extends Feature<ConversationState, ConversationOptions> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        id: z.ZodString;
+        thread: z.ZodString;
+        model: z.ZodString;
+        messages: z.ZodArray<z.ZodAny>;
+        streaming: z.ZodBoolean;
+        lastResponse: z.ZodString;
+        toolCalls: z.ZodNumber;
+        api: z.ZodEnum<{
+            responses: "responses";
+            chat: "chat";
+        }>;
+        lastResponseId: z.ZodNullable<z.ZodString>;
+        tokenUsage: z.ZodObject<{
+            prompt: z.ZodNumber;
+            completion: z.ZodNumber;
+            total: z.ZodNumber;
+        }, z.core.$strip>;
+        estimatedInputTokens: z.ZodNumber;
+        compactionCount: z.ZodNumber;
+        contextWindow: z.ZodNumber;
+        tools: z.ZodRecord<z.ZodString, z.ZodAny>;
+        callMaxTokens: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        thread: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        history: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+        tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        api: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            responses: "responses";
+            chat: "chat";
+        }>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        clientOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        local: z.ZodOptional<z.ZodBoolean>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        topK: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        stop: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        autoCompact: z.ZodOptional<z.ZodBoolean>;
+        compactThreshold: z.ZodOptional<z.ZodNumber>;
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        compactKeepRecent: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        userMessage: z.ZodTuple<[z.ZodAny], null>;
+        turnStart: z.ZodTuple<[z.ZodObject<{
+            turn: z.ZodNumber;
+            isFollowUp: z.ZodBoolean;
+        }, z.core.$strip>], null>;
+        turnEnd: z.ZodTuple<[z.ZodObject<{
+            turn: z.ZodNumber;
+            hasToolCalls: z.ZodBoolean;
+        }, z.core.$strip>], null>;
+        toolCallsStart: z.ZodTuple<[z.ZodAny], null>;
+        toolCall: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        toolResult: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        toolError: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        toolCallsEnd: z.ZodTuple<[], null>;
+        chunk: z.ZodTuple<[z.ZodString], null>;
+        preview: z.ZodTuple<[z.ZodString], null>;
+        response: z.ZodTuple<[z.ZodString], null>;
+        responseCompleted: z.ZodTuple<[z.ZodAny], null>;
+        rawEvent: z.ZodTuple<[z.ZodAny], null>;
+        mcpEvent: z.ZodTuple<[z.ZodAny], null>;
+        summarizeStart: z.ZodTuple<[], null>;
+        summarizeEnd: z.ZodTuple<[z.ZodString], null>;
+        compactStart: z.ZodTuple<[z.ZodObject<{
+            messageCount: z.ZodNumber;
+            keepRecent: z.ZodNumber;
+        }, z.core.$strip>], null>;
+        compactEnd: z.ZodTuple<[z.ZodObject<{
+            summary: z.ZodString;
+            removedCount: z.ZodNumber;
+            estimatedTokens: z.ZodNumber;
+            compactionCount: z.ZodNumber;
+        }, z.core.$strip>], null>;
+        autoCompactTriggered: z.ZodTuple<[z.ZodObject<{
+            estimated: z.ZodNumber;
+            limit: z.ZodNumber;
+            contextWindow: z.ZodNumber;
+        }, z.core.$strip>], null>;
+    }, z.core.$strip>;
+    static shortcut: "features.conversation";
+    /**
+     * Pluggable tool executor. Called for each tool invocation with the tool
+     * name, parsed args, and the default handler. Return the serialized result string.
+     * The Assistant replaces this to wire in beforeToolCall/afterToolCall interceptors.
+     */
+    toolExecutor: ((name: string, args: Record<string, any>, handler: (...args: any[]) => Promise<any>) => Promise<string>) | null;
+    /** The active structured output schema for the current ask() call, if any. */
+    private _activeSchema;
+    /** Registered stubs: matched against user input to short-circuit the API with a canned response. */
+    private _stubs;
+    /** Resolved max tokens: per-call override > options-level > default 512. */
+    private get maxTokens();
+    /** @returns Default state seeded from options: id, thread, model, initial history, and zero token usage. */
+    get initialState(): ConversationState;
+    /** Returns the registered tools available for the model to call. */
+    get tools(): Record<string, ConversationTool>;
+    get availableTools(): string[];
+    /**
+     * Add or replace a single tool by name.
+     * Uses the same format as tools passed at construction time.
+     */
+    addTool(name: string, tool: ConversationTool): this;
+    /**
+     * Remove a tool by name.
+     */
+    removeTool(name: string): this;
+    /**
+     * Merge new tools into the conversation, replacing any with the same name.
+     * Accepts the same Record<string, ConversationTool> format used at construction time.
+     */
+    updateTools(tools: Record<string, ConversationTool>): this;
+    /**
+     * Register a hardcoded stub response that bypasses the API when the user's message matches.
+     * Streaming is still simulated — chunk/preview events fire word-by-word.
+     *
+     * @param matcher - Exact string match, substring, or RegExp tested against user input
+     * @param response - The text to stream back, or a zero-arg function that returns it
+     *
+     * @example
+     * conversation.stub('hello', 'Hi there!')
+     * conversation.stub(/weather/i, () => 'Sunny and 72°F.')
+     */
+    stub(matcher: string | RegExp, response: string | (() => string)): this;
+    /** Returns configured remote MCP servers keyed by server label. */
+    get mcpServers(): Record<string, ConversationMCPServer>;
+    /** Returns the full message history of the conversation. */
+    get messages(): Message[];
+    /** Returns the OpenAI model name being used for completions. */
+    get model(): string;
+    /** Returns the active completion API mode after resolving auto/local behavior. */
+    get apiMode(): 'responses' | 'chat';
+    /** Whether a streaming response is currently in progress. */
+    get isStreaming(): boolean;
+    /**
+     * Returns the correct parameter name for limiting output tokens.
+     * Local models (LM Studio, Ollama) and legacy OpenAI models use max_tokens.
+     * Newer OpenAI models (gpt-4o+, gpt-4.1, gpt-5, o1, o3, o4) require max_completion_tokens.
+     */
+    private get maxTokensParam();
+    /** The context window size for the current model (from options override or auto-detected). */
+    get contextWindow(): number;
+    /** Whether the conversation is approaching the context limit. */
+    get isNearContextLimit(): boolean;
+    /**
+     * Estimate the input token count for the current messages array
+     * using the js-tiktoken tokenizer. Updates state.
+     */
+    estimateTokens(): number;
+    /**
+     * Generate a summary of the conversation so far using the LLM.
+     * Read-only — does not modify messages.
+     */
+    summarize(): Promise<string>;
+    /**
+     * Compact the conversation by summarizing old messages and replacing them
+     * with a summary message. Keeps the system message (if any) and the most
+     * recent N messages.
+     */
+    compact(options?: {
+        keepRecent?: number;
+    }): Promise<{
+        summary: string;
+        removedCount: number;
+        estimatedTokens: number;
+    }>;
+    /**
+     * Get the OpenAI-formatted tools array from the registered tools.
+     *
+     * @returns {OpenAI.Chat.Completions.ChatCompletionTool[]} The tools formatted for OpenAI
+     */
+    private get openaiTools();
+    /**
+     * Get the OpenAI Responses-formatted tools array from local function tools
+     * plus configured remote MCP servers.
+     */
+    private get responseTools();
+    /** Returns the first system/developer text message to use as Responses instructions. */
+    private get responsesInstructions();
+    /**
+     * Send a message and get a streamed response. Automatically handles
+     * tool calls by invoking the registered handlers and feeding results
+     * back to the model until a final text response is produced.
+     *
+     * @param {string | ContentPart[]} content - The user message, either a string or array of content parts (text + images)
+     * @returns {Promise<string>} The assistant's final text response
+     *
+     * @example
+     * const reply = await conversation.ask("What's the weather in SF?")
+     * // With image:
+     * const reply = await conversation.ask([
+     *   { type: 'text', text: 'What is in this diagram?' },
+     *   { type: 'image_url', image_url: { url: 'data:image/png;base64,...' } }
+     * ])
+     */
+    ask(content: string | ContentPart[], options?: AskOptions): Promise<string>;
+    /** Convert user content into a Responses API input message item. */
+    private toResponsesUserMessage;
+    /**
+     * Convert the full Chat Completions message history into Responses API input items.
+     * Used when resuming a conversation without a previous_response_id.
+     */
+    private messagesToResponsesInput;
+    /**
+     * Build the OpenAI response_format / text.format config from the active Zod schema.
+     * Returns undefined when no schema is active.
+     */
+    private get structuredOutputConfig();
+    /** Returns the OpenAI client instance from the container. */
+    get openai(): OpenAIClient;
+    /** Returns the conversationHistory feature for persistence. */
+    get history(): ConversationHistory;
+    /**
+     * Persist this conversation to disk via conversationHistory.
+     * Creates a new record if this conversation hasn't been saved before,
+     * or updates the existing one.
+     *
+     * @param opts - Optional overrides for title, tags, thread, or metadata
+     * @returns The saved conversation record
+     */
+    save(opts?: {
+        title?: string;
+        tags?: string[];
+        thread?: string;
+        metadata?: Record<string, any>;
+    }): Promise<import("./conversation-history").ConversationRecord>;
+    /**
+     * Execute a single tool call, routing through the pluggable toolExecutor
+     * if one is set (e.g. by the Assistant's interceptor chain).
+     */
+    private executeTool;
+    /** Check registered stubs against user input. Returns the response text, or null if no match. */
+    private _matchStub;
+    /**
+     * Simulate a streaming response for a hardcoded stub text.
+     * Emits chunk/preview events word-by-word, yielding between each to keep the event loop alive.
+     */
+    private _streamStub;
+    /**
+     * Runs the streaming Responses API loop. Handles local function calls by
+     * executing handlers and submitting `function_call_output` items until
+     * the model produces a final text response.
+     */
+    private runResponsesLoop;
+    /** Apply Responses API usage stats to this conversation's token usage counters. */
+    private applyResponsesUsage;
+    /**
+     * Runs the streaming completion loop. If the model requests tool calls,
+     * executes them and loops again until a text response is produced.
+     *
+     * @returns {Promise<string>} The final assistant text response
+     */
+    /**
+     * Runs the streaming completion loop. If the model requests tool calls,
+     * executes them and loops again until a text response is produced.
+     *
+     * @param context - Turn tracking: turn number and text accumulated across all turns
+     * @returns {Promise<string>} The final assistant text response (accumulated across all turns)
+     */
+    private runChatCompletionLoop;
+    /**
+     * Append a message to the conversation state.
+     *
+     * @param {Message} message - The message to append
+     */
+    pushMessage(message: Message): void;
+}
+export default Conversation;
+//# sourceMappingURL=conversation.d.ts.map

package/dist/agi/features/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../../src/agi/features/conversation.ts"],"names":[],"mappings":"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"}

package/dist/agi/features/docs-reader.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import type { ContentDb } from '@/node.js';
+import type Assistant from './assistant.js';
+declare module '@soederpop/luca/feature' {
+    interface AvailableFeatures {
+        docsReader: typeof DocsReader;
+    }
+}
+export declare const DocsReaderStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    started: z.ZodBoolean;
+}, z.core.$loose>;
+export declare const DocsReaderOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    contentDb: z.ZodUnion<readonly [z.ZodString, z.ZodAny]>;
+    model: z.ZodDefault<z.ZodString>;
+    local: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const DocsReaderEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    loaded: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+export type DocsReaderState = z.infer<typeof DocsReaderStateSchema>;
+export type DocsReaderOptions = z.infer<typeof DocsReaderOptionsSchema>;
+/**
+ * The DocsReader feature is an AI Assisted wrapper around a ContentDB feature.
+ *
+ * You can ask it questions about the content, and it will use the ContentDB to find the answers
+ * from the documents.
+*/
+export declare class DocsReader extends Feature<DocsReaderState, DocsReaderOptions> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        started: z.ZodBoolean;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        contentDb: z.ZodUnion<readonly [z.ZodString, z.ZodAny]>;
+        model: z.ZodDefault<z.ZodString>;
+        local: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        loaded: z.ZodTuple<[], null>;
+    }, z.core.$strip>;
+    static shortcut: "features.docsReader";
+    /** @returns Default state with started=false. */
+    get initialState(): DocsReaderState;
+    /** Whether the docs reader has been started. */
+    get isStarted(): boolean;
+    calculateCacheKeyForQuestion(question: string): string;
+    get answerCache(): import("@/node.js").DiskCache;
+    get contentDb(): ContentDb;
+    ask(question: string): Promise<string>;
+    askCached(question: string): Promise<any>;
+    assistant?: Assistant;
+    private generateSpecificCollectionExplainer;
+    /** Start the docs reader by loading the contentDb and wiring its tools into an assistant. */
+    start(): Promise<DocsReader>;
+}
+export default DocsReader;
+export declare const CONTENT_DB_SYSTEM_PROMPT = "You answer questions using a collection of structured documents. Follow this workflow:\n\n1. Start with getCollectionOverview to understand the collection structure, available models, and document counts\n2. Use listDocuments or queryDocuments to find relevant documents by model, glob pattern, or metadata filters\n3. Use searchContent for text/regex search or semanticSearch for natural language queries\n4. Use readDocument to read specific documents \u2014 use include/exclude to focus on relevant sections and avoid loading unnecessary content\n5. Synthesize your answer from the documents you've read\n\nBe precise: read only what you need, use section filtering to stay focused, and cite document IDs in your answers.";
+//# sourceMappingURL=docs-reader.d.ts.map

package/dist/agi/features/docs-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-reader.d.ts","sourceRoot":"","sources":["../../../src/agi/features/docs-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C,OAAO,QAAQ,yBAAyB,CAAC;IACxC,UAAU,iBAAiB;QAC1B,UAAU,EAAE,OAAO,UAAU,CAAA;KAC7B;CACD;AAED,eAAO,MAAM,qBAAqB;;;iBAEhC,CAAA;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;iBAO1B,CAAA;AAEV,eAAO,MAAM,sBAAsB;;;;iBAEH,CAAA;AAEhC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AACnE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE;;;;;EAKE;AACF,qBAAa,UAAW,SAAQ,OAAO,CAAC,eAAe,EAAE,iBAAiB,CAAC;IAC1E,OAAgB,WAAW;;;sBAAwB;IACnD,OAAgB,aAAa;;;;;;;;sBAA0B;IACvD,OAAgB,YAAY;;;;sBAAyB;IACrD,OAAgB,QAAQ,EAAG,qBAAqB,CAAS;IAIzD,iDAAiD;IACjD,IAAa,YAAY,IAAI,eAAe,CAK3C;IAED,gDAAgD;IAChD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,4BAA4B,CAAC,QAAQ,EAAE,MAAM;IAO7C,IAAI,WAAW,kCAEd;IAED,IAAI,SAAS,IAAK,SAAS,CAI1B;IAEK,GAAG,CAAC,QAAQ,EAAE,MAAM;IAYpB,SAAS,CAAC,QAAQ,EAAE,MAAM;IAoBhC,SAAS,CAAC,EAAE,SAAS,CAAA;IAGrB,OAAO,CAAC,mCAAmC;IAsB3C,6FAA6F;IACvF,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;CAmBlC;AAED,eAAe,UAAU,CAAA;AAEzB,eAAO,MAAM,wBAAwB,ytBAQ8E,CAAA"}

package/dist/agi/features/file-tools.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import type { Helper } from '../../helper.js';
+declare module '@soederpop/luca/feature' {
+    interface AvailableFeatures {
+        fileTools: typeof FileTools;
+    }
+}
+export declare const FileToolsStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const FileToolsOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Curated file-system and code-search tools for AI assistants.
+ *
+ * Wraps the container's `fs` and `grep` features into a focused tool surface
+ * modeled on the tools that coding assistants (Claude Code, Cursor, etc.) rely on:
+ * read, write, edit, list, search, find, stat, mkdir, move, copy, delete.
+ *
+ * Usage:
+ * ```typescript
+ * const fileTools = container.feature('fileTools')
+ * assistant.use(fileTools)
+ * // or selectively:
+ * assistant.use(fileTools.toTools({ only: ['readFile', 'searchFiles', 'listDirectory'] }))
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class FileTools extends Feature {
+    static shortcut: "features.fileTools";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static tools: Record<string, {
+        schema: z.ZodType;
+        description?: string;
+    }>;
+    private get fs();
+    private get grep();
+    readFile(args: {
+        path: string;
+        offset?: number;
+        limit?: number;
+    }): Promise<string>;
+    writeFile(args: {
+        path: string;
+        content: string;
+    }): Promise<string>;
+    editFile(args: {
+        path: string;
+        oldString: string;
+        newString: string;
+        replaceAll?: boolean;
+    }): Promise<string>;
+    listDirectory(args: {
+        path?: string;
+        recursive?: boolean;
+        include?: string;
+        exclude?: string;
+    }): Promise<string>;
+    searchFiles(args: {
+        pattern: string;
+        path?: string;
+        include?: string;
+        exclude?: string;
+        ignoreCase?: boolean;
+        maxResults?: number;
+    }): Promise<string>;
+    findFiles(args: {
+        pattern: string;
+        path?: string;
+        exclude?: string;
+    }): Promise<string>;
+    fileInfo(args: {
+        path: string;
+    }): Promise<string>;
+    createDirectory(args: {
+        path: string;
+    }): Promise<string>;
+    moveFile(args: {
+        source: string;
+        destination: string;
+    }): Promise<string>;
+    copyFile(args: {
+        source: string;
+        destination: string;
+    }): Promise<string>;
+    deleteFile(args: {
+        path: string;
+    }): Promise<string>;
+    /**
+     * When an assistant uses fileTools, inject system prompt guidance
+     * about how to use the tools effectively.
+     */
+    setupToolsConsumer(consumer: Helper): void;
+}
+export default FileTools;
+//# sourceMappingURL=file-tools.d.ts.map

package/dist/agi/features/file-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-tools.d.ts","sourceRoot":"","sources":["../../../src/agi/features/file-tools.ts"],"names":[],"mappings":"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"}