@soederpop/luca 0.0.32 → 0.0.34

package/src/python/generated.ts

@@ -0,0 +1,227 @@
+// Auto-generated Python bridge script
+// Generated at: 2026-03-26T03:30:23.085Z
+// Source: src/python/bridge.py
+//
+// Do not edit manually. Run: luca build-python-bridge
+
+export const bridgeScript = `#!/usr/bin/env python3
+"""Luca Python Bridge - persistent interactive Python session.
+
+Communicates via JSON lines over stdin/stdout. Each request is a single
+JSON object per line on stdin; each response is a single JSON object per
+line on stdout. User print() output is captured per-execution via
+io.StringIO so it never corrupts the protocol.
+
+Python 3.8+ compatible (stdlib only).
+"""
+import sys
+import json
+import io
+import traceback
+import os
+
+# Persistent namespace shared across all exec/eval calls
+_namespace = {"__builtins__": __builtins__}
+
+
+def setup_sys_path(project_dir):
+    """Insert project_dir and common sub-paths into sys.path."""
+    paths_to_add = [project_dir]
+
+    # src/ layout (PEP 621 / setuptools)
+    src_dir = os.path.join(project_dir, "src")
+    if os.path.isdir(src_dir):
+        paths_to_add.append(src_dir)
+
+    # lib/ layout (less common but exists)
+    lib_dir = os.path.join(project_dir, "lib")
+    if os.path.isdir(lib_dir):
+        paths_to_add.append(lib_dir)
+
+    for p in reversed(paths_to_add):
+        if p not in sys.path:
+            sys.path.insert(0, p)
+
+
+def _safe_serialize(value):
+    """Attempt JSON serialization; fall back to repr()."""
+    try:
+        json.dumps(value, default=str)
+        return value
+    except (TypeError, ValueError, OverflowError):
+        return repr(value)
+
+
+def handle_exec(req):
+    """Execute code in the persistent namespace."""
+    code = req.get("code", "")
+    variables = req.get("variables", {})
+    _namespace.update(variables)
+
+    old_stdout = sys.stdout
+    captured = io.StringIO()
+    sys.stdout = captured
+    try:
+        exec(code, _namespace)
+        sys.stdout = old_stdout
+        return {"ok": True, "stdout": captured.getvalue(), "result": None}
+    except Exception as e:
+        sys.stdout = old_stdout
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+            "stdout": captured.getvalue(),
+        }
+
+
+def handle_eval(req):
+    """Evaluate an expression and return its value."""
+    expression = req.get("expression", "")
+
+    old_stdout = sys.stdout
+    captured = io.StringIO()
+    sys.stdout = captured
+    try:
+        result = eval(expression, _namespace)
+        sys.stdout = old_stdout
+        return {
+            "ok": True,
+            "result": _safe_serialize(result),
+            "stdout": captured.getvalue(),
+        }
+    except Exception as e:
+        sys.stdout = old_stdout
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+            "stdout": captured.getvalue(),
+        }
+
+
+def handle_import(req):
+    """Import a module into the namespace."""
+    module_name = req.get("module", "")
+    alias = req.get("alias", module_name.split(".")[-1])
+    try:
+        mod = __import__(
+            module_name,
+            fromlist=[module_name.split(".")[-1]] if "." in module_name else [],
+        )
+        _namespace[alias] = mod
+        return {"ok": True, "result": "Imported {} as {}".format(module_name, alias)}
+    except Exception as e:
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+        }
+
+
+def handle_call(req):
+    """Call a function by dotted path in the namespace."""
+    func_path = req.get("function", "")
+    args = req.get("args", [])
+    kwargs = req.get("kwargs", {})
+
+    old_stdout = sys.stdout
+    captured = io.StringIO()
+    sys.stdout = captured
+    try:
+        parts = func_path.split(".")
+        obj = _namespace[parts[0]]
+        for part in parts[1:]:
+            obj = getattr(obj, part)
+        result = obj(*args, **kwargs)
+        sys.stdout = old_stdout
+        return {
+            "ok": True,
+            "result": _safe_serialize(result),
+            "stdout": captured.getvalue(),
+        }
+    except Exception as e:
+        sys.stdout = old_stdout
+        return {
+            "ok": False,
+            "error": str(e),
+            "traceback": traceback.format_exc(),
+            "stdout": captured.getvalue(),
+        }
+
+
+def handle_get_locals(req):
+    """Return all non-dunder keys from the namespace."""
+    safe = {}
+    for k, v in _namespace.items():
+        if k.startswith("__"):
+            continue
+        safe[k] = _safe_serialize(v)
+    return {"ok": True, "result": safe}
+
+
+def handle_reset(req):
+    """Clear the namespace."""
+    _namespace.clear()
+    _namespace["__builtins__"] = __builtins__
+    return {"ok": True, "result": "Session reset"}
+
+
+HANDLERS = {
+    "exec": handle_exec,
+    "eval": handle_eval,
+    "import": handle_import,
+    "call": handle_call,
+    "get_locals": handle_get_locals,
+    "reset": handle_reset,
+}
+
+
+def main():
+    # First line from stdin is the init handshake with project_dir
+    init_line = sys.stdin.readline().strip()
+    if init_line:
+        try:
+            init = json.loads(init_line)
+            if "project_dir" in init:
+                setup_sys_path(init["project_dir"])
+        except json.JSONDecodeError:
+            pass
+
+    # Signal ready
+    sys.stdout.write(json.dumps({"ok": True, "type": "ready"}) + "\\n")
+    sys.stdout.flush()
+
+    # Main loop: read JSON commands, execute, respond
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError as e:
+            resp = {"ok": False, "error": "Invalid JSON: {}".format(e)}
+            sys.stdout.write(json.dumps(resp) + "\\n")
+            sys.stdout.flush()
+            continue
+
+        req_id = req.get("id")
+        req_type = req.get("type", "exec")
+        handler = HANDLERS.get(req_type)
+
+        if not handler:
+            resp = {"ok": False, "error": "Unknown request type: {}".format(req_type)}
+        else:
+            resp = handler(req)
+
+        if req_id:
+            resp["id"] = req_id
+
+        sys.stdout.write(json.dumps(resp, default=str) + "\\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()
+`

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-24T09:09:10.786Z
+// Generated at: 2026-03-26T03:30:21.414Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/test/python-session.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test'
+
+describe('Python Persistent Session', () => {
+  let container: any
+  let python: any
+
+  beforeAll(async () => {
+    const mod = await import('../src/node.js')
+    container = mod.default
+    python = container.feature('python', { dir: container.cwd })
+    await python.enable()
+    await python.startSession()
+  })
+
+  afterAll(async () => {
+    if (python?.state?.get('sessionActive')) {
+      await python.stopSession()
+    }
+  })
+
+  it('session is active after start', () => {
+    expect(python.state.get('sessionActive')).toBe(true)
+    expect(python.state.get('sessionId')).toBeTruthy()
+  })
+
+  it('run() executes code and captures stdout', async () => {
+    const result = await python.run('print("hello from bridge")')
+    expect(result.ok).toBe(true)
+    expect(result.stdout).toContain('hello from bridge')
+  })
+
+  it('state persists across calls', async () => {
+    await python.run('x = 42')
+    const result = await python.eval('x + 1')
+    expect(result).toBe(43)
+  })
+
+  it('variables are injected', async () => {
+    const result = await python.run('print(name)', { name: 'luca' })
+    expect(result.ok).toBe(true)
+    expect(result.stdout).toContain('luca')
+  })
+
+  it('importModule() works', async () => {
+    await python.importModule('json')
+    const result = await python.eval('json.dumps({"a": 1})')
+    expect(result).toBe('{"a": 1}')
+  })
+
+  it('call() invokes functions', async () => {
+    await python.run('def add(a, b): return a + b')
+    const result = await python.call('add', [3, 4])
+    expect(result).toBe(7)
+  })
+
+  it('getLocals() returns namespace', async () => {
+    await python.run('y = 99')
+    const locals = await python.getLocals()
+    expect(locals.y).toBe(99)
+    expect(locals.x).toBe(42)
+  })
+
+  it('handles errors gracefully without crashing the session', async () => {
+    const result = await python.run('raise ValueError("test error")')
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('test error')
+    // Session should still be alive
+    const check = await python.run('print("still alive")')
+    expect(check.ok).toBe(true)
+    expect(check.stdout).toContain('still alive')
+  })
+
+  it('resetSession() clears state', async () => {
+    await python.run('z = 123')
+    await python.resetSession()
+    const result = await python.run('print(z)')
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('is not defined')
+  })
+
+  it('stopSession() cleans up', async () => {
+    await python.stopSession()
+    expect(python.state.get('sessionActive')).toBe(false)
+    expect(python.state.get('sessionId')).toBeNull()
+  })
+
+  it('can start a new session after stopping', async () => {
+    await python.startSession()
+    expect(python.state.get('sessionActive')).toBe(true)
+    const result = await python.run('print("fresh session")')
+    expect(result.ok).toBe(true)
+    expect(result.stdout).toContain('fresh session')
+  })
+})
+
+describe('Python backward compatibility', () => {
+  it('execute() still works without a session', async () => {
+    const mod = await import('../src/node.js')
+    const container = mod.default
+    const python = container.feature('python', { dir: container.cwd })
+    await python.enable()
+    const result = await python.execute('print("stateless")')
+    expect(result.stdout).toContain('stateless')
+  })
+})

package/assistants/lucaExpert/CORE.md

@@ -1,37 +0,0 @@
-# Luca Framework Expert
-
-You are a Luca framework expert. You have deep knowledge of the container architecture, its features, clients, servers, commands, and how to build with them. Your job is to help people understand, use, and build on the Luca framework.
-
-You have powerful tools to explore the framework at runtime — use them liberally before answering questions. Don't guess when you can look it up.
-
-## Your Tools
-
-### Discovery & Documentation
-
-- **readSkill** — Read the SKILL.md learning guide and follow referenced documentation. Start here when orienting yourself.
-- **readDoc** — Read any document from the docs/ folder: examples, tutorials, API references, scaffolds. Use `list` mode to browse what's available in a category, or `read` mode to get the full content.
-- **lucaDescribe** — Run `luca describe` to get live documentation for any feature, client, server, or specific method/getter. This is generated from the actual source code and is always current. Use dot notation (`fs.readFile`, `ui.banner`) to drill into specific members.
-
-### Live Code Execution
-
-- **lucaEval** — Execute JavaScript/TypeScript in a live container sandbox. All features are available as top-level variables (fs, git, proc, vm, etc). The last expression's value is returned. For async code, put the await call as the last expression.
-
-### Deep Research
-
-- **askCodingAssistant** — Delegate deep codebase research to the coding assistant, who has ripgrep, cat, ls, sed, and awk at its disposal. Use this when you need to understand implementation details, trace code paths, or find patterns across files that the documentation doesn't cover.
-
-## How to Work
-
-1. **Start with describe.** When asked about any feature, client, or server — run `lucaDescribe` first. It's the fastest path to accurate information.
-2. **Consult docs for depth.** Use `readDoc` to pull up examples, tutorials, and API docs when you need patterns, best practices, or complete working code.
-3. **Eval to verify.** When uncertain about behavior, run it. `lucaEval` gives you a live container — test the actual API rather than speculating.
-4. **Delegate research.** When you need to understand how something is implemented (not just how to use it), ask the codingAssistant to dig into the source.
-5. **Read the SKILL.md** via `readSkill` when you need to orient a user to the framework's learning path.
-
-## Response Style
-
-- Lead with working code examples when possible
-- Reference specific methods and their signatures
-- Explain the "why" behind patterns, not just the "what"
-- When a user's approach conflicts with framework conventions, explain the idiomatic way and why it matters
-- Be concise but thorough — framework users need precision

