@soederpop/luca 0.0.31 → 0.0.34

package/src/introspection/generated.agi.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-24T09:08:05.995Z
+// Generated at: 2026-03-26T03:30:20.574Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -5927,6 +5927,312 @@ setBuildTimeData('features.googleCalendar', {
   }
 });
 
+setBuildTimeData('features.redis', {
+  "id": "features.redis",
+  "description": "Redis feature for shared state and pub/sub communication between container instances. Wraps ioredis with a focused API for the primitives that matter most: key/value state, pub/sub messaging, and cross-instance coordination. Uses a dedicated subscriber connection for pub/sub (ioredis requirement), created lazily on first subscribe call.",
+  "shortcut": "features.redis",
+  "className": "RedisFeature",
+  "methods": {
+    "set": {
+      "description": "Set a key to a string value with optional TTL.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The key name"
+        },
+        "value": {
+          "type": "string",
+          "description": "The string value to store"
+        },
+        "ttl": {
+          "type": "number",
+          "description": "Optional time-to-live in seconds"
+        }
+      },
+      "required": [
+        "key",
+        "value"
+      ],
+      "returns": "Promise<void>"
+    },
+    "get": {
+      "description": "Get a key's value. Returns null if the key doesn't exist.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The key name"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "returns": "Promise<string | null>"
+    },
+    "del": {
+      "description": "Delete one or more keys.",
+      "parameters": {
+        "keys": {
+          "type": "string[]",
+          "description": "One or more key names to delete"
+        }
+      },
+      "required": [
+        "keys"
+      ],
+      "returns": "Promise<number>"
+    },
+    "exists": {
+      "description": "Check if a key exists.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The key name"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "returns": "Promise<boolean>"
+    },
+    "expire": {
+      "description": "Set a key's TTL in seconds.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The key name"
+        },
+        "seconds": {
+          "type": "number",
+          "description": "TTL in seconds"
+        }
+      },
+      "required": [
+        "key",
+        "seconds"
+      ],
+      "returns": "Promise<boolean>"
+    },
+    "keys": {
+      "description": "Find keys matching a glob pattern (respects prefix).",
+      "parameters": {
+        "pattern": {
+          "type": "string",
+          "description": "Glob pattern, e.g. \"worker:*\""
+        }
+      },
+      "required": [],
+      "returns": "Promise<string[]>"
+    },
+    "setJSON": {
+      "description": "Store a value as JSON.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The key name"
+        },
+        "value": {
+          "type": "unknown",
+          "description": "Any JSON-serializable value"
+        },
+        "ttl": {
+          "type": "number",
+          "description": "Optional TTL in seconds"
+        }
+      },
+      "required": [
+        "key",
+        "value"
+      ],
+      "returns": "Promise<void>"
+    },
+    "getJSON": {
+      "description": "Retrieve and parse a JSON value.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The key name"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "returns": "Promise<T | null>"
+    },
+    "hset": {
+      "description": "Set fields on a hash.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The hash key"
+        },
+        "fields": {
+          "type": "Record<string, string>",
+          "description": "Object of field/value pairs"
+        }
+      },
+      "required": [
+        "key",
+        "fields"
+      ],
+      "returns": "Promise<void>"
+    },
+    "hgetall": {
+      "description": "Get all fields from a hash.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The hash key"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "returns": "Promise<Record<string, string>>"
+    },
+    "hget": {
+      "description": "Get a single field from a hash.",
+      "parameters": {
+        "key": {
+          "type": "string",
+          "description": "The hash key"
+        },
+        "field": {
+          "type": "string",
+          "description": "The field name"
+        }
+      },
+      "required": [
+        "key",
+        "field"
+      ],
+      "returns": "Promise<string | null>"
+    },
+    "subscribe": {
+      "description": "Subscribe to one or more channels. Optionally pass a handler that fires only for these channels. The feature also emits a `message` event for all messages.",
+      "parameters": {
+        "channels": {
+          "type": "string | string[]",
+          "description": "Channel name(s) to subscribe to"
+        },
+        "handler": {
+          "type": "MessageHandler",
+          "description": "Optional per-channel message handler"
+        }
+      },
+      "required": [
+        "channels"
+      ],
+      "returns": "Promise<void>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await redis.subscribe('tasks', (channel, msg) => {\n console.log(`Got ${msg} on ${channel}`)\n})"
+        }
+      ]
+    },
+    "unsubscribe": {
+      "description": "Unsubscribe from one or more channels.",
+      "parameters": {
+        "channels": {
+          "type": "string[]",
+          "description": "Channel name(s) to unsubscribe from"
+        }
+      },
+      "required": [
+        "channels"
+      ],
+      "returns": "Promise<void>"
+    },
+    "publish": {
+      "description": "Publish a message to a channel.",
+      "parameters": {
+        "channel": {
+          "type": "string",
+          "description": "The channel to publish to"
+        },
+        "message": {
+          "type": "string",
+          "description": "The message string (use JSON.stringify for objects)"
+        }
+      },
+      "required": [
+        "channel",
+        "message"
+      ],
+      "returns": "Promise<number>"
+    },
+    "ensureLocalDocker": {
+      "description": "Spin up a local Redis instance via Docker. Checks if a container with the given name already exists and starts it if stopped, or creates a new one from redis:alpine. Requires the docker feature to be available on the container.",
+      "parameters": {
+        "options": {
+          "type": "{ name?: string; port?: number; image?: string }",
+          "description": "Container name and host port"
+        }
+      },
+      "required": [],
+      "returns": "Promise<string>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const redis = container.feature('redis', { url: 'redis://localhost:6379', lazyConnect: true })\nawait redis.ensureLocalDocker()"
+        }
+      ]
+    },
+    "close": {
+      "description": "Close all redis connections (main client + subscriber).",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<this>"
+    }
+  },
+  "getters": {
+    "client": {
+      "description": "The underlying ioredis client for advanced operations.",
+      "returns": "Redis"
+    },
+    "subscriber": {
+      "description": "The dedicated subscriber connection, if pub/sub is active.",
+      "returns": "Redis | null"
+    }
+  },
+  "events": {
+    "message": {
+      "name": "message",
+      "description": "Event emitted by RedisFeature",
+      "arguments": {}
+    },
+    "error": {
+      "name": "error",
+      "description": "Event emitted by RedisFeature",
+      "arguments": {}
+    },
+    "subscribed": {
+      "name": "subscribed",
+      "description": "Event emitted by RedisFeature",
+      "arguments": {}
+    },
+    "unsubscribed": {
+      "name": "unsubscribed",
+      "description": "Event emitted by RedisFeature",
+      "arguments": {}
+    },
+    "closed": {
+      "name": "closed",
+      "description": "Event emitted by RedisFeature",
+      "arguments": {}
+    }
+  },
+  "state": {},
+  "options": {},
+  "envVars": [],
+  "examples": [
+    {
+      "language": "ts",
+      "code": "const redis = container.feature('redis', { url: 'redis://localhost:6379' })\n\n// Shared state\nawait redis.set('worker:status', 'active')\nconst status = await redis.get('worker:status')\n\n// Pub/sub between instances\nredis.on('message', (channel, msg) => console.log(`${channel}: ${msg}`))\nawait redis.subscribe('tasks')\nawait redis.publish('tasks', JSON.stringify({ type: 'ping' }))\n\n// JSON helpers\nawait redis.setJSON('config', { workers: 4, debug: true })\nconst config = await redis.getJSON<{ workers: number }>('config')"
+    }
+  ]
+});
+
 setBuildTimeData('features.fs', {
   "id": "features.fs",
   "description": "The FS feature provides methods for interacting with the file system, relative to the container's cwd.",
@@ -7566,7 +7872,7 @@ setBuildTimeData('features.postgres', {
 
 setBuildTimeData('features.python', {
   "id": "features.python",
-  "description": "The Python VM feature provides Python virtual machine capabilities for executing Python code. This feature automatically detects Python environments (uv, conda, venv, system) and provides methods to install dependencies and execute Python scripts. It can manage project-specific Python environments and maintain context between executions.",
+  "description": "The Python VM feature provides Python virtual machine capabilities for executing Python code. This feature automatically detects Python environments (uv, conda, venv, system) and provides methods to install dependencies and execute Python scripts. It can manage project-specific Python environments and maintain context between executions. Supports two modes: - **Stateless** (default): `execute()` and `executeFile()` spawn a fresh process per call - **Persistent session**: `startSession()` spawns a long-lived bridge process that maintains state across `run()` calls, enabling real codebase interaction with imports and session variables",
   "shortcut": "features.python",
   "className": "Python",
   "methods": {
@@ -7666,6 +7972,146 @@ setBuildTimeData('features.python', {
       "parameters": {},
       "required": [],
       "returns": "Promise<{ version: string; path: string; packages: string[] }>"
+    },
+    "startSession": {
+      "description": "Starts a persistent Python session by spawning the bridge process. The bridge sets up sys.path for the project directory, then enters a JSON-line REPL loop. State (variables, imports) persists across run() calls until stopSession() or resetSession() is called.",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<void>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const python = container.feature('python', { dir: '/path/to/project' })\nawait python.enable()\nawait python.startSession()\nawait python.run('x = 42')\nconst result = await python.run('print(x)')\nconsole.log(result.stdout) // '42\\n'\nawait python.stopSession()"
+        }
+      ]
+    },
+    "stopSession": {
+      "description": "Stops the persistent Python session and cleans up the bridge process.",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<void>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.stopSession()"
+        }
+      ]
+    },
+    "run": {
+      "description": "Executes Python code in the persistent session. Variables and imports survive across calls. This is the session equivalent of execute().",
+      "parameters": {
+        "code": {
+          "type": "string",
+          "description": "Python code to execute"
+        },
+        "variables": {
+          "type": "Record<string, any>",
+          "description": "Variables to inject into the namespace before execution"
+        }
+      },
+      "required": [
+        "code"
+      ],
+      "returns": "Promise<RunResult>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.startSession()\n\n// State persists across calls\nawait python.run('x = 42')\nconst result = await python.run('print(x * 2)')\nconsole.log(result.stdout) // '84\\n'\n\n// Inject variables from JS\nconst result2 = await python.run('print(f\"Hello {name}!\")', { name: 'World' })\nconsole.log(result2.stdout) // 'Hello World!\\n'"
+        }
+      ]
+    },
+    "eval": {
+      "description": "Evaluates a Python expression in the persistent session and returns its value.",
+      "parameters": {
+        "expression": {
+          "type": "string",
+          "description": "Python expression to evaluate"
+        }
+      },
+      "required": [
+        "expression"
+      ],
+      "returns": "Promise<any>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.run('x = 42')\nconst result = await python.eval('x * 2')\nconsole.log(result) // 84"
+        }
+      ]
+    },
+    "importModule": {
+      "description": "Imports a Python module into the persistent session namespace.",
+      "parameters": {
+        "moduleName": {
+          "type": "string",
+          "description": "Dotted module path (e.g. 'myapp.models')"
+        },
+        "alias": {
+          "type": "string",
+          "description": "Optional alias for the import (defaults to the last segment)"
+        }
+      },
+      "required": [
+        "moduleName"
+      ],
+      "returns": "Promise<void>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.importModule('json')\nawait python.importModule('myapp.models', 'models')\nconst result = await python.eval('models.User')"
+        }
+      ]
+    },
+    "call": {
+      "description": "Calls a function by dotted path in the persistent session namespace.",
+      "parameters": {
+        "funcPath": {
+          "type": "string",
+          "description": "Dotted path to the function (e.g. 'json.dumps' or 'my_func')"
+        },
+        "args": {
+          "type": "any[]",
+          "description": "Positional arguments"
+        },
+        "kwargs": {
+          "type": "Record<string, any>",
+          "description": "Keyword arguments"
+        }
+      },
+      "required": [
+        "funcPath"
+      ],
+      "returns": "Promise<any>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.importModule('json')\nconst result = await python.call('json.dumps', [{ a: 1 }], { indent: 2 })"
+        }
+      ]
+    },
+    "getLocals": {
+      "description": "Returns all non-dunder variables from the persistent session namespace.",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<Record<string, any>>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.run('x = 42\\ny = \"hello\"')\nconst locals = await python.getLocals()\nconsole.log(locals) // { x: 42, y: 'hello' }"
+        }
+      ]
+    },
+    "resetSession": {
+      "description": "Clears all variables and imports from the persistent session namespace. The session remains active — you can continue calling run() after reset.",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<void>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "await python.run('x = 42')\nawait python.resetSession()\n// x is now undefined"
+        }
+      ]
     }
   },
   "getters": {
@@ -7722,6 +8168,21 @@ setBuildTimeData('features.python', {
       "name": "fileExecuted",
       "description": "Event emitted by Python",
       "arguments": {}
+    },
+    "sessionError": {
+      "name": "sessionError",
+      "description": "Event emitted by Python",
+      "arguments": {}
+    },
+    "sessionStarted": {
+      "name": "sessionStarted",
+      "description": "Event emitted by Python",
+      "arguments": {}
+    },
+    "sessionStopped": {
+      "name": "sessionStopped",
+      "description": "Event emitted by Python",
+      "arguments": {}
     }
   },
   "state": {},
@@ -7730,9 +8191,38 @@ setBuildTimeData('features.python', {
   "examples": [
     {
       "language": "ts",
-      "code": "const python = container.feature('python', { \n dir: \"/path/to/python/project\",\n contextScript: \"/path/to/setup-context.py\"\n})\n\n// Auto-install dependencies\nawait python.installDependencies()\n\n// Execute Python code\nconst result = await python.execute('print(\"Hello from Python!\")')\n\n// Execute with custom variables\nconst result2 = await python.execute('print(f\"Hello {name}!\")', { name: 'World' })"
+      "code": "const python = container.feature('python', {\n dir: \"/path/to/python/project\",\n})\n\n// Stateless execution\nconst result = await python.execute('print(\"Hello from Python!\")')\n\n// Persistent session\nawait python.startSession()\nawait python.run('import myapp.models')\nawait python.run('users = myapp.models.User.objects.all()')\nconst result = await python.run('print(len(users))')\nawait python.stopSession()"
     }
-  ]
+  ],
+  "types": {
+    "RunResult": {
+      "description": "Result from a persistent session run() call.",
+      "properties": {
+        "ok": {
+          "type": "boolean",
+          "description": ""
+        },
+        "result": {
+          "type": "any",
+          "description": ""
+        },
+        "stdout": {
+          "type": "string",
+          "description": ""
+        },
+        "error": {
+          "type": "string",
+          "description": "",
+          "optional": true
+        },
+        "traceback": {
+          "type": "string",
+          "description": "",
+          "optional": true
+        }
+      }
+    }
+  }
 });
 
 setBuildTimeData('features.jsonTree', {
@@ -16543,6 +17033,303 @@ setBuildTimeData('features.openaiCodex', {
   }
 });
 
+setBuildTimeData('features.lucaCoder', {
+  "id": "features.lucaCoder",
+  "description": "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).",
+  "shortcut": "features.lucaCoder",
+  "className": "LucaCoder",
+  "methods": {
+    "getPermission": {
+      "description": "Get the effective permission level for a tool.",
+      "parameters": {
+        "toolName": {
+          "type": "string",
+          "description": "Parameter toolName"
+        }
+      },
+      "required": [
+        "toolName"
+      ],
+      "returns": "PermissionLevel"
+    },
+    "setPermission": {
+      "description": "Set permission level for one or more tools.",
+      "parameters": {
+        "toolName": {
+          "type": "string | string[]",
+          "description": "Parameter toolName"
+        },
+        "level": {
+          "type": "PermissionLevel",
+          "description": "Parameter level"
+        }
+      },
+      "required": [
+        "toolName",
+        "level"
+      ],
+      "returns": "this"
+    },
+    "setDefaultPermission": {
+      "description": "Set the default permission level for unconfigured tools.",
+      "parameters": {
+        "level": {
+          "type": "PermissionLevel",
+          "description": "Parameter level"
+        }
+      },
+      "required": [
+        "level"
+      ],
+      "returns": "this"
+    },
+    "permitTool": {
+      "description": "Allow a tool (or tools) to run without approval.",
+      "parameters": {
+        "toolNames": {
+          "type": "string[]",
+          "description": "Parameter toolNames"
+        }
+      },
+      "required": [
+        "toolNames"
+      ],
+      "returns": "this"
+    },
+    "gateTool": {
+      "description": "Require approval before a tool (or tools) can run.",
+      "parameters": {
+        "toolNames": {
+          "type": "string[]",
+          "description": "Parameter toolNames"
+        }
+      },
+      "required": [
+        "toolNames"
+      ],
+      "returns": "this"
+    },
+    "blockTool": {
+      "description": "Block a tool (or tools) from ever running.",
+      "parameters": {
+        "toolNames": {
+          "type": "string[]",
+          "description": "Parameter toolNames"
+        }
+      },
+      "required": [
+        "toolNames"
+      ],
+      "returns": "this"
+    },
+    "approve": {
+      "description": "Approve a pending tool call by ID. The tool will execute.",
+      "parameters": {
+        "id": {
+          "type": "string",
+          "description": "Parameter id"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "returns": "this"
+    },
+    "deny": {
+      "description": "Deny a pending tool call by ID. The tool call will be skipped.",
+      "parameters": {
+        "id": {
+          "type": "string",
+          "description": "Parameter id"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "returns": "this"
+    },
+    "approveAll": {
+      "description": "Approve all pending tool calls.",
+      "parameters": {},
+      "required": [],
+      "returns": "this"
+    },
+    "denyAll": {
+      "description": "Deny all pending tool calls.",
+      "parameters": {},
+      "required": [],
+      "returns": "this"
+    },
+    "bash": {
+      "description": "Execute a shell command string and return its output. Uses proc.execAndCapture under the hood — runs `sh -c <command>`.",
+      "parameters": {
+        "{ command, cwd, timeout }": {
+          "type": "{ command: string; cwd?: string; timeout?: number }",
+          "description": "Parameter { command, cwd, timeout }"
+        }
+      },
+      "required": [
+        "{ command, cwd, timeout }"
+      ],
+      "returns": "Promise<{\n\t\texitCode: number\n\t\tstdout: string\n\t\tstderr: string\n\t\tsuccess: boolean\n\t}>"
+    },
+    "start": {
+      "description": "Initialize the inner assistant, register the bash tool, stack tool bundles, auto-load skills, and wire up the permission interceptor.",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<this>"
+    },
+    "ask": {
+      "description": "Ask the coder a question. Auto-starts if needed. Tool calls will be gated by the permission system.",
+      "parameters": {
+        "question": {
+          "type": "string",
+          "description": "Parameter question"
+        },
+        "options": {
+          "type": "Record<string, any>",
+          "description": "Parameter options"
+        }
+      },
+      "required": [
+        "question"
+      ],
+      "returns": "Promise<string>"
+    },
+    "use": {
+      "description": "Add a tool bundle after initialization. Useful for dynamically extending the assistant's capabilities.",
+      "parameters": {
+        "spec": {
+          "type": "ToolBundleSpec",
+          "description": "Parameter spec"
+        }
+      },
+      "required": [
+        "spec"
+      ],
+      "returns": "this"
+    }
+  },
+  "getters": {
+    "assistant": {
+      "description": "The inner assistant. Throws if not started.",
+      "returns": "Assistant"
+    },
+    "permissions": {
+      "description": "Current permission map from state.",
+      "returns": "Record<string, PermissionLevel>"
+    },
+    "pendingApprovals": {
+      "description": "Current pending approvals.",
+      "returns": "PendingApproval[]"
+    },
+    "isStarted": {
+      "description": "Whether the assistant is started and ready.",
+      "returns": "boolean"
+    },
+    "tools": {
+      "description": "The tools registered on the inner assistant.",
+      "returns": "Record<string, any>"
+    },
+    "conversation": {
+      "description": "The conversation on the inner assistant (if started).",
+      "returns": "any"
+    },
+    "messages": {
+      "description": "Messages from the inner assistant's conversation.",
+      "returns": "any"
+    }
+  },
+  "events": {
+    "permissionGranted": {
+      "name": "permissionGranted",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "permissionDenied": {
+      "name": "permissionDenied",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "toolBlocked": {
+      "name": "toolBlocked",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "chunk": {
+      "name": "chunk",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "response": {
+      "name": "response",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "toolCall": {
+      "name": "toolCall",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "toolResult": {
+      "name": "toolResult",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "toolError": {
+      "name": "toolError",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "started": {
+      "name": "started",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    },
+    "permissionRequest": {
+      "name": "permissionRequest",
+      "description": "Event emitted by LucaCoder",
+      "arguments": {}
+    }
+  },
+  "state": {},
+  "options": {},
+  "envVars": [],
+  "examples": [
+    {
+      "language": "ts",
+      "code": "const coder = container.feature('lucaCoder', {\n tools: ['fileTools'],\n permissions: {\n   readFile: 'allow',\n   searchFiles: 'allow',\n   writeFile: 'ask',\n   bash: 'ask',\n },\n defaultPermission: 'ask',\n systemPrompt: 'You are a coding assistant.',\n})\n\ncoder.on('permissionRequest', ({ id, toolName, args }) => {\n console.log(`Tool \"${toolName}\" wants to run with`, args)\n coder.approve(id)  // or coder.deny(id)\n})\n\nawait coder.ask('Refactor the auth module to use async/await')"
+    }
+  ],
+  "types": {
+    "PendingApproval": {
+      "description": "A pending approval awaiting user decision.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": ""
+        },
+        "toolName": {
+          "type": "string",
+          "description": ""
+        },
+        "args": {
+          "type": "Record<string, any>",
+          "description": ""
+        },
+        "timestamp": {
+          "type": "number",
+          "description": ""
+        },
+        "resolve": {
+          "type": "(decision: 'approve' | 'deny') => void",
+          "description": ""
+        }
+      }
+    }
+  }
+});
+
 setBuildTimeData('features.conversationHistory', {
   "id": "features.conversationHistory",
   "description": "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.",
@@ -17023,6 +17810,460 @@ setBuildTimeData('features.conversationHistory', {
   }
 });
 
+setBuildTimeData('features.autoAssistant', {
+  "id": "features.autoAssistant",
+  "description": "An autonomous assistant that owns a lower-level Assistant instance and gates all tool calls through a permission system. Tools are stacked from feature bundles (fileTools, processManager, etc.) and each tool can be set to 'allow' (runs immediately), 'ask' (blocks until user approves/denies), or 'deny' (always rejected).",
+  "shortcut": "features.autoAssistant",
+  "className": "AutonomousAssistant",
+  "methods": {
+    "getPermission": {
+      "description": "Get the effective permission level for a tool.",
+      "parameters": {
+        "toolName": {
+          "type": "string",
+          "description": "Parameter toolName"
+        }
+      },
+      "required": [
+        "toolName"
+      ],
+      "returns": "PermissionLevel"
+    },
+    "setPermission": {
+      "description": "Set permission level for one or more tools.",
+      "parameters": {
+        "toolName": {
+          "type": "string | string[]",
+          "description": "Parameter toolName"
+        },
+        "level": {
+          "type": "PermissionLevel",
+          "description": "Parameter level"
+        }
+      },
+      "required": [
+        "toolName",
+        "level"
+      ],
+      "returns": "this"
+    },
+    "setDefaultPermission": {
+      "description": "Set the default permission level for unconfigured tools.",
+      "parameters": {
+        "level": {
+          "type": "PermissionLevel",
+          "description": "Parameter level"
+        }
+      },
+      "required": [
+        "level"
+      ],
+      "returns": "this"
+    },
+    "permitTool": {
+      "description": "Allow a tool (or tools) to run without approval.",
+      "parameters": {
+        "toolNames": {
+          "type": "string[]",
+          "description": "Parameter toolNames"
+        }
+      },
+      "required": [
+        "toolNames"
+      ],
+      "returns": "this"
+    },
+    "gateTool": {
+      "description": "Require approval before a tool (or tools) can run.",
+      "parameters": {
+        "toolNames": {
+          "type": "string[]",
+          "description": "Parameter toolNames"
+        }
+      },
+      "required": [
+        "toolNames"
+      ],
+      "returns": "this"
+    },
+    "blockTool": {
+      "description": "Block a tool (or tools) from ever running.",
+      "parameters": {
+        "toolNames": {
+          "type": "string[]",
+          "description": "Parameter toolNames"
+        }
+      },
+      "required": [
+        "toolNames"
+      ],
+      "returns": "this"
+    },
+    "approve": {
+      "description": "Approve a pending tool call by ID. The tool will execute.",
+      "parameters": {
+        "id": {
+          "type": "string",
+          "description": "Parameter id"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "returns": "this"
+    },
+    "deny": {
+      "description": "Deny a pending tool call by ID. The tool call will be skipped.",
+      "parameters": {
+        "id": {
+          "type": "string",
+          "description": "Parameter id"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "returns": "this"
+    },
+    "approveAll": {
+      "description": "Approve all pending tool calls.",
+      "parameters": {},
+      "required": [],
+      "returns": "this"
+    },
+    "denyAll": {
+      "description": "Deny all pending tool calls.",
+      "parameters": {},
+      "required": [],
+      "returns": "this"
+    },
+    "start": {
+      "description": "Initialize the inner assistant, stack tool bundles, and wire up the permission interceptor.",
+      "parameters": {},
+      "required": [],
+      "returns": "Promise<this>"
+    },
+    "ask": {
+      "description": "Ask the autonomous assistant a question. Auto-starts if needed. Tool calls will be gated by the permission system.",
+      "parameters": {
+        "question": {
+          "type": "string",
+          "description": "Parameter question"
+        },
+        "options": {
+          "type": "Record<string, any>",
+          "description": "Parameter options"
+        }
+      },
+      "required": [
+        "question"
+      ],
+      "returns": "Promise<string>"
+    },
+    "use": {
+      "description": "Add a tool bundle after initialization. Useful for dynamically extending the assistant's capabilities.",
+      "parameters": {
+        "spec": {
+          "type": "ToolBundleSpec",
+          "description": "Parameter spec"
+        }
+      },
+      "required": [
+        "spec"
+      ],
+      "returns": "this"
+    }
+  },
+  "getters": {
+    "assistant": {
+      "description": "The inner assistant. Throws if not started.",
+      "returns": "Assistant"
+    },
+    "permissions": {
+      "description": "Current permission map from state.",
+      "returns": "Record<string, PermissionLevel>"
+    },
+    "pendingApprovals": {
+      "description": "Current pending approvals.",
+      "returns": "PendingApproval[]"
+    },
+    "isStarted": {
+      "description": "Whether the assistant is started and ready.",
+      "returns": "boolean"
+    },
+    "tools": {
+      "description": "The tools registered on the inner assistant.",
+      "returns": "Record<string, any>"
+    },
+    "conversation": {
+      "description": "The conversation on the inner assistant (if started).",
+      "returns": "any"
+    },
+    "messages": {
+      "description": "Messages from the inner assistant's conversation.",
+      "returns": "any"
+    }
+  },
+  "events": {
+    "permissionGranted": {
+      "name": "permissionGranted",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "permissionDenied": {
+      "name": "permissionDenied",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "toolBlocked": {
+      "name": "toolBlocked",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "chunk": {
+      "name": "chunk",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "response": {
+      "name": "response",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "toolCall": {
+      "name": "toolCall",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "toolResult": {
+      "name": "toolResult",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "toolError": {
+      "name": "toolError",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "started": {
+      "name": "started",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    },
+    "permissionRequest": {
+      "name": "permissionRequest",
+      "description": "Event emitted by AutonomousAssistant",
+      "arguments": {}
+    }
+  },
+  "state": {},
+  "options": {},
+  "envVars": [],
+  "examples": [
+    {
+      "language": "ts",
+      "code": "const auto = container.feature('autoAssistant', {\n tools: ['fileTools', { feature: 'processManager', except: ['killAllProcesses'] }],\n permissions: {\n   readFile: 'allow',\n   searchFiles: 'allow',\n   writeFile: 'ask',\n   editFile: 'ask',\n   deleteFile: 'deny',\n },\n defaultPermission: 'ask',\n systemPrompt: 'You are a coding assistant.',\n})\n\nauto.on('permissionRequest', ({ id, toolName, args }) => {\n console.log(`Tool \"${toolName}\" wants to run with`, args)\n // Show UI, then:\n auto.approve(id)  // or auto.deny(id)\n})\n\nawait auto.ask('Refactor the auth module to use async/await')"
+    }
+  ],
+  "types": {
+    "PendingApproval": {
+      "description": "A pending approval awaiting user decision.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": ""
+        },
+        "toolName": {
+          "type": "string",
+          "description": ""
+        },
+        "args": {
+          "type": "Record<string, any>",
+          "description": ""
+        },
+        "timestamp": {
+          "type": "number",
+          "description": ""
+        },
+        "resolve": {
+          "type": "(decision: 'approve' | 'deny') => void",
+          "description": ""
+        }
+      }
+    }
+  }
+});
+
+setBuildTimeData('features.fileTools', {
+  "id": "features.fileTools",
+  "description": "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'] })) ```",
+  "shortcut": "features.fileTools",
+  "className": "FileTools",
+  "methods": {
+    "readFile": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path: string; offset?: number; limit?: number }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "writeFile": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path: string; content: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "editFile": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path: string; oldString: string; newString: string; replaceAll?: boolean }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "listDirectory": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path?: string; recursive?: boolean; include?: string; exclude?: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "searchFiles": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ pattern: string; path?: string; include?: string; exclude?: string; ignoreCase?: boolean; maxResults?: number }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "findFiles": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ pattern: string; path?: string; exclude?: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "fileInfo": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "createDirectory": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "moveFile": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ source: string; destination: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "copyFile": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ source: string; destination: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "deleteFile": {
+      "description": "",
+      "parameters": {
+        "args": {
+          "type": "{ path: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "Promise<string>"
+    },
+    "setupToolsConsumer": {
+      "description": "When an assistant uses fileTools, inject system prompt guidance about how to use the tools effectively.",
+      "parameters": {
+        "consumer": {
+          "type": "Helper",
+          "description": "Parameter consumer"
+        }
+      },
+      "required": [
+        "consumer"
+      ],
+      "returns": "void"
+    }
+  },
+  "getters": {},
+  "events": {},
+  "state": {},
+  "options": {},
+  "envVars": []
+});
+
 // Container introspection data
 setContainerBuildTimeData('Container', {
   "className": "Container",
@@ -17254,7 +18495,7 @@ setContainerBuildTimeData('Container', {
         }
       ]
     },
-    "inspect": {
+    "introspect": {
       "description": "Returns a full introspection object for this container, merging build-time AST data (JSDoc descriptions, methods, getters) with runtime data (registries, factories, state, environment).",
       "parameters": {},
       "required": [],
@@ -17262,11 +18503,11 @@ setContainerBuildTimeData('Container', {
       "examples": [
         {
           "language": "ts",
-          "code": "const info = container.inspect()\nconsole.log(info.methods)   // all public methods with descriptions\nconsole.log(info.getters)   // all getters with return types\nconsole.log(info.registries) // features, clients, servers, etc."
+          "code": "const info = container.introspect()\nconsole.log(info.methods)   // all public methods with descriptions\nconsole.log(info.getters)   // all getters with return types\nconsole.log(info.registries) // features, clients, servers, etc."
         }
       ]
     },
-    "inspectAsText": {
+    "introspectAsText": {
       "description": "Returns a human-readable markdown representation of this container's introspection data. Useful in REPLs, AI agent contexts, or documentation generation. Pass a section name to render only that section (e.g. 'methods', 'getters', 'events', 'state').",
       "parameters": {
         "sectionOrDepth": {
@@ -17283,32 +18524,17 @@ setContainerBuildTimeData('Container', {
       "examples": [
         {
           "language": "ts",
-          "code": "console.log(container.inspectAsText())           // full description\nconsole.log(container.inspectAsText('methods'))   // just methods"
+          "code": "console.log(container.introspectAsText())           // full description\nconsole.log(container.introspectAsText('methods'))   // just methods"
         }
       ]
     },
-    "introspectAsText": {
-      "description": "Alias for inspectAsText.",
-      "parameters": {
-        "sectionOrDepth": {
-          "type": "IntrospectionSection | number",
-          "description": "Parameter sectionOrDepth"
-        },
-        "startHeadingDepth": {
-          "type": "number",
-          "description": "Parameter startHeadingDepth"
-        }
-      },
-      "required": [],
-      "returns": "string"
-    },
     "introspectAsJSON": {
-      "description": "Alias for inspect, returns JSON introspection data.",
+      "description": "Returns JSON introspection data.",
       "parameters": {},
       "required": [],
       "returns": "ContainerIntrospection"
     },
-    "inspectAsType": {
+    "introspectAsType": {
       "description": "Returns the container's introspection data formatted as a TypeScript interface declaration. Includes the container's own methods, getters, factories, and registered helper types.",
       "parameters": {},
       "required": [],
@@ -17316,16 +18542,10 @@ setContainerBuildTimeData('Container', {
       "examples": [
         {
           "language": "ts",
-          "code": "console.log(container.inspectAsType())\n// interface NodeContainer {\n//   feature<T>(id: string, options?: object): T;\n//   readonly uuid: string;\n//   ...\n// }"
+          "code": "console.log(container.introspectAsType())\n// interface NodeContainer {\n//   feature<T>(id: string, options?: object): T;\n//   readonly uuid: string;\n//   ...\n// }"
         }
       ]
     },
-    "introspectAsType": {
-      "description": "",
-      "parameters": {},
-      "required": [],
-      "returns": "string"
-    },
     "sleep": {
       "description": "Sleep for the specified number of milliseconds. Useful for scripting and sequencing.",
       "parameters": {
@@ -23428,6 +24648,311 @@ export const introspectionData = [
       }
     }
   },
+  {
+    "id": "features.redis",
+    "description": "Redis feature for shared state and pub/sub communication between container instances. Wraps ioredis with a focused API for the primitives that matter most: key/value state, pub/sub messaging, and cross-instance coordination. Uses a dedicated subscriber connection for pub/sub (ioredis requirement), created lazily on first subscribe call.",
+    "shortcut": "features.redis",
+    "className": "RedisFeature",
+    "methods": {
+      "set": {
+        "description": "Set a key to a string value with optional TTL.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The key name"
+          },
+          "value": {
+            "type": "string",
+            "description": "The string value to store"
+          },
+          "ttl": {
+            "type": "number",
+            "description": "Optional time-to-live in seconds"
+          }
+        },
+        "required": [
+          "key",
+          "value"
+        ],
+        "returns": "Promise<void>"
+      },
+      "get": {
+        "description": "Get a key's value. Returns null if the key doesn't exist.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The key name"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "returns": "Promise<string | null>"
+      },
+      "del": {
+        "description": "Delete one or more keys.",
+        "parameters": {
+          "keys": {
+            "type": "string[]",
+            "description": "One or more key names to delete"
+          }
+        },
+        "required": [
+          "keys"
+        ],
+        "returns": "Promise<number>"
+      },
+      "exists": {
+        "description": "Check if a key exists.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The key name"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "returns": "Promise<boolean>"
+      },
+      "expire": {
+        "description": "Set a key's TTL in seconds.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The key name"
+          },
+          "seconds": {
+            "type": "number",
+            "description": "TTL in seconds"
+          }
+        },
+        "required": [
+          "key",
+          "seconds"
+        ],
+        "returns": "Promise<boolean>"
+      },
+      "keys": {
+        "description": "Find keys matching a glob pattern (respects prefix).",
+        "parameters": {
+          "pattern": {
+            "type": "string",
+            "description": "Glob pattern, e.g. \"worker:*\""
+          }
+        },
+        "required": [],
+        "returns": "Promise<string[]>"
+      },
+      "setJSON": {
+        "description": "Store a value as JSON.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The key name"
+          },
+          "value": {
+            "type": "unknown",
+            "description": "Any JSON-serializable value"
+          },
+          "ttl": {
+            "type": "number",
+            "description": "Optional TTL in seconds"
+          }
+        },
+        "required": [
+          "key",
+          "value"
+        ],
+        "returns": "Promise<void>"
+      },
+      "getJSON": {
+        "description": "Retrieve and parse a JSON value.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The key name"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "returns": "Promise<T | null>"
+      },
+      "hset": {
+        "description": "Set fields on a hash.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The hash key"
+          },
+          "fields": {
+            "type": "Record<string, string>",
+            "description": "Object of field/value pairs"
+          }
+        },
+        "required": [
+          "key",
+          "fields"
+        ],
+        "returns": "Promise<void>"
+      },
+      "hgetall": {
+        "description": "Get all fields from a hash.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The hash key"
+          }
+        },
+        "required": [
+          "key"
+        ],
+        "returns": "Promise<Record<string, string>>"
+      },
+      "hget": {
+        "description": "Get a single field from a hash.",
+        "parameters": {
+          "key": {
+            "type": "string",
+            "description": "The hash key"
+          },
+          "field": {
+            "type": "string",
+            "description": "The field name"
+          }
+        },
+        "required": [
+          "key",
+          "field"
+        ],
+        "returns": "Promise<string | null>"
+      },
+      "subscribe": {
+        "description": "Subscribe to one or more channels. Optionally pass a handler that fires only for these channels. The feature also emits a `message` event for all messages.",
+        "parameters": {
+          "channels": {
+            "type": "string | string[]",
+            "description": "Channel name(s) to subscribe to"
+          },
+          "handler": {
+            "type": "MessageHandler",
+            "description": "Optional per-channel message handler"
+          }
+        },
+        "required": [
+          "channels"
+        ],
+        "returns": "Promise<void>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await redis.subscribe('tasks', (channel, msg) => {\n console.log(`Got ${msg} on ${channel}`)\n})"
+          }
+        ]
+      },
+      "unsubscribe": {
+        "description": "Unsubscribe from one or more channels.",
+        "parameters": {
+          "channels": {
+            "type": "string[]",
+            "description": "Channel name(s) to unsubscribe from"
+          }
+        },
+        "required": [
+          "channels"
+        ],
+        "returns": "Promise<void>"
+      },
+      "publish": {
+        "description": "Publish a message to a channel.",
+        "parameters": {
+          "channel": {
+            "type": "string",
+            "description": "The channel to publish to"
+          },
+          "message": {
+            "type": "string",
+            "description": "The message string (use JSON.stringify for objects)"
+          }
+        },
+        "required": [
+          "channel",
+          "message"
+        ],
+        "returns": "Promise<number>"
+      },
+      "ensureLocalDocker": {
+        "description": "Spin up a local Redis instance via Docker. Checks if a container with the given name already exists and starts it if stopped, or creates a new one from redis:alpine. Requires the docker feature to be available on the container.",
+        "parameters": {
+          "options": {
+            "type": "{ name?: string; port?: number; image?: string }",
+            "description": "Container name and host port"
+          }
+        },
+        "required": [],
+        "returns": "Promise<string>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const redis = container.feature('redis', { url: 'redis://localhost:6379', lazyConnect: true })\nawait redis.ensureLocalDocker()"
+          }
+        ]
+      },
+      "close": {
+        "description": "Close all redis connections (main client + subscriber).",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<this>"
+      }
+    },
+    "getters": {
+      "client": {
+        "description": "The underlying ioredis client for advanced operations.",
+        "returns": "Redis"
+      },
+      "subscriber": {
+        "description": "The dedicated subscriber connection, if pub/sub is active.",
+        "returns": "Redis | null"
+      }
+    },
+    "events": {
+      "message": {
+        "name": "message",
+        "description": "Event emitted by RedisFeature",
+        "arguments": {}
+      },
+      "error": {
+        "name": "error",
+        "description": "Event emitted by RedisFeature",
+        "arguments": {}
+      },
+      "subscribed": {
+        "name": "subscribed",
+        "description": "Event emitted by RedisFeature",
+        "arguments": {}
+      },
+      "unsubscribed": {
+        "name": "unsubscribed",
+        "description": "Event emitted by RedisFeature",
+        "arguments": {}
+      },
+      "closed": {
+        "name": "closed",
+        "description": "Event emitted by RedisFeature",
+        "arguments": {}
+      }
+    },
+    "state": {},
+    "options": {},
+    "envVars": [],
+    "examples": [
+      {
+        "language": "ts",
+        "code": "const redis = container.feature('redis', { url: 'redis://localhost:6379' })\n\n// Shared state\nawait redis.set('worker:status', 'active')\nconst status = await redis.get('worker:status')\n\n// Pub/sub between instances\nredis.on('message', (channel, msg) => console.log(`${channel}: ${msg}`))\nawait redis.subscribe('tasks')\nawait redis.publish('tasks', JSON.stringify({ type: 'ping' }))\n\n// JSON helpers\nawait redis.setJSON('config', { workers: 4, debug: true })\nconst config = await redis.getJSON<{ workers: number }>('config')"
+      }
+    ]
+  },
   {
     "id": "features.fs",
     "description": "The FS feature provides methods for interacting with the file system, relative to the container's cwd.",
@@ -25063,7 +26588,7 @@ export const introspectionData = [
   },
   {
     "id": "features.python",
-    "description": "The Python VM feature provides Python virtual machine capabilities for executing Python code. This feature automatically detects Python environments (uv, conda, venv, system) and provides methods to install dependencies and execute Python scripts. It can manage project-specific Python environments and maintain context between executions.",
+    "description": "The Python VM feature provides Python virtual machine capabilities for executing Python code. This feature automatically detects Python environments (uv, conda, venv, system) and provides methods to install dependencies and execute Python scripts. It can manage project-specific Python environments and maintain context between executions. Supports two modes: - **Stateless** (default): `execute()` and `executeFile()` spawn a fresh process per call - **Persistent session**: `startSession()` spawns a long-lived bridge process that maintains state across `run()` calls, enabling real codebase interaction with imports and session variables",
     "shortcut": "features.python",
     "className": "Python",
     "methods": {
@@ -25163,6 +26688,146 @@ export const introspectionData = [
         "parameters": {},
         "required": [],
         "returns": "Promise<{ version: string; path: string; packages: string[] }>"
+      },
+      "startSession": {
+        "description": "Starts a persistent Python session by spawning the bridge process. The bridge sets up sys.path for the project directory, then enters a JSON-line REPL loop. State (variables, imports) persists across run() calls until stopSession() or resetSession() is called.",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<void>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const python = container.feature('python', { dir: '/path/to/project' })\nawait python.enable()\nawait python.startSession()\nawait python.run('x = 42')\nconst result = await python.run('print(x)')\nconsole.log(result.stdout) // '42\\n'\nawait python.stopSession()"
+          }
+        ]
+      },
+      "stopSession": {
+        "description": "Stops the persistent Python session and cleans up the bridge process.",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<void>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.stopSession()"
+          }
+        ]
+      },
+      "run": {
+        "description": "Executes Python code in the persistent session. Variables and imports survive across calls. This is the session equivalent of execute().",
+        "parameters": {
+          "code": {
+            "type": "string",
+            "description": "Python code to execute"
+          },
+          "variables": {
+            "type": "Record<string, any>",
+            "description": "Variables to inject into the namespace before execution"
+          }
+        },
+        "required": [
+          "code"
+        ],
+        "returns": "Promise<RunResult>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.startSession()\n\n// State persists across calls\nawait python.run('x = 42')\nconst result = await python.run('print(x * 2)')\nconsole.log(result.stdout) // '84\\n'\n\n// Inject variables from JS\nconst result2 = await python.run('print(f\"Hello {name}!\")', { name: 'World' })\nconsole.log(result2.stdout) // 'Hello World!\\n'"
+          }
+        ]
+      },
+      "eval": {
+        "description": "Evaluates a Python expression in the persistent session and returns its value.",
+        "parameters": {
+          "expression": {
+            "type": "string",
+            "description": "Python expression to evaluate"
+          }
+        },
+        "required": [
+          "expression"
+        ],
+        "returns": "Promise<any>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.run('x = 42')\nconst result = await python.eval('x * 2')\nconsole.log(result) // 84"
+          }
+        ]
+      },
+      "importModule": {
+        "description": "Imports a Python module into the persistent session namespace.",
+        "parameters": {
+          "moduleName": {
+            "type": "string",
+            "description": "Dotted module path (e.g. 'myapp.models')"
+          },
+          "alias": {
+            "type": "string",
+            "description": "Optional alias for the import (defaults to the last segment)"
+          }
+        },
+        "required": [
+          "moduleName"
+        ],
+        "returns": "Promise<void>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.importModule('json')\nawait python.importModule('myapp.models', 'models')\nconst result = await python.eval('models.User')"
+          }
+        ]
+      },
+      "call": {
+        "description": "Calls a function by dotted path in the persistent session namespace.",
+        "parameters": {
+          "funcPath": {
+            "type": "string",
+            "description": "Dotted path to the function (e.g. 'json.dumps' or 'my_func')"
+          },
+          "args": {
+            "type": "any[]",
+            "description": "Positional arguments"
+          },
+          "kwargs": {
+            "type": "Record<string, any>",
+            "description": "Keyword arguments"
+          }
+        },
+        "required": [
+          "funcPath"
+        ],
+        "returns": "Promise<any>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.importModule('json')\nconst result = await python.call('json.dumps', [{ a: 1 }], { indent: 2 })"
+          }
+        ]
+      },
+      "getLocals": {
+        "description": "Returns all non-dunder variables from the persistent session namespace.",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<Record<string, any>>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.run('x = 42\\ny = \"hello\"')\nconst locals = await python.getLocals()\nconsole.log(locals) // { x: 42, y: 'hello' }"
+          }
+        ]
+      },
+      "resetSession": {
+        "description": "Clears all variables and imports from the persistent session namespace. The session remains active — you can continue calling run() after reset.",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<void>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "await python.run('x = 42')\nawait python.resetSession()\n// x is now undefined"
+          }
+        ]
       }
     },
     "getters": {
@@ -25219,6 +26884,21 @@ export const introspectionData = [
         "name": "fileExecuted",
         "description": "Event emitted by Python",
         "arguments": {}
+      },
+      "sessionError": {
+        "name": "sessionError",
+        "description": "Event emitted by Python",
+        "arguments": {}
+      },
+      "sessionStarted": {
+        "name": "sessionStarted",
+        "description": "Event emitted by Python",
+        "arguments": {}
+      },
+      "sessionStopped": {
+        "name": "sessionStopped",
+        "description": "Event emitted by Python",
+        "arguments": {}
       }
     },
     "state": {},
@@ -25227,9 +26907,38 @@ export const introspectionData = [
     "examples": [
       {
         "language": "ts",
-        "code": "const python = container.feature('python', { \n dir: \"/path/to/python/project\",\n contextScript: \"/path/to/setup-context.py\"\n})\n\n// Auto-install dependencies\nawait python.installDependencies()\n\n// Execute Python code\nconst result = await python.execute('print(\"Hello from Python!\")')\n\n// Execute with custom variables\nconst result2 = await python.execute('print(f\"Hello {name}!\")', { name: 'World' })"
+        "code": "const python = container.feature('python', {\n dir: \"/path/to/python/project\",\n})\n\n// Stateless execution\nconst result = await python.execute('print(\"Hello from Python!\")')\n\n// Persistent session\nawait python.startSession()\nawait python.run('import myapp.models')\nawait python.run('users = myapp.models.User.objects.all()')\nconst result = await python.run('print(len(users))')\nawait python.stopSession()"
       }
-    ]
+    ],
+    "types": {
+      "RunResult": {
+        "description": "Result from a persistent session run() call.",
+        "properties": {
+          "ok": {
+            "type": "boolean",
+            "description": ""
+          },
+          "result": {
+            "type": "any",
+            "description": ""
+          },
+          "stdout": {
+            "type": "string",
+            "description": ""
+          },
+          "error": {
+            "type": "string",
+            "description": "",
+            "optional": true
+          },
+          "traceback": {
+            "type": "string",
+            "description": "",
+            "optional": true
+          }
+        }
+      }
+    }
   },
   {
     "id": "features.jsonTree",
@@ -34009,6 +35718,302 @@ export const introspectionData = [
       }
     }
   },
+  {
+    "id": "features.lucaCoder",
+    "description": "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).",
+    "shortcut": "features.lucaCoder",
+    "className": "LucaCoder",
+    "methods": {
+      "getPermission": {
+        "description": "Get the effective permission level for a tool.",
+        "parameters": {
+          "toolName": {
+            "type": "string",
+            "description": "Parameter toolName"
+          }
+        },
+        "required": [
+          "toolName"
+        ],
+        "returns": "PermissionLevel"
+      },
+      "setPermission": {
+        "description": "Set permission level for one or more tools.",
+        "parameters": {
+          "toolName": {
+            "type": "string | string[]",
+            "description": "Parameter toolName"
+          },
+          "level": {
+            "type": "PermissionLevel",
+            "description": "Parameter level"
+          }
+        },
+        "required": [
+          "toolName",
+          "level"
+        ],
+        "returns": "this"
+      },
+      "setDefaultPermission": {
+        "description": "Set the default permission level for unconfigured tools.",
+        "parameters": {
+          "level": {
+            "type": "PermissionLevel",
+            "description": "Parameter level"
+          }
+        },
+        "required": [
+          "level"
+        ],
+        "returns": "this"
+      },
+      "permitTool": {
+        "description": "Allow a tool (or tools) to run without approval.",
+        "parameters": {
+          "toolNames": {
+            "type": "string[]",
+            "description": "Parameter toolNames"
+          }
+        },
+        "required": [
+          "toolNames"
+        ],
+        "returns": "this"
+      },
+      "gateTool": {
+        "description": "Require approval before a tool (or tools) can run.",
+        "parameters": {
+          "toolNames": {
+            "type": "string[]",
+            "description": "Parameter toolNames"
+          }
+        },
+        "required": [
+          "toolNames"
+        ],
+        "returns": "this"
+      },
+      "blockTool": {
+        "description": "Block a tool (or tools) from ever running.",
+        "parameters": {
+          "toolNames": {
+            "type": "string[]",
+            "description": "Parameter toolNames"
+          }
+        },
+        "required": [
+          "toolNames"
+        ],
+        "returns": "this"
+      },
+      "approve": {
+        "description": "Approve a pending tool call by ID. The tool will execute.",
+        "parameters": {
+          "id": {
+            "type": "string",
+            "description": "Parameter id"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "returns": "this"
+      },
+      "deny": {
+        "description": "Deny a pending tool call by ID. The tool call will be skipped.",
+        "parameters": {
+          "id": {
+            "type": "string",
+            "description": "Parameter id"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "returns": "this"
+      },
+      "approveAll": {
+        "description": "Approve all pending tool calls.",
+        "parameters": {},
+        "required": [],
+        "returns": "this"
+      },
+      "denyAll": {
+        "description": "Deny all pending tool calls.",
+        "parameters": {},
+        "required": [],
+        "returns": "this"
+      },
+      "bash": {
+        "description": "Execute a shell command string and return its output. Uses proc.execAndCapture under the hood — runs `sh -c <command>`.",
+        "parameters": {
+          "{ command, cwd, timeout }": {
+            "type": "{ command: string; cwd?: string; timeout?: number }",
+            "description": "Parameter { command, cwd, timeout }"
+          }
+        },
+        "required": [
+          "{ command, cwd, timeout }"
+        ],
+        "returns": "Promise<{\n\t\texitCode: number\n\t\tstdout: string\n\t\tstderr: string\n\t\tsuccess: boolean\n\t}>"
+      },
+      "start": {
+        "description": "Initialize the inner assistant, register the bash tool, stack tool bundles, auto-load skills, and wire up the permission interceptor.",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<this>"
+      },
+      "ask": {
+        "description": "Ask the coder a question. Auto-starts if needed. Tool calls will be gated by the permission system.",
+        "parameters": {
+          "question": {
+            "type": "string",
+            "description": "Parameter question"
+          },
+          "options": {
+            "type": "Record<string, any>",
+            "description": "Parameter options"
+          }
+        },
+        "required": [
+          "question"
+        ],
+        "returns": "Promise<string>"
+      },
+      "use": {
+        "description": "Add a tool bundle after initialization. Useful for dynamically extending the assistant's capabilities.",
+        "parameters": {
+          "spec": {
+            "type": "ToolBundleSpec",
+            "description": "Parameter spec"
+          }
+        },
+        "required": [
+          "spec"
+        ],
+        "returns": "this"
+      }
+    },
+    "getters": {
+      "assistant": {
+        "description": "The inner assistant. Throws if not started.",
+        "returns": "Assistant"
+      },
+      "permissions": {
+        "description": "Current permission map from state.",
+        "returns": "Record<string, PermissionLevel>"
+      },
+      "pendingApprovals": {
+        "description": "Current pending approvals.",
+        "returns": "PendingApproval[]"
+      },
+      "isStarted": {
+        "description": "Whether the assistant is started and ready.",
+        "returns": "boolean"
+      },
+      "tools": {
+        "description": "The tools registered on the inner assistant.",
+        "returns": "Record<string, any>"
+      },
+      "conversation": {
+        "description": "The conversation on the inner assistant (if started).",
+        "returns": "any"
+      },
+      "messages": {
+        "description": "Messages from the inner assistant's conversation.",
+        "returns": "any"
+      }
+    },
+    "events": {
+      "permissionGranted": {
+        "name": "permissionGranted",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "permissionDenied": {
+        "name": "permissionDenied",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "toolBlocked": {
+        "name": "toolBlocked",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "chunk": {
+        "name": "chunk",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "response": {
+        "name": "response",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "toolCall": {
+        "name": "toolCall",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "toolResult": {
+        "name": "toolResult",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "toolError": {
+        "name": "toolError",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "started": {
+        "name": "started",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      },
+      "permissionRequest": {
+        "name": "permissionRequest",
+        "description": "Event emitted by LucaCoder",
+        "arguments": {}
+      }
+    },
+    "state": {},
+    "options": {},
+    "envVars": [],
+    "examples": [
+      {
+        "language": "ts",
+        "code": "const coder = container.feature('lucaCoder', {\n tools: ['fileTools'],\n permissions: {\n   readFile: 'allow',\n   searchFiles: 'allow',\n   writeFile: 'ask',\n   bash: 'ask',\n },\n defaultPermission: 'ask',\n systemPrompt: 'You are a coding assistant.',\n})\n\ncoder.on('permissionRequest', ({ id, toolName, args }) => {\n console.log(`Tool \"${toolName}\" wants to run with`, args)\n coder.approve(id)  // or coder.deny(id)\n})\n\nawait coder.ask('Refactor the auth module to use async/await')"
+      }
+    ],
+    "types": {
+      "PendingApproval": {
+        "description": "A pending approval awaiting user decision.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": ""
+          },
+          "toolName": {
+            "type": "string",
+            "description": ""
+          },
+          "args": {
+            "type": "Record<string, any>",
+            "description": ""
+          },
+          "timestamp": {
+            "type": "number",
+            "description": ""
+          },
+          "resolve": {
+            "type": "(decision: 'approve' | 'deny') => void",
+            "description": ""
+          }
+        }
+      }
+    }
+  },
   {
     "id": "features.conversationHistory",
     "description": "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.",
@@ -34487,6 +36492,458 @@ export const introspectionData = [
         }
       }
     }
+  },
+  {
+    "id": "features.autoAssistant",
+    "description": "An autonomous assistant that owns a lower-level Assistant instance and gates all tool calls through a permission system. Tools are stacked from feature bundles (fileTools, processManager, etc.) and each tool can be set to 'allow' (runs immediately), 'ask' (blocks until user approves/denies), or 'deny' (always rejected).",
+    "shortcut": "features.autoAssistant",
+    "className": "AutonomousAssistant",
+    "methods": {
+      "getPermission": {
+        "description": "Get the effective permission level for a tool.",
+        "parameters": {
+          "toolName": {
+            "type": "string",
+            "description": "Parameter toolName"
+          }
+        },
+        "required": [
+          "toolName"
+        ],
+        "returns": "PermissionLevel"
+      },
+      "setPermission": {
+        "description": "Set permission level for one or more tools.",
+        "parameters": {
+          "toolName": {
+            "type": "string | string[]",
+            "description": "Parameter toolName"
+          },
+          "level": {
+            "type": "PermissionLevel",
+            "description": "Parameter level"
+          }
+        },
+        "required": [
+          "toolName",
+          "level"
+        ],
+        "returns": "this"
+      },
+      "setDefaultPermission": {
+        "description": "Set the default permission level for unconfigured tools.",
+        "parameters": {
+          "level": {
+            "type": "PermissionLevel",
+            "description": "Parameter level"
+          }
+        },
+        "required": [
+          "level"
+        ],
+        "returns": "this"
+      },
+      "permitTool": {
+        "description": "Allow a tool (or tools) to run without approval.",
+        "parameters": {
+          "toolNames": {
+            "type": "string[]",
+            "description": "Parameter toolNames"
+          }
+        },
+        "required": [
+          "toolNames"
+        ],
+        "returns": "this"
+      },
+      "gateTool": {
+        "description": "Require approval before a tool (or tools) can run.",
+        "parameters": {
+          "toolNames": {
+            "type": "string[]",
+            "description": "Parameter toolNames"
+          }
+        },
+        "required": [
+          "toolNames"
+        ],
+        "returns": "this"
+      },
+      "blockTool": {
+        "description": "Block a tool (or tools) from ever running.",
+        "parameters": {
+          "toolNames": {
+            "type": "string[]",
+            "description": "Parameter toolNames"
+          }
+        },
+        "required": [
+          "toolNames"
+        ],
+        "returns": "this"
+      },
+      "approve": {
+        "description": "Approve a pending tool call by ID. The tool will execute.",
+        "parameters": {
+          "id": {
+            "type": "string",
+            "description": "Parameter id"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "returns": "this"
+      },
+      "deny": {
+        "description": "Deny a pending tool call by ID. The tool call will be skipped.",
+        "parameters": {
+          "id": {
+            "type": "string",
+            "description": "Parameter id"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "returns": "this"
+      },
+      "approveAll": {
+        "description": "Approve all pending tool calls.",
+        "parameters": {},
+        "required": [],
+        "returns": "this"
+      },
+      "denyAll": {
+        "description": "Deny all pending tool calls.",
+        "parameters": {},
+        "required": [],
+        "returns": "this"
+      },
+      "start": {
+        "description": "Initialize the inner assistant, stack tool bundles, and wire up the permission interceptor.",
+        "parameters": {},
+        "required": [],
+        "returns": "Promise<this>"
+      },
+      "ask": {
+        "description": "Ask the autonomous assistant a question. Auto-starts if needed. Tool calls will be gated by the permission system.",
+        "parameters": {
+          "question": {
+            "type": "string",
+            "description": "Parameter question"
+          },
+          "options": {
+            "type": "Record<string, any>",
+            "description": "Parameter options"
+          }
+        },
+        "required": [
+          "question"
+        ],
+        "returns": "Promise<string>"
+      },
+      "use": {
+        "description": "Add a tool bundle after initialization. Useful for dynamically extending the assistant's capabilities.",
+        "parameters": {
+          "spec": {
+            "type": "ToolBundleSpec",
+            "description": "Parameter spec"
+          }
+        },
+        "required": [
+          "spec"
+        ],
+        "returns": "this"
+      }
+    },
+    "getters": {
+      "assistant": {
+        "description": "The inner assistant. Throws if not started.",
+        "returns": "Assistant"
+      },
+      "permissions": {
+        "description": "Current permission map from state.",
+        "returns": "Record<string, PermissionLevel>"
+      },
+      "pendingApprovals": {
+        "description": "Current pending approvals.",
+        "returns": "PendingApproval[]"
+      },
+      "isStarted": {
+        "description": "Whether the assistant is started and ready.",
+        "returns": "boolean"
+      },
+      "tools": {
+        "description": "The tools registered on the inner assistant.",
+        "returns": "Record<string, any>"
+      },
+      "conversation": {
+        "description": "The conversation on the inner assistant (if started).",
+        "returns": "any"
+      },
+      "messages": {
+        "description": "Messages from the inner assistant's conversation.",
+        "returns": "any"
+      }
+    },
+    "events": {
+      "permissionGranted": {
+        "name": "permissionGranted",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "permissionDenied": {
+        "name": "permissionDenied",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "toolBlocked": {
+        "name": "toolBlocked",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "chunk": {
+        "name": "chunk",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "response": {
+        "name": "response",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "toolCall": {
+        "name": "toolCall",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "toolResult": {
+        "name": "toolResult",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "toolError": {
+        "name": "toolError",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "started": {
+        "name": "started",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      },
+      "permissionRequest": {
+        "name": "permissionRequest",
+        "description": "Event emitted by AutonomousAssistant",
+        "arguments": {}
+      }
+    },
+    "state": {},
+    "options": {},
+    "envVars": [],
+    "examples": [
+      {
+        "language": "ts",
+        "code": "const auto = container.feature('autoAssistant', {\n tools: ['fileTools', { feature: 'processManager', except: ['killAllProcesses'] }],\n permissions: {\n   readFile: 'allow',\n   searchFiles: 'allow',\n   writeFile: 'ask',\n   editFile: 'ask',\n   deleteFile: 'deny',\n },\n defaultPermission: 'ask',\n systemPrompt: 'You are a coding assistant.',\n})\n\nauto.on('permissionRequest', ({ id, toolName, args }) => {\n console.log(`Tool \"${toolName}\" wants to run with`, args)\n // Show UI, then:\n auto.approve(id)  // or auto.deny(id)\n})\n\nawait auto.ask('Refactor the auth module to use async/await')"
+      }
+    ],
+    "types": {
+      "PendingApproval": {
+        "description": "A pending approval awaiting user decision.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": ""
+          },
+          "toolName": {
+            "type": "string",
+            "description": ""
+          },
+          "args": {
+            "type": "Record<string, any>",
+            "description": ""
+          },
+          "timestamp": {
+            "type": "number",
+            "description": ""
+          },
+          "resolve": {
+            "type": "(decision: 'approve' | 'deny') => void",
+            "description": ""
+          }
+        }
+      }
+    }
+  },
+  {
+    "id": "features.fileTools",
+    "description": "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'] })) ```",
+    "shortcut": "features.fileTools",
+    "className": "FileTools",
+    "methods": {
+      "readFile": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path: string; offset?: number; limit?: number }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "writeFile": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path: string; content: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "editFile": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path: string; oldString: string; newString: string; replaceAll?: boolean }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "listDirectory": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path?: string; recursive?: boolean; include?: string; exclude?: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "searchFiles": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ pattern: string; path?: string; include?: string; exclude?: string; ignoreCase?: boolean; maxResults?: number }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "findFiles": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ pattern: string; path?: string; exclude?: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "fileInfo": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "createDirectory": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "moveFile": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ source: string; destination: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "copyFile": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ source: string; destination: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "deleteFile": {
+        "description": "",
+        "parameters": {
+          "args": {
+            "type": "{ path: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "Promise<string>"
+      },
+      "setupToolsConsumer": {
+        "description": "When an assistant uses fileTools, inject system prompt guidance about how to use the tools effectively.",
+        "parameters": {
+          "consumer": {
+            "type": "Helper",
+            "description": "Parameter consumer"
+          }
+        },
+        "required": [
+          "consumer"
+        ],
+        "returns": "void"
+      }
+    },
+    "getters": {},
+    "events": {},
+    "state": {},
+    "options": {},
+    "envVars": []
   }
 ];
 
@@ -34721,7 +37178,7 @@ export const containerIntrospectionData = [
           }
         ]
       },
-      "inspect": {
+      "introspect": {
         "description": "Returns a full introspection object for this container, merging build-time AST data (JSDoc descriptions, methods, getters) with runtime data (registries, factories, state, environment).",
         "parameters": {},
         "required": [],
@@ -34729,11 +37186,11 @@ export const containerIntrospectionData = [
         "examples": [
           {
             "language": "ts",
-            "code": "const info = container.inspect()\nconsole.log(info.methods)   // all public methods with descriptions\nconsole.log(info.getters)   // all getters with return types\nconsole.log(info.registries) // features, clients, servers, etc."
+            "code": "const info = container.introspect()\nconsole.log(info.methods)   // all public methods with descriptions\nconsole.log(info.getters)   // all getters with return types\nconsole.log(info.registries) // features, clients, servers, etc."
           }
         ]
       },
-      "inspectAsText": {
+      "introspectAsText": {
         "description": "Returns a human-readable markdown representation of this container's introspection data. Useful in REPLs, AI agent contexts, or documentation generation. Pass a section name to render only that section (e.g. 'methods', 'getters', 'events', 'state').",
         "parameters": {
           "sectionOrDepth": {
@@ -34750,32 +37207,17 @@ export const containerIntrospectionData = [
         "examples": [
           {
             "language": "ts",
-            "code": "console.log(container.inspectAsText())           // full description\nconsole.log(container.inspectAsText('methods'))   // just methods"
+            "code": "console.log(container.introspectAsText())           // full description\nconsole.log(container.introspectAsText('methods'))   // just methods"
           }
         ]
       },
-      "introspectAsText": {
-        "description": "Alias for inspectAsText.",
-        "parameters": {
-          "sectionOrDepth": {
-            "type": "IntrospectionSection | number",
-            "description": "Parameter sectionOrDepth"
-          },
-          "startHeadingDepth": {
-            "type": "number",
-            "description": "Parameter startHeadingDepth"
-          }
-        },
-        "required": [],
-        "returns": "string"
-      },
       "introspectAsJSON": {
-        "description": "Alias for inspect, returns JSON introspection data.",
+        "description": "Returns JSON introspection data.",
         "parameters": {},
         "required": [],
         "returns": "ContainerIntrospection"
       },
-      "inspectAsType": {
+      "introspectAsType": {
         "description": "Returns the container's introspection data formatted as a TypeScript interface declaration. Includes the container's own methods, getters, factories, and registered helper types.",
         "parameters": {},
         "required": [],
@@ -34783,16 +37225,10 @@ export const containerIntrospectionData = [
         "examples": [
           {
             "language": "ts",
-            "code": "console.log(container.inspectAsType())\n// interface NodeContainer {\n//   feature<T>(id: string, options?: object): T;\n//   readonly uuid: string;\n//   ...\n// }"
+            "code": "console.log(container.introspectAsType())\n// interface NodeContainer {\n//   feature<T>(id: string, options?: object): T;\n//   readonly uuid: string;\n//   ...\n// }"
           }
         ]
       },
-      "introspectAsType": {
-        "description": "",
-        "parameters": {},
-        "required": [],
-        "returns": "string"
-      },
       "sleep": {
         "description": "Sleep for the specified number of milliseconds. Useful for scripting and sequencing.",
         "parameters": {