@soederpop/luca 0.1.1 → 0.1.3

package/docs/apis/features/agi/luca-coder.md

@@ -0,0 +1,407 @@
+# LucaCoder (features.lucaCoder)
+
+A coding assistant that owns a lower-level Assistant instance and gates all tool calls through a permission system. Comes with built-in Bash tool (via proc.execAndCapture) and auto-loads the luca-framework skill when found in .claude/skills paths. Tools are stacked from feature bundles (fileTools, etc.) and each tool can be set to 'allow' (runs immediately), 'ask' (blocks until user approves/denies), or 'deny' (always rejected).
+
+## Usage
+
+```ts
+container.feature('lucaCoder', {
+  // Tool bundles to register on the inner assistant
+  tools,
+  // Permission level per tool name
+  permissions,
+  // Default permission level for unconfigured tools
+  defaultPermission,
+  // System prompt for the inner assistant
+  systemPrompt,
+  // OpenAI model override
+  model,
+  // Maximum number of output tokens per completion
+  maxTokens,
+  // Use a local API server for the inner assistant
+  local,
+  // Conversation history persistence mode
+  historyMode,
+  // Assistant folder for disk-based definitions
+  folder,
+  // Skill names to auto-load into the system prompt
+  skills,
+  // Auto-load luca-framework skill if found in .claude/skills path
+  autoLoadLucaSkill,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tools` | `array` | Tool bundles to register on the inner assistant |
+| `permissions` | `object` | Permission level per tool name |
+| `defaultPermission` | `string` | Default permission level for unconfigured tools |
+| `systemPrompt` | `string` | System prompt for the inner assistant |
+| `model` | `string` | OpenAI model override |
+| `maxTokens` | `number` | Maximum number of output tokens per completion |
+| `local` | `boolean` | Use a local API server for the inner assistant |
+| `historyMode` | `string` | Conversation history persistence mode |
+| `folder` | `string` | Assistant folder for disk-based definitions |
+| `skills` | `array` | Skill names to auto-load into the system prompt |
+| `autoLoadLucaSkill` | `boolean` | Auto-load luca-framework skill if found in .claude/skills path |
+
+## Methods
+
+### getPermission
+
+Get the effective permission level for a tool.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `toolName` | `string` | ✓ | Parameter toolName |
+
+**Returns:** `PermissionLevel`
+
+
+
+### setPermission
+
+Set permission level for one or more tools.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `toolName` | `string | string[]` | ✓ | Parameter toolName |
+| `level` | `PermissionLevel` | ✓ | Parameter level |
+
+**Returns:** `this`
+
+
+
+### setDefaultPermission
+
+Set the default permission level for unconfigured tools.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `level` | `PermissionLevel` | ✓ | Parameter level |
+
+**Returns:** `this`
+
+
+
+### permitTool
+
+Allow a tool (or tools) to run without approval.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `toolNames` | `string[]` | ✓ | Parameter toolNames |
+
+**Returns:** `this`
+
+
+
+### gateTool
+
+Require approval before a tool (or tools) can run.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `toolNames` | `string[]` | ✓ | Parameter toolNames |
+
+**Returns:** `this`
+
+
+
+### blockTool
+
+Block a tool (or tools) from ever running.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `toolNames` | `string[]` | ✓ | Parameter toolNames |
+
+**Returns:** `this`
+
+
+
+### approve
+
+Approve a pending tool call by ID. The tool will execute.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✓ | Parameter id |
+
+**Returns:** `this`
+
+
+
+### deny
+
+Deny a pending tool call by ID. The tool call will be skipped.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✓ | Parameter id |
+
+**Returns:** `this`
+
+
+
+### approveAll
+
+Approve all pending tool calls.
+
+**Returns:** `this`
+
+
+
+### denyAll
+
+Deny all pending tool calls.
+
+**Returns:** `this`
+
+
+
+### bash
+
+Execute a shell command string and return its output. Uses proc.execAndCapture under the hood — runs `sh -c <command>`.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `{ command, cwd, timeout }` | `{ command: string; cwd?: string; timeout?: number }` | ✓ | Parameter { command, cwd, timeout } |
+
+**Returns:** `Promise<{
+		exitCode: number
+		stdout: string
+		stderr: string
+		success: boolean
+	}>`
+
+
+
+### start
+
+Initialize the inner assistant, register the bash tool, stack tool bundles, auto-load skills, and wire up the permission interceptor.
+
+**Returns:** `Promise<this>`
+
+
+
+### ask
+
+Ask the coder a question. Auto-starts if needed. Tool calls will be gated by the permission system.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `question` | `string` | ✓ | Parameter question |
+| `options` | `Record<string, any>` |  | Parameter options |
+
+**Returns:** `Promise<string>`
+
+
+
+### use
+
+Add a tool bundle after initialization. Useful for dynamically extending the assistant's capabilities.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `spec` | `ToolBundleSpec` | ✓ | Parameter spec |
+
+**Returns:** `this`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `assistant` | `Assistant` | The inner assistant. Throws if not started. |
+| `permissions` | `Record<string, PermissionLevel>` | Current permission map from state. |
+| `pendingApprovals` | `PendingApproval[]` | Current pending approvals. |
+| `isStarted` | `boolean` | Whether the assistant is started and ready. |
+| `tools` | `Record<string, any>` | The tools registered on the inner assistant. |
+| `conversation` | `any` | The conversation on the inner assistant (if started). |
+| `messages` | `any` | Messages from the inner assistant's conversation. |
+
+## Events (Zod v4 schema)
+
+### permissionGranted
+
+Emitted when a pending tool call is approved
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Approval ID |
+
+
+
+### permissionDenied
+
+Emitted when a pending tool call is denied
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Approval ID |
+
+
+
+### toolBlocked
+
+Emitted when a tool call is blocked by deny policy
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+| `arg1` | `string` | Reason |
+
+
+
+### chunk
+
+Forwarded: streamed token chunk from the inner assistant
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | A chunk of streamed text |
+
+
+
+### response
+
+Forwarded: complete response from the inner assistant
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The final response text |
+
+
+
+### toolCall
+
+Forwarded: a tool was called
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Tool arguments |
+
+
+
+### toolResult
+
+Forwarded: a tool returned a result
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Result value |
+
+
+
+### toolError
+
+Forwarded: a tool call failed
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Tool name |
+| `arg1` | `any` | Error |
+
+
+
+### started
+
+Emitted when the luca coder has been initialized
+
+
+
+### permissionRequest
+
+Emitted when a tool call requires user approval
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique approval ID |
+| `toolName` | `string` | The tool requesting permission |
+| `args` | `object` | The arguments the tool was called with |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `started` | `boolean` | Whether the assistant has been initialized |
+| `permissions` | `object` | Permission level per tool name |
+| `defaultPermission` | `string` | Permission level for tools not explicitly configured |
+| `pendingApprovals` | `array` | Tool calls currently awaiting user approval |
+| `approvalHistory` | `array` | Recent approval decisions |
+| `loadedSkills` | `array` | Names of skills auto-loaded into context |
+
+## Examples
+
+**features.lucaCoder**
+
+```ts
+const coder = container.feature('lucaCoder', {
+ tools: ['fileTools'],
+ permissions: {
+   readFile: 'allow',
+   searchFiles: 'allow',
+   writeFile: 'ask',
+   bash: 'ask',
+ },
+ defaultPermission: 'ask',
+ systemPrompt: 'You are a coding assistant.',
+})
+
+coder.on('permissionRequest', ({ id, toolName, args }) => {
+ console.log(`Tool "${toolName}" wants to run with`, args)
+ coder.approve(id)  // or coder.deny(id)
+})
+
+await coder.ask('Refactor the auth module to use async/await')
+```
+

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

@@ -32,7 +32,7 @@ Get a single endpoint by its friendly name or operationId.
 
 
 
-### toTools
+### toOpenAITools
 
 Convert all endpoints into OpenAI-compatible tool definitions.
 
@@ -130,7 +130,7 @@ api.endpoints
 api.endpoint('getPetById')
 
 // Convert to OpenAI tool definitions
-api.toTools()
+api.toOpenAITools()
 
 // Convert a single endpoint to a function definition
 api.toFunction('getPetById')

package/docs/apis/features/agi/skills-library.md

@@ -19,6 +19,18 @@ container.feature('skillsLibrary', {
 
 ## Methods
 
+### setupToolsConsumer
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `assistant` | `Feature` | ✓ | Parameter assistant |
+
+**Returns:** `void`
+
+
+
 ### start
 
 Start the skills library: read config, scan all locations.

package/docs/apis/features/node/python.md

@@ -296,67 +296,137 @@ await python.resetSession()
 
 ### ready
 
-Event emitted by Python
+When the Python environment is ready for execution
 
 
 
 ### environmentDetected
 
-Event emitted by Python
+When the Python environment type is detected
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pythonPath` | `any` | Path to the detected Python executable |
+| `environmentType` | `any` | Detected environment type |
 
 
 
 ### installingDependencies
 
-Event emitted by Python
+When dependency installation begins
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `command` | `string` | The install command being run |
 
 
 
 ### dependenciesInstalled
 
-Event emitted by Python
+When dependencies are successfully installed
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `stdout` | `string` | Standard output from install |
+| `stderr` | `string` | Standard error from install |
+| `exitCode` | `number` | Process exit code |
 
 
 
 ### dependencyInstallFailed
 
-Event emitted by Python
+When dependency installation fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `stdout` | `string` | Standard output from install |
+| `stderr` | `string` | Standard error from install |
+| `exitCode` | `number` | Process exit code |
 
 
 
 ### localsParseError
 
-Event emitted by Python
+When captured locals fail to parse as JSON
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The parse error |
 
 
 
 ### codeExecuted
 
-Event emitted by Python
+When Python code finishes executing
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `code` | `string` | The Python code that was executed |
+| `variables` | `object` | Variables passed to the execution |
+| `result` | `object` | Execution result |
 
 
 
 ### fileExecuted
 
-Event emitted by Python
+When a Python file finishes executing
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `filePath` | `string` | Path to the executed Python file |
+| `variables` | `object` | Variables passed as arguments |
+| `result` | `object` | Execution result |
 
 
 
 ### sessionError
 
-Event emitted by Python
+When a session-level error occurs
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `error` | `string` | Error message |
+| `sessionId` | `any` | Session identifier, if available |
 
 
 
 ### sessionStarted
 
-Event emitted by Python
+When a persistent Python session starts
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` | Unique session identifier |
 
 
 
 ### sessionStopped
 
-Event emitted by Python
+When a persistent Python session stops
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` | Session identifier that stopped |
 
 
 

package/docs/apis/features/node/transpiler.md

@@ -0,0 +1,74 @@
+# Transpiler (features.transpiler)
+
+Transpile TypeScript, TSX, and JSX to JavaScript at runtime using Bun's built-in transpiler. Compile code strings on the fly without touching the filesystem or spawning external processes.
+
+## Usage
+
+```ts
+container.feature('transpiler')
+```
+
+## Methods
+
+### transformSync
+
+Transform code synchronously
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | The code to transform |
+| `options` | `TransformOptions` |  | Transform options (loader, format, minify) |
+
+`TransformOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `loader` | `'ts' | 'tsx' | 'jsx' | 'js'` |  |
+| `format` | `'esm' | 'cjs'` |  |
+| `minify` | `boolean` |  |
+
+**Returns:** `TransformResult`
+
+
+
+### transform
+
+Transform code asynchronously
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | The code to transform |
+| `options` | `TransformOptions` |  | Transform options (loader, format, minify) |
+
+`TransformOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `loader` | `'ts' | 'tsx' | 'jsx' | 'js'` |  |
+| `format` | `'esm' | 'cjs'` |  |
+| `minify` | `boolean` |  |
+
+**Returns:** `Promise<TransformResult>`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.transpiler**
+
+```ts
+const transpiler = container.feature('transpiler')
+const result = transpiler.transformSync('const x: number = 1')
+console.log(result.code) // 'const x = 1;\n'
+```
+

package/docs/apis/features/web/esbuild.md

@@ -41,12 +41,6 @@ container.feature('esbuild')
 |----------|------|-------------|
 | `assetLoader` | `any` | Returns the assetLoader feature for loading external libraries from unpkg. |
 
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-
 ## Examples
 
 **features.esbuild**

package/docs/apis/servers/mcp.md

@@ -52,9 +52,9 @@ Register an MCP tool. The tool's Zod schema is converted to JSON Schema for the
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `schema` | `z.ZodObject<any>` |  |
+| `schema` | `z.ZodType` |  |
 | `description` | `string` |  |
-| `handler` | `(args: any, ctx: MCPContext) => any` |  |
+| `handler` | `Function | ((args: any, ctx: any) => any)` |  |
 
 **Returns:** `this`