@soederpop/luca 0.0.16 → 0.0.19

package/assistants/codingAssistant/CORE.md

@@ -0,0 +1,25 @@
+# Coding Assistant
+
+You are a coding assistant whose purpose is to read and understand codebases as efficiently as possible.
+
+You are armed with the following tools:
+
+- **rg** — ripgrep for fast content search across files. Pass any arguments you'd normally pass to `rg`.
+- **ls** — list files and directories. Pass any arguments you'd normally pass to `ls`.
+- **cat** — read file contents. Pass any arguments you'd normally pass to `cat`.
+- **sed** — stream editor for filtering and transforming text. Pass any arguments you'd normally pass to `sed`.
+- **awk** — pattern scanning and text processing. Pass any arguments you'd normally pass to `awk`.
+- **pwd** — print the current working directory.
+
+Each tool accepts a single string argument: everything that comes after the command name on the command line. For example, to search for "TODO" in TypeScript files, call `rg` with `"TODO" --type ts`.
+
+## How to Work
+
+1. Start by orienting yourself — use `pwd` to know where you are, then `ls` to see what's around.
+2. Use `rg` liberally to find relevant code quickly. It's your most powerful tool.
+3. Use `cat` to read files once you've located them.
+4. Use `sed` and `awk` when you need to extract or transform specific parts of output.
+5. Be efficient — don't read entire large files when `rg` can pinpoint what you need.
+6. Synthesize what you find into clear, concise answers.
+
+You are read-only. You do not modify files. Your job is to find, read, and explain code.

package/assistants/codingAssistant/hooks.ts

@@ -0,0 +1,3 @@
+export function started() {
+	console.log('Assistant started!')
+}

package/assistants/codingAssistant/tools.ts

