@soederpop/luca 0.0.31 → 0.0.34

package/docs/apis/features/agi/claude-code.md

@@ -52,6 +52,8 @@ container.feature('claudeCode', {
   settingsFile,
   // Directories containing Claude Code skills to load into sessions
   skillsFolders,
+  // Launch Claude Code with a Chrome browser tool
+  chrome,
 })
 ```
 
@@ -82,6 +84,7 @@ container.feature('claudeCode', {
 | `strictMcpConfig` | `boolean` | Require strict MCP config validation |
 | `settingsFile` | `string` | Path to a custom settings file |
 | `skillsFolders` | `array` | Directories containing Claude Code skills to load into sessions |
+| `chrome` | `boolean` | Launch Claude Code with a Chrome browser tool |
 
 ## Methods
 
@@ -180,6 +183,7 @@ Run a prompt in a new Claude Code session. Spawns a subprocess, streams NDJSON e
 | `debug` | `string | boolean` | Enable debug output. Pass a string for specific debug channels, or true for all. |
 | `debugFile` | `string` | Path to write debug output to a file. |
 | `settingsFile` | `string` | Path to a custom settings file. |
+| `chrome` | `boolean` | Launch Claude Code with a Chrome browser tool. |
 
 **Returns:** `Promise<ClaudeSession>`
 
@@ -258,6 +262,7 @@ Run a prompt without waiting for completion. Returns the session ID immediately
 | `debug` | `string | boolean` | Enable debug output. Pass a string for specific debug channels, or true for all. |
 | `debugFile` | `string` | Path to write debug output to a file. |
 | `settingsFile` | `string` | Path to a custom settings file. |
+| `chrome` | `boolean` | Launch Claude Code with a Chrome browser tool. |
 
 **Returns:** `Promise<string>`
 
@@ -346,7 +351,7 @@ Get aggregated usage statistics across all sessions, or for a specific session.
 |------|------|----------|-------------|
 | `sessionId` | `string` |  | Optional session ID to get usage for a single session |
 
-**Returns:** `void`
+**Returns:** `{ totalCostUsd: number; totalInputTokens: number; totalOutputTokens: number; totalCacheReadTokens: number; totalCacheCreationTokens: number; totalTurns: number; sessionCount: number; sessions: Array<{ id: string; costUsd: number; turns: number; inputTokens: number; outputTokens: number; status: string`
 
 ```ts
 const stats = cc.usage()

package/docs/apis/features/agi/conversation-history.md

@@ -1,14 +1,14 @@
 # ConversationHistory (features.conversationHistory)
 
-A queryable store, backed by the file system, for maintaining conversation history and easily restoring it. Each conversation is stored as a JSON record keyed by ID, with lightweight metadata stored alongside for efficient listing and search without loading full message arrays.
+Persists conversations to disk using the diskCache feature (cacache). Each conversation is stored as a JSON blob keyed by ID, with metadata stored alongside for efficient listing and search without loading full message arrays.
 
 ## Usage
 
 ```ts
 container.feature('conversationHistory', {
-  // Directory for conversation storage
+  // Custom cache directory for conversation storage
   cachePath,
-  // Namespace prefix to isolate datasets
+  // Namespace prefix for cache keys to isolate datasets
   namespace,
 })
 ```
@@ -17,8 +17,8 @@ container.feature('conversationHistory', {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `cachePath` | `string` | Directory for conversation storage |
-| `namespace` | `string` | Namespace prefix to isolate datasets |
+| `cachePath` | `string` | Custom cache directory for conversation storage |
+| `namespace` | `string` | Namespace prefix for cache keys to isolate datasets |
 
 ## Methods
 
@@ -307,7 +307,8 @@ Delete all conversations matching a thread prefix.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `namespace` | `string` | The namespace prefix used for key isolation |
+| `diskCache` | `DiskCache` |  |
+| `namespace` | `string` |  |
 
 ## Events (Zod v4 schema)
 

package/docs/apis/features/agi/conversation.md

@@ -1,6 +1,6 @@
 # Conversation (features.conversation)
 
-An observable conversation class that enables long-running chat threads with an LLM. Supports streaming responses, tool calling with automatic handler dispatch, message state management, and context window compaction. Works with both local (Ollama) and remote (OpenAI) backends.
+A self-contained conversation with OpenAI that supports streaming, tool calling, and message state management.
 
 ## Usage
 
@@ -30,8 +30,20 @@ container.feature('conversation', {
   clientOptions,
   // Whether to use the local ollama models instead of the remote OpenAI models
   local,
-  // Maximum number of output tokens per completion
+  // Maximum number of output tokens per completion (default 512)
   maxTokens,
+  // Sampling temperature (0-2). Higher = more random, lower = more deterministic
+  temperature,
+  // Nucleus sampling cutoff (0-1). Lower = more focused
+  topP,
+  // Top-K sampling. Only supported by local/Anthropic models
+  topK,
+  // Frequency penalty (-2 to 2). Positive = discourage repetition
+  frequencyPenalty,
+  // Presence penalty (-2 to 2). Positive = encourage new topics
+  presencePenalty,
+  // Stop sequences — generation halts when any of these strings is produced
+  stop,
   // Enable automatic compaction when input tokens approach the context limit
   autoCompact,
   // Fraction of context window at which auto-compact triggers (default 0.8)
@@ -59,7 +71,13 @@ container.feature('conversation', {
 | `metadata` | `object` | Arbitrary metadata to attach to this conversation |
 | `clientOptions` | `object` | Options for the OpenAI client |
 | `local` | `boolean` | Whether to use the local ollama models instead of the remote OpenAI models |
-| `maxTokens` | `number` | Maximum number of output tokens per completion |
+| `maxTokens` | `number` | Maximum number of output tokens per completion (default 512) |
+| `temperature` | `number` | Sampling temperature (0-2). Higher = more random, lower = more deterministic |
+| `topP` | `number` | Nucleus sampling cutoff (0-1). Lower = more focused |
+| `topK` | `number` | Top-K sampling. Only supported by local/Anthropic models |
+| `frequencyPenalty` | `number` | Frequency penalty (-2 to 2). Positive = discourage repetition |
+| `presencePenalty` | `number` | Presence penalty (-2 to 2). Positive = encourage new topics |
+| `stop` | `array` | Stop sequences — generation halts when any of these strings is produced |
 | `autoCompact` | `boolean` | Enable automatic compaction when input tokens approach the context limit |
 | `compactThreshold` | `number` | Fraction of context window at which auto-compact triggers (default 0.8) |
 | `contextWindow` | `number` | Override the inferred context window size for this model |
@@ -67,6 +85,57 @@ container.feature('conversation', {
 
 ## Methods
 
+### addTool
+
+Add or replace a single tool by name. Uses the same format as tools passed at construction time.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Parameter name |
+| `tool` | `ConversationTool` | ✓ | Parameter tool |
+
+`ConversationTool` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `handler` | `(...args: any[]) => Promise<any>` |  |
+| `description` | `string` |  |
+| `parameters` | `Record<string, any>` |  |
+
+**Returns:** `this`
+
+
+
+### removeTool
+
+Remove a tool by name.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Parameter name |
+
+**Returns:** `this`
+
+
+
+### updateTools
+
+Merge new tools into the conversation, replacing any with the same name. Accepts the same Record<string, ConversationTool> format used at construction time.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `tools` | `Record<string, ConversationTool>` | ✓ | Parameter tools |
+
+**Returns:** `this`
+
+
+
 ### estimateTokens
 
 Estimate the input token count for the current messages array using the js-tiktoken tokenizer. Updates state.
@@ -113,6 +182,7 @@ Send a message and get a streamed response. Automatically handles tool calls by
 | Property | Type | Description |
 |----------|------|-------------|
 | `maxTokens` | `number` |  |
+| `schema` | `z.ZodType` | 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. |
 
 **Returns:** `Promise<string>`
 
@@ -159,7 +229,8 @@ Append a message to the conversation state.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `tools` | `Record<string, any>` | Returns the registered tools available for the model to call. |
+| `tools` | `Record<string, ConversationTool>` | Returns the registered tools available for the model to call. |
+| `availableTools` | `any` |  |
 | `mcpServers` | `Record<string, ConversationMCPServer>` | Returns configured remote MCP servers keyed by server label. |
 | `messages` | `Message[]` | Returns the full message history of the conversation. |
 | `model` | `string` | Returns the OpenAI model name being used for completions. |
@@ -244,127 +315,127 @@ Fired when a user message is added to the conversation
 
 
 
-### turnStart
+### toolError
 
-Fired at the start of each completion turn
+Fired when a tool handler throws or the tool is unknown
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `turn` | `number` |  |
-| `isFollowUp` | `boolean` |  |
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Error object or message |
 
 
 
-### rawEvent
+### toolCall
 
-Fired for every raw event from the Responses API stream
+Fired before invoking a single tool handler
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | Raw stream event from the API |
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Parsed arguments object |
 
 
 
-### mcpEvent
+### toolResult
 
-Fired for MCP-related events from the Responses API
+Fired after a tool handler returns successfully
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | MCP-related stream event |
+| `arg0` | `string` | Tool name |
+| `arg1` | `string` | Serialized result |
 
 
 
-### chunk
+### turnStart
 
-Fired for each streaming text delta
+Fired at the start of each completion turn
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `string` | Text delta from the stream |
+| `turn` | `number` |  |
+| `isFollowUp` | `boolean` |  |
 
 
 
-### preview
+### rawEvent
 
-Fired after each chunk with the full accumulated text
+Fired for every raw event from the Responses API stream
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `string` | Accumulated text so far |
+| `arg0` | `any` | Raw stream event from the API |
 
 
 
-### responseCompleted
+### mcpEvent
 
-Fired when the Responses API stream completes
+Fired for MCP-related events from the Responses API
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | The completed OpenAI Response object |
+| `arg0` | `any` | MCP-related stream event |
 
 
 
-### toolCallsStart
+### chunk
 
-Fired when the model begins a batch of tool calls
+Fired for each streaming text delta
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | Array of tool call objects from the model |
+| `arg0` | `string` | Text delta from the stream |
 
 
 
-### toolError
+### preview
 
-Fired when a tool handler throws or the tool is unknown
+Fired after each chunk with the full accumulated text
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Error object or message |
+| `arg0` | `string` | Accumulated text so far |
 
 
 
-### toolCall
+### responseCompleted
 
-Fired before invoking a single tool handler
+Fired when the Responses API stream completes
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Parsed arguments object |
+| `arg0` | `any` | The completed OpenAI Response object |
 
 
 
-### toolResult
+### toolCallsStart
 
-Fired after a tool handler returns successfully
+Fired when the model begins a batch of tool calls
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `string` | Serialized result |
+| `arg0` | `any` | Array of tool call objects from the model |
 
 
 
@@ -417,6 +488,8 @@ Fired when the final text response is produced
 | `estimatedInputTokens` | `number` | Estimated input token count for the current messages array |
 | `compactionCount` | `number` | Number of times compact() has been called |
 | `contextWindow` | `number` | The context window size for the current model |
+| `tools` | `object` | Active tools map including any runtime overrides |
+| `callMaxTokens` | `any` | Per-call max tokens override, cleared after each ask() |
 
 ## Examples
 

package/docs/apis/features/agi/docs-reader.md

@@ -1,17 +1,17 @@
 # DocsReader (features.docsReader)
 
-No description provided
+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.
 
 ## Usage
 
 ```ts
 container.feature('docsReader', {
-  // A ContentDb instance to read documents from
+  // Either the contentDb instance or the path to the contentDb you want to load
   contentDb,
-  // Optional system prompt to prepend before the docs listing
-  systemPrompt,
-  // OpenAI model to use for the conversation
+  // The model to use for the conversation
   model,
+  // Whether to use a local model for the conversation
+  local,
 })
 ```
 
@@ -19,55 +19,53 @@ container.feature('docsReader', {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `contentDb` | `any` | A ContentDb instance to read documents from |
-| `systemPrompt` | `string` | Optional system prompt to prepend before the docs listing |
-| `model` | `string` | OpenAI model to use for the conversation |
+| `contentDb` | `any` | Either the contentDb instance or the path to the contentDb you want to load |
+| `model` | `string` | The model to use for the conversation |
+| `local` | `boolean` | Whether to use a local model for the conversation |
 
 ## Methods
 
-### buildTools
-
-Build the tool definitions (listDocs, readDoc, readDocOutline, readDocs) that the conversation model uses to query the content database.
-
-**Returns:** `Record<string, ConversationTool>`
+### calculateCacheKeyForQuestion
 
+**Parameters:**
 
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `string` | ✓ | Parameter question |
 
-### buildSystemPrompt
+**Returns:** `void`
 
-Build the system prompt by combining the optional prefix with a table of contents generated from the content database.
 
-**Returns:** `string`
 
+### ask
 
+**Parameters:**
 
-### createConversation
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `string` | ✓ | Parameter question |
 
-Create and return a new Conversation feature configured with the docs reader's system prompt and tools.
+**Returns:** `void`
 
-**Returns:** `Conversation`
 
 
+### askCached
 
-### start
+**Parameters:**
 
-Initialize the docs reader by loading the content database, creating the conversation, and emitting the start event.
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `string` | ✓ | Parameter question |
 
 **Returns:** `void`
 
 
 
-### ask
-
-Ask the docs reader a question. It will read relevant documents and return an answer based on their content.
-
-**Parameters:**
+### start
 
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `question` | `string` | ✓ | The question to ask |
+Start the docs reader by loading the contentDb and wiring its tools into an assistant.
 
-**Returns:** `void`
+**Returns:** `Promise<DocsReader>`
 
 
 
@@ -75,26 +73,21 @@ Ask the docs reader a question. It will read relevant documents and return an an
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `contentDb` | `ContentDb` | The ContentDb instance this reader draws from. |
-| `isStarted` | `any` | Whether the reader has been started and is ready to answer questions. |
+| `isStarted` | `boolean` | Whether the docs reader has been started. |
+| `answerCache` | `any` |  |
+| `contentDb` | `ContentDb` |  |
 
 ## Events (Zod v4 schema)
 
-### start
-
-Event emitted by DocsReader
-
-
-
-### preview
+### started
 
 Event emitted by DocsReader
 
 
 
-### answered
+### loaded
 
-Event emitted by DocsReader
+Fired after the docs reader has been started
 
 
 
@@ -103,19 +96,4 @@ Event emitted by DocsReader
 | Property | Type | Description |
 |----------|------|-------------|
 | `enabled` | `boolean` | Whether this feature is currently enabled |
-| `started` | `boolean` | Whether the docs reader has been initialized |
-| `docsLoaded` | `boolean` | Whether the content database has been loaded |
-
-## Examples
-
-**features.docsReader**
-
-```ts
-const reader = container.feature('docsReader', {
- contentDb: myContentDb,
- model: 'gpt-4.1'
-})
-await reader.start()
-const answer = await reader.ask('How does authentication work?')
-```
-
+| `started` | `boolean` | Whether the docs reader has been started |

package/docs/apis/features/agi/file-tools.md

@@ -0,0 +1,163 @@
+# FileTools (features.fileTools)
+
+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'] })) ```
+
+## Usage
+
+```ts
+container.feature('fileTools')
+```
+
+## Methods
+
+### readFile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path: string; offset?: number; limit?: number }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### writeFile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path: string; content: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### editFile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path: string; oldString: string; newString: string; replaceAll?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### listDirectory
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path?: string; recursive?: boolean; include?: string; exclude?: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### searchFiles
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ pattern: string; path?: string; include?: string; exclude?: string; ignoreCase?: boolean; maxResults?: number }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### findFiles
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ pattern: string; path?: string; exclude?: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### fileInfo
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### createDirectory
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### moveFile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ source: string; destination: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### copyFile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ source: string; destination: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### deleteFile
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ path: string }` | ✓ | Parameter args |
+
+**Returns:** `Promise<string>`
+
+
+
+### setupToolsConsumer
+
+When an assistant uses fileTools, inject system prompt guidance about how to use the tools effectively.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `consumer` | `Helper` | ✓ | Parameter consumer |
+
+**Returns:** `void`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |