@soederpop/luca 0.0.2

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

@@ -0,0 +1,121 @@
+# DocsReader (features.docsReader)
+
+No description provided
+
+## Usage
+
+```ts
+container.feature('docsReader', {
+  // A ContentDb instance to read documents from
+  contentDb,
+  // Optional system prompt to prepend before the docs listing
+  systemPrompt,
+  // OpenAI model to use for the conversation
+  model,
+})
+```
+
+## Options (Zod v4 schema)
+
+| 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 |
+
+## Methods
+
+### buildTools
+
+Build the tool definitions (listDocs, readDoc, readDocOutline, readDocs) that the conversation model uses to query the content database.
+
+**Returns:** `Record<string, ConversationTool>`
+
+
+
+### buildSystemPrompt
+
+Build the system prompt by combining the optional prefix with a table of contents generated from the content database.
+
+**Returns:** `string`
+
+
+
+### createConversation
+
+Create and return a new Conversation feature configured with the docs reader's system prompt and tools.
+
+**Returns:** `Conversation`
+
+
+
+### start
+
+Initialize the docs reader by loading the content database, creating the conversation, and emitting the start event.
+
+**Returns:** `void`
+
+
+
+### ask
+
+Ask the docs reader a question. It will read relevant documents and return an answer based on their content.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `string` | ✓ | The question to ask |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| 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. |
+
+## Events (Zod v4 schema)
+
+### start
+
+Event emitted by DocsReader
+
+
+
+### preview
+
+Event emitted by DocsReader
+
+
+
+### answered
+
+Event emitted by DocsReader
+
+
+
+## State (Zod v4 schema)
+
+| 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?')
+```
+

package/docs/apis/features/agi/openai-codex.md

@@ -0,0 +1,318 @@
+# OpenAICodex (features.openaiCodex)
+
+No description provided
+
+## Usage
+
+```ts
+container.feature('openaiCodex', {
+  // Path to the codex CLI binary
+  codexPath,
+  // Default model to use for sessions
+  model,
+  // Default working directory for sessions
+  cwd,
+  // Sandbox policy for shell commands
+  sandbox,
+  // Approval mode for codex operations
+  approvalMode,
+  // Path to additional project doc to include
+  projectDoc,
+  // Disable automatic codex.md inclusion
+  noProjectDoc,
+  // Do not truncate stdout/stderr from command outputs
+  fullStdout,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `codexPath` | `string` | Path to the codex CLI binary |
+| `model` | `string` | Default model to use for sessions |
+| `cwd` | `string` | Default working directory for sessions |
+| `sandbox` | `string` | Sandbox policy for shell commands |
+| `approvalMode` | `string` | Approval mode for codex operations |
+| `projectDoc` | `string` | Path to additional project doc to include |
+| `noProjectDoc` | `boolean` | Disable automatic codex.md inclusion |
+| `fullStdout` | `boolean` | Do not truncate stdout/stderr from command outputs |
+
+## Methods
+
+### checkAvailability
+
+Check if the Codex CLI is available and capture its version.
+
+**Returns:** `Promise<boolean>`
+
+
+
+### run
+
+Run a prompt in a new Codex session. Spawns a subprocess, streams NDJSON events, and resolves when the session completes.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `prompt` | `string` | ✓ | The natural language instruction for the Codex agent |
+| `options` | `CodexRunOptions` |  | Optional overrides for model, cwd, sandbox policy, etc. |
+
+`CodexRunOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `model` | `string` |  |
+| `cwd` | `string` |  |
+| `sandbox` | `'read-only' | 'workspace-write' | 'danger-full-access'` |  |
+| `approvalMode` | `'suggest' | 'auto-edit' | 'full-auto'` |  |
+| `projectDoc` | `string` |  |
+| `noProjectDoc` | `boolean` |  |
+| `fullStdout` | `boolean` |  |
+| `images` | `string[]` |  |
+| `fullAuto` | `boolean` |  |
+| `resumeSessionId` | `string` | Resume a previous session by ID. |
+| `resumeLast` | `boolean` | Resume the most recent session. |
+| `dangerouslyAutoApproveEverything` | `boolean` | Skip all approvals and sandboxing. |
+| `extraArgs` | `string[]` | Additional CLI flags. |
+
+**Returns:** `Promise<CodexSession>`
+
+```ts
+const session = await codex.run('Fix the failing tests')
+console.log(session.result)
+
+const session = await codex.run('Refactor the auth module', {
+ model: 'o4-mini',
+ fullAuto: true,
+ cwd: '/path/to/project'
+})
+```
+
+
+
+### start
+
+Run a prompt without waiting for completion. Returns the session ID immediately so you can subscribe to events.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `prompt` | `string` | ✓ | The natural language instruction for the Codex agent |
+| `options` | `CodexRunOptions` |  | Optional overrides for model, cwd, sandbox policy, etc. |
+
+`CodexRunOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `model` | `string` |  |
+| `cwd` | `string` |  |
+| `sandbox` | `'read-only' | 'workspace-write' | 'danger-full-access'` |  |
+| `approvalMode` | `'suggest' | 'auto-edit' | 'full-auto'` |  |
+| `projectDoc` | `string` |  |
+| `noProjectDoc` | `boolean` |  |
+| `fullStdout` | `boolean` |  |
+| `images` | `string[]` |  |
+| `fullAuto` | `boolean` |  |
+| `resumeSessionId` | `string` | Resume a previous session by ID. |
+| `resumeLast` | `boolean` | Resume the most recent session. |
+| `dangerouslyAutoApproveEverything` | `boolean` | Skip all approvals and sandboxing. |
+| `extraArgs` | `string[]` | Additional CLI flags. |
+
+**Returns:** `string`
+
+```ts
+const sessionId = codex.start('Build a REST API for users')
+
+codex.on('session:delta', ({ sessionId: sid, text }) => {
+ if (sid === sessionId) process.stdout.write(text)
+})
+```
+
+
+
+### abort
+
+Kill a running session's subprocess.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sessionId` | `string` | ✓ | The session ID to abort |
+
+**Returns:** `void`
+
+
+
+### getSession
+
+Retrieve the current state of a session by its ID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sessionId` | `string` | ✓ | The session ID to look up |
+
+**Returns:** `CodexSession | undefined`
+
+
+
+### waitForSession
+
+Wait for a running session to complete or error. Resolves immediately if the session is already in a terminal state.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sessionId` | `string` | ✓ | The session ID to wait for |
+
+**Returns:** `Promise<CodexSession>`
+
+
+
+### enable
+
+Enable the feature. Delegates to the base Feature enable() lifecycle.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `any` |  | Options to merge into the feature configuration |
+
+**Returns:** `Promise<this>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `codexPath` | `string` |  |
+
+## Events (Zod v4 schema)
+
+### session:event
+
+Event emitted by OpenAICodex
+
+
+
+### session:delta
+
+Event emitted by OpenAICodex
+
+
+
+### session:message
+
+Event emitted by OpenAICodex
+
+
+
+### session:exec
+
+Event emitted by OpenAICodex
+
+
+
+### session:reasoning
+
+Event emitted by OpenAICodex
+
+
+
+### session:exec-start
+
+Event emitted by OpenAICodex
+
+
+
+### session:start
+
+Event emitted by OpenAICodex
+
+
+
+### session:error
+
+Event emitted by OpenAICodex
+
+
+
+### session:parse-error
+
+Event emitted by OpenAICodex
+
+
+
+### session:result
+
+Event emitted by OpenAICodex
+
+
+
+### session:abort
+
+Event emitted by OpenAICodex
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `sessions` | `object` | Map of session IDs to CodexSession objects |
+| `activeSessions` | `array` | List of currently running session IDs |
+| `codexAvailable` | `boolean` | Whether the codex CLI binary is available |
+| `codexVersion` | `string` | Detected codex CLI version string |
+
+## Examples
+
+**features.openaiCodex**
+
+```ts
+const codex = container.feature('openaiCodex')
+
+// Listen for events
+codex.on('session:message', ({ sessionId, message }) => console.log(message))
+codex.on('session:patch', ({ sessionId, patch }) => console.log('File changed:', patch.path))
+
+// Run a prompt
+const session = await codex.run('Fix the failing tests in src/')
+console.log(session.result)
+```
+
+
+
+**run**
+
+```ts
+const session = await codex.run('Fix the failing tests')
+console.log(session.result)
+
+const session = await codex.run('Refactor the auth module', {
+ model: 'o4-mini',
+ fullAuto: true,
+ cwd: '/path/to/project'
+})
+```
+
+
+
+**start**
+
+```ts
+const sessionId = codex.start('Build a REST API for users')
+
+codex.on('session:delta', ({ sessionId: sid, text }) => {
+ if (sid === sessionId) process.stdout.write(text)
+})
+```
+

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

@@ -0,0 +1,138 @@
+# OpenAPI (features.openapi)
+
+The OpenAPI feature loads an OpenAPI/Swagger spec from a URL and provides inspection and conversion utilities. Works in both browser and node environments since it uses fetch.
+
+## Usage
+
+```ts
+container.feature('openapi')
+```
+
+## Methods
+
+### load
+
+Fetches and parses the OpenAPI spec from the configured URL. Populates `endpoints`, updates state with spec metadata.
+
+**Returns:** `Promise<this>`
+
+
+
+### endpoint
+
+Get a single endpoint by its friendly name or operationId.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The friendly name or operationId to look up |
+
+**Returns:** `EndpointInfo | undefined`
+
+
+
+### toTools
+
+Convert all endpoints into OpenAI-compatible tool definitions.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filter` | `(ep: EndpointInfo) => boolean` |  | Optional predicate to select which endpoints to include |
+
+**Returns:** `OpenAIToolDef[]`
+
+
+
+### toTool
+
+Convert a single endpoint (by name) to an OpenAI-compatible tool definition.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The endpoint friendly name or operationId |
+
+**Returns:** `OpenAIToolDef | undefined`
+
+
+
+### toFunctions
+
+Convert all endpoints into OpenAI-compatible function definitions.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filter` | `(ep: EndpointInfo) => boolean` |  | Optional predicate to select which endpoints to include |
+
+**Returns:** `OpenAIFunctionDef[]`
+
+
+
+### toFunction
+
+Convert a single endpoint (by name) to an OpenAI function definition.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The endpoint friendly name or operationId |
+
+**Returns:** `OpenAIFunctionDef | undefined`
+
+
+
+### toJSON
+
+Return a compact JSON summary of all endpoints, useful for logging or REPL inspection.
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `serverUrl` | `string` | The base server URL derived from options, normalizing the openapi.json suffix |
+| `specUrl` | `string` | The URL that will be fetched for the spec document |
+| `spec` | `any` | The raw spec object. Null before load() is called. |
+| `endpoints` | `EndpointInfo[]` | All parsed endpoints as an array |
+| `endpointNames` | `string[]` | All endpoint friendly names |
+| `endpointsByTag` | `Record<string, EndpointInfo[]>` | Map of endpoints grouped by tag |
+
+## Events (Zod v4 schema)
+
+### loaded
+
+Event emitted by OpenAPI
+
+
+
+## Examples
+
+**features.openapi**
+
+```ts
+const api = container.feature('openapi', { url: 'https://petstore.swagger.io/v2' })
+await api.load()
+
+// Inspect all endpoints
+api.endpoints
+
+// Get a single endpoint by its friendly name
+api.endpoint('getPetById')
+
+// Convert to OpenAI tool definitions
+api.toTools()
+
+// Convert a single endpoint to a function definition
+api.toFunction('getPetById')
+```
+