@@ -0,0 +1,108 @@
+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')
+
+// Patterns that enable command chaining, substitution, or injection at the shell level.
+const SHELL_INJECTION_PATTERNS = [
+	/;/,          // command chaining
+	/&&/,         // logical AND chaining
+	/\|\|/,       // logical OR chaining
+	/\$\(/,       // command substitution $(...)
+	/`/,          // backtick command substitution
+	/\$\{/,       // variable expansion ${...}
+	/\n/,         // newline injection
+]
+
+// Additional patterns for tools that should not use piping or redirection.
+const PIPE_AND_REDIRECT_PATTERNS = [
+	/\|/,         // piping
+	/>\s*/,       // output redirection
+	/<\(/,        // process substitution
+]
+
+/**
+ * Validates that args don't contain shell injection metacharacters.
+ * `strict` mode also blocks pipes and redirects (for tools like ls, cat).
+ * `permissive` mode allows | and > since they're valid in regex patterns (for rg, sed, awk).
+ */
+function sanitizeArgs(args: string, command: string, mode: 'strict' | 'permissive' = 'strict'): string {
+	const patterns = mode === 'strict'
+		? [...SHELL_INJECTION_PATTERNS, ...PIPE_AND_REDIRECT_PATTERNS]
+		: SHELL_INJECTION_PATTERNS
+
+	for (const pattern of patterns) {
+		if (pattern.test(args)) {
+			throw new Error(
+				`Refused to execute ${command}: args contain a disallowed shell metacharacter (matched ${pattern}). ` +
+				`Only pass flags, patterns, and file paths — no command chaining or substitution.`
+			)
+		}
+	}
+
+	return args
+}
+
+export const schemas = {
+	rg: z.object({
+		args: z.string().describe('Arguments to pass to ripgrep, e.g. "TODO" --type ts -n'),
+	}).describe('Search file contents using ripgrep (rg). Fast, recursive, respects .gitignore.'),
+
+	ls: z.object({
+		args: z.string().default('.').describe('Arguments to pass to ls, e.g. -la src/'),
+	}).describe('List files and directories.'),
+
+	cat: z.object({
+		args: z.string().describe('Arguments to pass to cat, e.g. src/index.ts'),
+	}).describe('Read file contents.'),
+
+	sed: z.object({
+		args: z.string().describe('Arguments to pass to sed, e.g. -n "10,20p" src/index.ts'),
+	}).describe('Stream editor for filtering and transforming text.'),
+
+	awk: z.object({
+		args: z.string().describe('Arguments to pass to awk, e.g. \'{print $1}\' file.txt'),
+	}).describe('Pattern scanning and text processing.'),
+
+	writeFile: z.object({
+		path: z.string().describe('File path relative to the project root, e.g. src/utils/helper.ts'),
+		content: z.string().describe('The full content to write to the file'),
+	}).describe('Write content to a file. Creates the file if it does not exist, overwrites if it does.'),
+
+	pwd: z.object({}).describe('Print the current working directory.'),
+}
+
+export function rg({ args }: z.infer<typeof schemas.rg>): string {
+	return proc().exec(`rg ${sanitizeArgs(args, 'rg', 'permissive')}`)
+}
+
+export function ls({ args }: z.infer<typeof schemas.ls>): string {
+	return proc().exec(`ls ${sanitizeArgs(args, 'ls')}`)
+}
+
+export function cat({ args }: z.infer<typeof schemas.cat>): string {
+	return proc().exec(`cat ${sanitizeArgs(args, 'cat')}`)
+}
+
+export function sed({ args }: z.infer<typeof schemas.sed>): string {
+	return proc().exec(`sed ${sanitizeArgs(args, 'sed', 'permissive')}`)
+}
+
+export function awk({ args }: z.infer<typeof schemas.awk>): string {
+	return proc().exec(`awk ${sanitizeArgs(args, 'awk', 'permissive')}`)
+}
+
+export async function writeFile({ path, content }: z.infer<typeof schemas.writeFile>): Promise<string> {
+	await fs().writeFileAsync(path, content)
+	return `Wrote ${content.length} bytes to ${path}`
+}
+
+export function pwd(): string {
+	return proc().exec('pwd')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.16",
+  "version": "0.0.19",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",
@@ -102,7 +102,7 @@
     "chokidar": "^3.5.3",
     "cli-markdown": "^3.5.0",
     "compromise": "^14.14.5",
-    "contentbase": "^0.1.5",
+    "contentbase": "^0.1.7",
     "cors": "^2.8.5",
     "detect-port": "^1.5.1",
     "dotenv": "^17.2.4",

package/src/agi/features/assistant.ts

@@ -69,6 +69,9 @@ export const AssistantOptionsSchema = FeatureOptionsSchema.extend({
 
 	/** History persistence mode: lifecycle (ephemeral), daily (auto-resume per day), persistent (single long-running thread), session (unique per run, resumable) */
 	historyMode: z.enum(['lifecycle', 'daily', 'persistent', 'session']).optional().describe('Conversation history persistence mode'),
+
+	/** When true, prepend a timestamp to each user message so the assistant can track the passage of time across sessions */
+	injectTimestamps: z.boolean().default(false).describe('Prepend timestamps to user messages so the assistant can perceive time passing between sessions'),
 })
 
 export type AssistantState = z.infer<typeof AssistantStateSchema>
@@ -402,6 +405,15 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			prompt = prompt + '\n\n' + this.options.appendPrompt
 		}
 
+		if (this.options.injectTimestamps) {
+			prompt = prompt + '\n\n' + [
+				'## Timestamps',
+				'Each user message is prefixed with a timestamp in [YYYY-MM-DD HH:MM] format.',
+				'Use these to understand the passage of time between interactions.',
+				'The user may return hours or days later within the same conversation — acknowledge the time gap naturally when relevant, and use timestamps to contextualize when topics were previously discussed.',
+			].join('\n')
+		}
+
 		return prompt.trim()
 	}
 
@@ -544,6 +556,25 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		}
 	}
 
+	/**
+	 * Prepend a [YYYY-MM-DD HH:MM] timestamp to user message content.
+	 */
+	private prependTimestamp(content: string | ContentPart[]): string | ContentPart[] {
+		const now = new Date()
+		const pad = (n: number) => String(n).padStart(2, '0')
+		const stamp = `[${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}]`
+
+		if (typeof content === 'string') {
+			return `${stamp} ${content}`
+		}
+
+		if (content.length > 0 && content[0].type === 'text') {
+			return [{ type: 'text' as const, text: `${stamp} ${content[0].text}` }, ...content.slice(1)]
+		}
+
+		return [{ type: 'text' as const, text: stamp }, ...content]
+	}
+
 	// -- History mode helpers --
 
 	/** The assistant name derived from the folder basename. */
@@ -663,9 +694,13 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * name matches an event gets wired up so it fires automatically when
 	 * that event is emitted. Must be called before any events are emitted.
 	 */
+	/** Hook names that are called directly during lifecycle, not bound as event listeners. */
+	private static lifecycleHooks = new Set(['formatSystemPrompt'])
+
 	private bindHooksToEvents() {
 		const assistant = this
 		for (const [eventName, hookFn] of Object.entries(this._hooks)) {
+			if (Assistant.lifecycleHooks.has(eventName)) continue
 			this.on(eventName as any, (...args: any[]) => {
 				this.emit('hookFired', eventName)
 				hookFn(assistant, ...args)
@@ -690,6 +725,15 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			this._pendingPlugins = []
 		}
 
+		// Allow hooks.ts to export a formatSystemPrompt(assistant, prompt) => string
+		// that transforms the system prompt before the conversation is created.
+		if (this._hooks.formatSystemPrompt) {
+			const result = await this._hooks.formatSystemPrompt(this, this._systemPrompt)
+			if (typeof result === 'string') {
+				this._systemPrompt = result
+			}
+		}
+
 		// Wire up event forwarding from conversation to assistant.
 		// Hooks fire automatically because they're bound as event listeners.
 		this.conversation.on('turnStart', (info: any) => this.emit('turnStart', info))
@@ -745,6 +789,10 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		const count = (this.state.get('conversationCount') || 0) + 1
 		this.state.set('conversationCount', count)
 
+		if (this.options.injectTimestamps) {
+			question = this.prependTimestamp(question)
+		}
+
 		const result = await this.conversation.ask(question, options)
 
 		// Auto-save for non-lifecycle modes

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-20T16:22:30.732Z
+// Generated at: 2026-03-20T21:13:00.583Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
 //
 // Do not edit manually. Run: luca build-bootstrap

package/src/commands/chat.ts

@@ -18,6 +18,8 @@ export const argsSchema = CommandOptionsSchema.extend({
 	historyMode: z.enum(['lifecycle', 'daily', 'persistent', 'session']).optional().describe('Override history persistence mode'),
 	offRecord: z.boolean().optional().describe('Alias for --history-mode lifecycle (ephemeral, no persistence)'),
 	clear: z.boolean().optional().describe('Clear the conversation history for the resolved history mode and exit'),
+	prependPrompt: z.string().optional().describe('Text or path to a markdown file to prepend to the system prompt'),
+	appendPrompt: z.string().optional().describe('Text or path to a markdown file to append to the system prompt'),
 })
 
 export default async function chat(options: z.infer<typeof argsSchema>, context: ContainerContext) {
@@ -67,10 +69,26 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 		? 'lifecycle'
 		: (options.historyMode || 'daily')
 
-	const createOptions: Record<string, any> = { historyMode }
+	const createOptions: Record<string, any> = { historyMode, injectTimestamps: true }
 	if (options.model) createOptions.model = options.model
 	if (options.local) createOptions.local = options.local
 
+	// Resolve --prepend-prompt / --append-prompt: if it's an existing file, read it; if it ends in .md but doesn't exist, error
+	const fs = container.feature('fs')
+	for (const flag of ['prependPrompt', 'appendPrompt'] as const) {
+		const raw = options[flag]
+		if (!raw) continue
+		const resolved = container.paths.resolve(raw)
+		if (fs.exists(resolved)) {
+			createOptions[flag] = fs.readFile(resolved)
+		} else if (raw.endsWith('.md')) {
+			console.error(ui.colors.red(`File not found: ${resolved}`))
+			process.exit(1)
+		} else {
+			createOptions[flag] = raw
+		}
+	}
+
 	const assistant = manager.create(name, createOptions)
 
 	// --clear: wipe history for the current mode and exit
@@ -110,17 +128,34 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 		assistant.resumeThread(options.resume)
 	}
 
-	let isFirstChunk = true
+	const ink = container.feature('ink', { enable: true })
+	await ink.loadModules()
+	const React = ink.React
+	const { Text } = ink.components
+
+	// Use the raw ink render (sync) since modules are already loaded
+	const inkModule = await import('ink')
+
+	let responseBuffer = ''
+	let inkInstance: any = null
+
+	function mdElement(content: string) {
+		const rendered = content ? String(ui.markdown(content)).trimEnd() : ''
+		return React.createElement(Text, null, rendered)
+	}
 
 	assistant.on('chunk', (text: string) => {
-		if (isFirstChunk) {
+		responseBuffer += text
+		if (!inkInstance) {
 			process.stdout.write('\n')
-			isFirstChunk = false
+			inkInstance = inkModule.render(mdElement(responseBuffer), { patchConsole: false })
+		} else {
+			inkInstance.rerender(mdElement(responseBuffer))
 		}
-		process.stdout.write(text)
 	})
 
 	assistant.on('toolCall', (toolName: string, args: any) => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
 		const argsStr = JSON.stringify(args).slice(0, 120)
 		process.stdout.write(ui.colors.dim(`\n  ⟳ ${toolName}`) + ui.colors.dim(`(${argsStr})\n`))
 	})
@@ -136,8 +171,9 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 	})
 
 	assistant.on('response', () => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
+		responseBuffer = ''
 		process.stdout.write('\n')
-		isFirstChunk = true
 	})
 
 	// Start the assistant (loads history if applicable)
@@ -146,7 +182,7 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 	const messageCount = assistant.messages?.length || 0
 	const isResuming = historyMode !== 'lifecycle' && messageCount > 1
 
-	const rl = readline.createInterface({
+	let rl = readline.createInterface({
 		input: process.stdin,
 		output: process.stdout,
 	})
@@ -174,6 +210,46 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 		if (!question) continue
 		if (question === '.exit') break
 
+		if (question === '/console') {
+			// Pause chat readline so the REPL can own stdin
+			rl.close()
+
+			// Build feature context like `luca console` does
+			const featureContext: Record<string, any> = {}
+			for (const fname of container.features.available) {
+				try { featureContext[fname] = container.feature(fname) } catch {}
+			}
+
+			const replPrompt = ui.colors.magenta('console') + ui.colors.dim(' > ')
+			const repl = container.feature('repl', { prompt: replPrompt })
+
+			console.log()
+			console.log(ui.colors.dim('  Dropping into console. The assistant is available as `assistant`.'))
+			console.log(ui.colors.dim('  Type .exit to return to chat.'))
+			console.log()
+
+			await repl.start({
+				context: {
+					...featureContext,
+					assistant,
+					console,
+					setTimeout, setInterval, clearTimeout, clearInterval,
+					fetch,
+				},
+			})
+
+			// Wait for the REPL to close
+			await new Promise<void>((resolve) => {
+				repl._rl!.on('close', resolve)
+			})
+
+			// Resume chat readline
+			console.log()
+			console.log(ui.colors.dim(`  Back in chat with ${ui.colors.cyan(name)}.`))
+			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			continue
+		}
+
 		await assistant.ask(question)
 	}