package/assistants/lucaExpert/hooks.ts

@@ -1,9 +0,0 @@
-import type { Assistant } from '@soederpop/luca/agi'
-
-declare global {
-	var assistant: Assistant
-}
-
-export function started() {
-	console.log('Luca Expert assistant started')
-}

package/assistants/lucaExpert/tools.ts

@@ -1,177 +0,0 @@
-import { z } from 'zod'
-import type { Assistant, AGIContainer } from '@soederpop/luca/agi'
-
-declare global {
-	var assistant: Assistant
-	var container: AGIContainer
-}
-
-const proc = () => container.feature('proc')
-const fs = () => container.feature('fs')
-
-// ---------------------------------------------------------------------------
-// readSkill — Read the SKILL.md and progressively discover referenced docs
-// ---------------------------------------------------------------------------
-
-export const schemas = {
-	readSkill: z.object({
-		section: z.string().default('').describe(
-			'Section to focus on (e.g. "Phase 1", "Phase 2", "Key Concepts"). Leave empty for the full SKILL.md.'
-		),
-	}).describe('Read the SKILL.md learning guide for the Luca framework. Use this to orient yourself or a user to how the framework is learned and used.'),
-
-	readDoc: z.object({
-		mode: z.enum(['list', 'read']).describe(
-			'"list" to browse available documents in a category, "read" to get full content of a specific document'
-		),
-		category: z.string().default('').describe(
-			'Document category: examples, tutorials, apis, apis/features/node, apis/features/agi, apis/features/web, apis/clients, apis/servers, challenges, prompts, scaffolds, sessions, bootstrap. Leave empty when using mode "read".'
-		),
-		path: z.string().default('').describe(
-			'Relative path within docs/ to read (e.g. "examples/fs.md", "tutorials/00-bootstrap.md"). Required when mode is "read". Leave empty when using mode "list".'
-		),
-	}).describe('Browse and read documentation from the docs/ folder — examples, tutorials, API references, scaffolds, and more.'),
-
-	lucaDescribe: z.object({
-		args: z.string().describe(
-			'Arguments to pass to luca describe. Examples: "fs", "git", "features", "clients", "servers", "fs.readFile", "ui.banner", "express --options", "fs --methods", "fs git --examples"'
-		),
-	}).describe('Run the luca describe CLI to get live, source-generated documentation for any feature, client, server, or specific method/getter. This is always current.'),
-
-	lucaEval: z.object({
-		code: z.string().describe(
-			'JavaScript/TypeScript code to run in a live container. All features available as top-level vars (fs, git, proc, vm, etc). The last expression value is returned. For async: put the await expression on the last line.'
-		),
-	}).describe('Execute code in a live Luca container sandbox. Use this to test APIs, verify behavior, and prototype ideas. Top-level await is supported — put async calls as the last expression to capture their result.'),
-
-	askCodingAssistant: z.object({
-		question: z.string().describe(
-			'A research question for the coding assistant. Be specific about what you want to find: file paths, function implementations, patterns, class hierarchies, etc.'
-		),
-	}).describe('Delegate deep codebase research to the coding assistant who has ripgrep, cat, ls, sed, and awk. Use for implementation details, tracing code paths, or finding patterns the docs do not cover.'),
-}
-
-export function readSkill({ section }: z.infer<typeof schemas.readSkill>): string {
-	const skillPath = 'docs/bootstrap/SKILL.md'
-
-	if (!fs().exists(skillPath)) {
-		return 'SKILL.md not found at docs/bootstrap/SKILL.md'
-	}
-
-	const content = fs().readFile(skillPath)
-
-	if (!section || !section.trim()) return content
-
-	// Extract section by heading match
-	const lines = content.split('\n')
-	const sectionLines: string[] = []
-	let capturing = false
-	let sectionLevel = 0
-
-	for (const line of lines) {
-		const headingMatch = line.match(/^(#{1,6})\s+(.*)/)
-
-		if (headingMatch) {
-			const level = headingMatch[1].length
-			const title = headingMatch[2]
-
-			if (capturing && level <= sectionLevel) break
-
-			if (title.toLowerCase().includes(section.toLowerCase())) {
-				capturing = true
-				sectionLevel = level
-			}
-		}
-
-		if (capturing) sectionLines.push(line)
-	}
-
-	return sectionLines.length > 0
-		? sectionLines.join('\n')
-		: `Section "${section}" not found in SKILL.md. Available sections:\n${lines.filter(l => l.startsWith('#')).join('\n')}`
-}
-
-export function readDoc({ mode, category, path: docPath }: z.infer<typeof schemas.readDoc>): string {
-	if (mode === 'list') {
-		const dir = category ? `docs/${category}` : 'docs'
-
-		if (!fs().exists(dir)) {
-			return `Directory "${dir}" not found. Available top-level categories:\n${fs().readdirSync('docs').join('\n')}`
-		}
-
-		const entries = fs().readdirSync(dir)
-		return `Contents of ${dir}/:\n${entries.join('\n')}`
-	}
-
-	// mode === 'read'
-	if (!docPath) {
-		return 'Error: path is required when mode is "read". Use mode "list" to browse available docs first.'
-	}
-
-	const fullPath = docPath.startsWith('docs/') ? docPath : `docs/${docPath}`
-
-	if (!fs().exists(fullPath)) {
-		return `Document not found: ${fullPath}`
-	}
-
-	return fs().readFile(fullPath)
-}
-
-export function lucaDescribe({ args }: z.infer<typeof schemas.lucaDescribe>): string {
-	try {
-		return proc().exec(`bun run src/cli/cli.ts describe ${args}`)
-	} catch (err: any) {
-		return `Error running luca describe ${args}: ${err.message || err}`
-	}
-}
-
-export async function lucaEval({ code }: z.infer<typeof schemas.lucaEval>): Promise<string> {
-	try {
-		const vm = container.feature('vm')
-		const { result, console: calls } = await vm.runCaptured(code, {
-			container,
-			fs: container.feature('fs'),
-			git: container.feature('git'),
-			proc: container.feature('proc'),
-			vm,
-			ui: container.feature('ui'),
-			os: container.feature('os'),
-			grep: container.feature('grep'),
-			networking: container.feature('networking'),
-		})
-
-		const parts: string[] = []
-
-		if (calls.length > 0) {
-			const consoleLines = calls.map(c => {
-				const prefix = c.method === 'log' ? '' : `[${c.method}] `
-				return prefix + c.args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' ')
-			})
-			parts.push(consoleLines.join('\n'))
-		}
-
-		if (result === undefined) {
-			parts.push('(undefined)')
-		} else if (result === null) {
-			parts.push('(null)')
-		} else if (typeof result === 'string') {
-			parts.push(result)
-		} else {
-			try { parts.push(JSON.stringify(result, null, 2)) } catch { parts.push(String(result)) }
-		}
-
-		return parts.join('\n')
-	} catch (err: any) {
-		return `Eval error: ${err.message || err}`
-	}
-}
-
-export async function askCodingAssistant({ question }: z.infer<typeof schemas.askCodingAssistant>): Promise<string> {
-	try {
-		const sub = await assistant.subagent('codingAssistant')
-		const answer = await sub.ask(question)
-		return answer
-	} catch (err: any) {
-		return `Error asking coding assistant: ${err.message || err}`
-	}
-}