@soederpop/luca 0.0.5 → 0.0.7

package/docs/apis/clients/websocket.md

@@ -1,6 +1,6 @@
 # WebSocketClient (clients.websocket)
 
-No description provided
+WebSocket client that bridges raw WebSocket events to Luca's Helper event bus, providing a clean interface for sending/receiving messages, tracking connection state, and optional auto-reconnection with exponential backoff. Events emitted: - `open` — connection established - `message` — message received (JSON-parsed when possible) - `close` — connection closed (with code and reason) - `error` — connection error - `reconnecting` — attempting reconnection (with attempt number)
 
 ## Usage
 
@@ -29,17 +29,61 @@ container.client('websocket', {
 | `reconnectInterval` | `number` | Base interval in milliseconds between reconnection attempts |
 | `maxReconnectAttempts` | `number` | Maximum number of reconnection attempts before giving up |
 
+## Methods
+
+### connect
+
+Establish a WebSocket connection to the configured baseURL. Wires all raw WebSocket events (open, message, close, error) to the Helper event bus and updates connection state accordingly. Resolves once the connection is open; rejects on error.
+
+**Returns:** `Promise<this>`
+
+
+
+### send
+
+Send data over the WebSocket connection. Automatically JSON-serializes the payload. If not currently connected, attempts to connect first.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | `any` | ✓ | The data to send (will be JSON.stringify'd) |
+
+**Returns:** `Promise<void>`
+
+
+
+### disconnect
+
+Gracefully close the WebSocket connection. Suppresses auto-reconnect and updates connection state to disconnected.
+
+**Returns:** `Promise<this>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hasError` | `any` | Whether the client is in an error state. |
+
 ## Events (Zod v4 schema)
 
-### failure
+### open
 
-Emitted when a request fails
+Emitted when the WebSocket connection is established
+
+
+
+### error
+
+Emitted when a WebSocket error occurs
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | The error object |
+| `arg0` | `any` | The error |
 
 
 
@@ -55,12 +99,6 @@ Emitted when a message is received
 
 
 
-### open
-
-Emitted when the WebSocket connection is established
-
-
-
 ### close
 
 Emitted when the WebSocket connection is closed
@@ -74,27 +112,27 @@ Emitted when the WebSocket connection is closed
 
 
 
-### error
+### reconnecting
 
-Emitted when a WebSocket error occurs
+Emitted when attempting to reconnect
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `any` | The error |
+| `arg0` | `number` | Attempt number |
 
 
 
-### reconnecting
+### failure
 
-Emitted when attempting to reconnect
+Emitted when a request fails
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `number` | Attempt number |
+| `arg0` | `any` | The error object |
 
 
 
@@ -104,4 +142,20 @@ Emitted when attempting to reconnect
 |----------|------|-------------|
 | `connected` | `boolean` | Whether the client is currently connected |
 | `connectionError` | `any` | The last connection error, if any |
-| `reconnectAttempts` | `number` | Number of reconnection attempts made |
+| `reconnectAttempts` | `number` | Number of reconnection attempts made |
+
+## Examples
+
+**clients.websocket**
+
+```ts
+const ws = container.client('websocket', {
+ baseURL: 'ws://localhost:8080',
+ reconnect: true,
+ maxReconnectAttempts: 5
+})
+ws.on('message', (data) => console.log('Received:', data))
+await ws.connect()
+await ws.send({ type: 'hello' })
+```
+

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

@@ -1,6 +1,6 @@
 # Assistant (features.assistant)
 
-No description provided
+An Assistant is a combination of a system prompt and tool calls that has a conversation with an LLM. You define an assistant by creating a folder with CORE.md (system prompt), tools.ts (tool implementations), and hooks.ts (event handlers).
 
 ## Usage
 
@@ -22,6 +22,8 @@ container.feature('assistant', {
   model,
   // Maximum number of output tokens per completion
   maxTokens,
+  // Whether to use our local models for this
+  local,
   // Conversation history persistence mode
   historyMode,
 })
@@ -39,6 +41,7 @@ container.feature('assistant', {
 | `schemas` | `object` | Override or extend schemas whose keys match tool names |
 | `model` | `string` | OpenAI model to use |
 | `maxTokens` | `number` | Maximum number of output tokens per completion |
+| `local` | `boolean` | Whether to use our local models for this |
 | `historyMode` | `string` | Conversation history persistence mode |
 
 ## Methods
@@ -242,6 +245,7 @@ Save the conversation to disk via conversationHistory.
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `name` | `any` |  |
 | `resolvedFolder` | `string` | The absolute resolved path to the assistant folder. |
 | `corePromptPath` | `string` | The path to CORE.md which provides the system prompt. |
 | `toolsModulePath` | `string` | The path to tools.ts which provides tool implementations and schemas. |
@@ -290,7 +294,8 @@ Emitted when a new completion turn begins. isFollowUp is true when resuming afte
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `object` |  |
+| `turn` | `number` |  |
+| `isFollowUp` | `boolean` |  |
 
 
 
@@ -302,7 +307,8 @@ Emitted when a completion turn ends. hasToolCalls indicates whether tool calls w
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `object` |  |
+| `turn` | `number` |  |
+| `hasToolCalls` | `boolean` |  |
 
 
 

package/docs/apis/features/agi/assistants-manager.md

@@ -1,6 +1,6 @@
 # AssistantsManager (features.assistantsManager)
 
-No description provided
+Discovers and manages assistant definitions by finding all CORE.md files in the project using the fileManager. Each directory containing a CORE.md is treated as an assistant definition that can also contain tools.ts, hooks.ts, voice.yaml, and a docs/ folder. Use `discover()` to scan for available assistants, `list()` to enumerate them, and `create(name)` to instantiate one as a running Assistant feature.
 
 ## Usage
 
@@ -29,7 +29,7 @@ container.feature('assistantsManager', {
 
 Discovers assistants by finding all CORE.md files in the project using the fileManager. Each directory containing a CORE.md is treated as an assistant definition.
 
-**Returns:** `this`
+**Returns:** `Promise<this>`
 
 
 

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

@@ -1,11 +1,13 @@
 # ClaudeCode (features.claudeCode)
 
-No description provided
+Claude Code CLI wrapper feature. Spawns and manages Claude Code sessions as subprocesses, streaming structured JSON events back through the container's event system. Sessions are long-lived: each call to `run()` spawns a `claude -p` process with `--output-format stream-json`, parses NDJSON from stdout line-by-line, and emits typed events on the feature's event bus.
 
 ## Usage
 
 ```ts
 container.feature('claudeCode', {
+  // Claude CLI session ID to resume by default
+  session,
   // Path to the claude CLI binary
   claudePath,
   // Default model to use for sessions
@@ -57,6 +59,7 @@ container.feature('claudeCode', {
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `session` | `string` | Claude CLI session ID to resume by default |
 | `claudePath` | `string` | Path to the claude CLI binary |
 | `model` | `string` | Default model to use for sessions |
 | `cwd` | `string` | Default working directory for sessions |
@@ -356,6 +359,31 @@ const sessionStats = cc.usage(sessionId)
 
 
 
+### sessionHistoryToMarkdown
+
+Export session history as a readable markdown document. Reads from a raw JSONL file (Claude CLI session log or this feature's NDJSON log) so it works independently of in-memory state. Can also accept a local session ID to export from in-memory state as a fallback.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source` | `string` |  | Path to a JSONL file, a local session ID, or omit for the most recent session |
+
+**Returns:** `Promise<string>`
+
+```ts
+// From a JSONL file (works without any prior state)
+const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
+
+// From the most recent in-memory session
+const md = await cc.sessionHistoryToMarkdown()
+
+// From a specific local session ID
+const md = await cc.sessionHistoryToMarkdown(localSessionId)
+```
+
+
+
 ### cleanupMcpTempFiles
 
 Clean up any temp MCP config files created during sessions.
@@ -382,80 +410,166 @@ Initialize the feature.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `claudePath` | `string` | Resolve the path to the claude CLI binary. |
+| `claudePath` | `string` |  |
 | `parsedVersion` | `{ major: number; minor: number; patch: number } | undefined` | Parsed semver components from the detected CLI version, or undefined if not yet checked. |
+| `sessionId` | `string | undefined` | The Claude CLI session ID of the most recently initialized session, or the session set via the `session` option. Useful for resuming later. |
 
 ## Events (Zod v4 schema)
 
 ### session:warning
 
-Event emitted by ClaudeCode
+Fired when the log reader encounters a warning
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `message` | `string` |  |
 
 
 
 ### session:log-error
 
-Event emitted by ClaudeCode
+Fired when the log reader encounters an error
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `error` | `any` |  |
 
 
 
 ### session:event
 
-Event emitted by ClaudeCode
+Fired for every parsed JSON event from the CLI stream
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `event` | `any` |  |
 
 
 
 ### session:init
 
-Event emitted by ClaudeCode
+Fired when the CLI emits its init system event
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `init` | `any` |  |
 
 
 
 ### session:delta
 
-Event emitted by ClaudeCode
+Fired for each text delta from an assistant message
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `text` | `string` |  |
+| `role` | `string` |  |
 
 
 
 ### session:stream
 
-Event emitted by ClaudeCode
+Fired for stream_event type events from the CLI
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `streamEvent` | `any` |  |
 
 
 
 ### session:message
 
-Event emitted by ClaudeCode
+Fired when a complete assistant message is received
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `message` | `any` |  |
 
 
 
 ### session:result
 
-Event emitted by ClaudeCode
+Fired when a session completes with a final result
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `result` | `string` |  |
 
 
 
 ### session:start
 
-Event emitted by ClaudeCode
+Fired when a new Claude Code session is spawned
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `prompt` | `string` |  |
 
 
 
 ### session:error
 
-Event emitted by ClaudeCode
+Fired when a session encounters an error
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `error` | `any` |  |
+| `exitCode` | `number` |  |
 
 
 
 ### session:parse-error
 
-Event emitted by ClaudeCode
+Fired when a JSON line from the CLI cannot be parsed
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
+| `line` | `string` |  |
 
 
 
 ### session:abort
 
-Event emitted by ClaudeCode
+Fired when a session is aborted by the user
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` |  |
 
 
 
@@ -600,3 +714,28 @@ console.log(`Tokens: ${stats.totalInputTokens} in / ${stats.totalOutputTokens} o
 const sessionStats = cc.usage(sessionId)
 ```
 
+
+
+**sessionHistoryToMarkdown**
+
+```ts
+// From a JSONL file (works without any prior state)
+const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
+
+// From the most recent in-memory session
+const md = await cc.sessionHistoryToMarkdown()
+
+// From a specific local session ID
+const md = await cc.sessionHistoryToMarkdown(localSessionId)
+```
+
+
+
+**sessionId**
+
+```ts
+const cc = container.feature('claudeCode')
+await cc.run('Do something')
+console.log(cc.sessionId) // the Claude CLI session ID
+```
+

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

@@ -1,6 +1,6 @@
 # ConversationHistory (features.conversationHistory)
 
-No description provided
+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
 
@@ -314,13 +314,25 @@ Delete all conversations matching a thread prefix.
 
 ### saved
 
-Event emitted by ConversationHistory
+Fired after a conversation record is persisted
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The conversation ID that was saved |
 
 
 
 ### deleted
 
-Event emitted by ConversationHistory
+Fired after a conversation record is deleted
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The conversation ID that was deleted |