@soederpop/luca 0.1.2 → 0.2.1

package/src/agi/features/assistant.ts

@@ -1,9 +1,8 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 import type { Conversation, ConversationTool, ContentPart, AskOptions, Message } from './conversation'
-import type { AGIContainer } from '../container.server.js'
 import type { ContentDb } from '@soederpop/luca/node'
 import type { ConversationHistory, ConversationMeta } from './conversation-history'
 import hashObject from '../../hash-object.js'
@@ -152,6 +151,10 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * @returns this, for chaining
 	 */
 	intercept<K extends InterceptorPoint>(point: K, fn: InterceptorFn<InterceptorPoints[K]>): this {
+		if (!(point in this.interceptors)) {
+			const available = Object.keys(this.interceptors).join(', ')
+			throw new Error(`Unknown intercept point "${point}". Available points: ${available}`)
+		}
 		this.interceptors[point].add(fn as any)
 		return this
 	}
@@ -176,12 +179,9 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		}
 	}
 
-	override get container(): AGIContainer {
-		return super.container as AGIContainer
-	}
 
 	get name() {
-		return this.resolvedFolder.split('/').pop()
+		return this.options.name || this.resolvedFolder.split('/').pop()
 	}
 
 	/** The absolute resolved path to the assistant folder. */
@@ -213,11 +213,11 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	get voiceConfig(): Record<string, any> | undefined {
 		if (!this.hasVoice) return undefined
 		const yaml = this.container.feature('yaml')
-		return yaml.parse(this.container.fs.readFile(this.paths.resolve('voice.yaml')))
+		return yaml.parse(String(this.container.fs.readFile(this.paths.resolve('voice.yaml'))))
 	}
 
 	get resolvedDocsFolder() {
-		const { docsFolder = this.options.docsFolder || 'docs' } = this.state.current
+		const { docsFolder = this.effectiveOptions.docsFolder || 'docs' } = this.state.current
 
 		if (this.container.fs.exists(docsFolder)) {
 			return this.container.paths.resolve(docsFolder)
@@ -261,24 +261,24 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		// Bind hooks to events BEFORE emitting created so the created hook fires
 		this.bindHooksToEvents()
 
-		this.emit('created')
+		setTimeout(() => this.emit('created'), 1)
 	}
 
 	get conversation(): Conversation {
 		let conv = this.state.get('conversation') as Conversation | null
 		if (!conv) {
 			conv = this.container.feature('conversation', {
-				model: this.options.model || 'gpt-5.4',
-				local: !!this.options.local,
+				model: this.effectiveOptions.model || 'gpt-5.4',
+				local: !!this.effectiveOptions.local,
 				tools: this.tools,
 				api: 'chat',
-				...(this.options.maxTokens ? { maxTokens: this.options.maxTokens } : {}),
-				...(this.options.temperature != null ? { temperature: this.options.temperature } : {}),
-				...(this.options.topP != null ? { topP: this.options.topP } : {}),
-				...(this.options.topK != null ? { topK: this.options.topK } : {}),
-				...(this.options.frequencyPenalty != null ? { frequencyPenalty: this.options.frequencyPenalty } : {}),
-				...(this.options.presencePenalty != null ? { presencePenalty: this.options.presencePenalty } : {}),
-				...(this.options.stop ? { stop: this.options.stop } : {}),
+				...(this.effectiveOptions.maxTokens ? { maxTokens: this.effectiveOptions.maxTokens } : {}),
+				...(this.effectiveOptions.temperature != null ? { temperature: this.effectiveOptions.temperature } : {}),
+				...(this.effectiveOptions.topP != null ? { topP: this.effectiveOptions.topP } : {}),
+				...(this.effectiveOptions.topK != null ? { topK: this.effectiveOptions.topK } : {}),
+				...(this.effectiveOptions.frequencyPenalty != null ? { frequencyPenalty: this.effectiveOptions.frequencyPenalty } : {}),
+				...(this.effectiveOptions.presencePenalty != null ? { presencePenalty: this.effectiveOptions.presencePenalty } : {}),
+				...(this.effectiveOptions.stop ? { stop: this.effectiveOptions.stop } : {}),
 				history: [
 					{ role: 'system', content: this.effectiveSystemPrompt },
 				],
@@ -372,7 +372,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * allowTools is applied first (strict allowlist), then forbidTools removes from whatever remains.
 	 */
 	private applyToolFilters(tools: Record<string, ConversationTool>): Record<string, ConversationTool> {
-		const { allowTools, forbidTools, toolNames } = this.options
+		const { allowTools, forbidTools, toolNames } = this.effectiveOptions
 		if (!allowTools && !forbidTools && !toolNames) return tools
 
 		let names = Object.keys(tools)
@@ -395,7 +395,8 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 		const result: Record<string, ConversationTool> = {}
 		for (const n of names) {
-			result[n] = tools[n]
+			const tool = tools[n]
+			if (tool) result[n] = tool
 		}
 		return result
 	}
@@ -607,6 +608,15 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		return (this.state.get('meta') || {}) as Record<string, any>
 	}
 
+	/**
+	 * Merged options where CORE.md frontmatter provides defaults and
+	 * constructor options take precedence. Prefer this over `this.options`
+	 * anywhere model parameters or runtime config is consumed.
+	 */
+	get effectiveOptions(): AssistantOptions & Record<string, any> {
+		return { ...this.meta, ...this.options }
+	}
+
 	/**
 	 * Load the system prompt from CORE.md, applying any prepend/append options.
 	 * YAML frontmatter (between --- fences) is stripped from the prompt and
@@ -831,8 +841,9 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			return `${stamp} ${content}`
 		}
 
-		if (content.length > 0 && content[0].type === 'text') {
-			return [{ type: 'text' as const, text: `${stamp} ${content[0].text}` }, ...content.slice(1)]
+		const firstPart = content[0]
+		if (firstPart && firstPart.type === 'text') {
+			return [{ type: 'text' as const, text: `${stamp} ${firstPart.text}` }, ...content.slice(1)]
 		}
 
 		return [{ type: 'text' as const, text: stamp }, ...content]
@@ -919,7 +930,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * Called from start() for non-lifecycle modes.
 	 */
 	private async loadConversationHistory(): Promise<void> {
-		const mode = this.options.historyMode || 'lifecycle'
+		const mode = this.effectiveOptions.historyMode || 'lifecycle'
 		if (mode === 'lifecycle') return
 
 		const threadId = (this.state.get('resumeThreadId') as string | undefined) || this.buildThreadId(mode)
@@ -1104,7 +1115,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		await this.loadConversationHistory()
 
 		// Enable autoCompact for modes that accumulate history
-		const mode = this.options.historyMode || 'lifecycle'
+		const mode = this.effectiveOptions.historyMode || 'lifecycle'
 		if (mode === 'daily' || mode === 'persistent') {
 			(this.conversation.options as any).autoCompact = true
 		}
@@ -1146,7 +1157,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		const count = (this.state.get('conversationCount') || 0) + 1
 		this.state.set('conversationCount', count)
 
-		if (this.options.injectTimestamps) {
+		if (this.effectiveOptions.injectTimestamps) {
 			question = this.prependTimestamp(question)
 		}
 
@@ -1169,7 +1180,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		}
 
 		// Auto-save for non-lifecycle modes
-		if (this.options.historyMode !== 'lifecycle' && this.state.get('threadId')) {
+		if (this.effectiveOptions.historyMode !== 'lifecycle' && this.state.get('threadId')) {
 			await this.conversation.save({ thread: this.state.get('threadId') })
 		}
 

package/src/agi/features/assistants-manager.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { Feature } from '@soederpop/luca/feature'
-import type { AGIContainer } from '../container.server.js'
+import { Feature } from '../feature.js'
 import type { Assistant } from './assistant.js'
+import type { InterceptorFn, InterceptorPoint, InterceptorPoints } from '../lib/interceptor-chain.js'
 
 declare module '@soederpop/luca/feature' {
 	interface AvailableFeatures {
@@ -27,6 +27,10 @@ export interface AssistantEntry {
 	hasHooks: boolean
 	/** Whether a voice.yaml configuration file exists. */
 	hasVoice: boolean
+	/** Contents of ABOUT.md if present, undefined otherwise. */
+	about?: string
+	/** Frontmatter metadata parsed from CORE.md. */
+	meta?: Record<string, any>
 }
 
 export const AssistantsManagerEventsSchema = FeatureEventsSchema.extend({
@@ -47,6 +51,7 @@ export const AssistantsManagerStateSchema = FeatureStateSchema.extend({
 	entries: z.record(z.string(), z.any()).describe('Discovered assistant entries keyed by name'),
 	instances: z.record(z.string(), z.any()).describe('Active assistant instances keyed by name'),
 	factories: z.record(z.string(), z.any()).describe('Registered factory functions keyed by name'),
+	extraFolders: z.array(z.string()).describe('Additional folders to scan during discovery'),
 })
 
 export const AssistantsManagerOptionsSchema = FeatureOptionsSchema.extend({})
@@ -91,12 +96,10 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 			entries: {},
 			instances: {},
 			factories: {},
+			extraFolders: [],
 		}
 	}
 
-	override get container(): AGIContainer {
-		return super.container as AGIContainer
-	}
 
 	/** Discovered assistant entries keyed by name. */
 	get entries(): Record<string, AssistantEntry> {
@@ -113,12 +116,60 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 		return (this.state.get('factories') || {}) as Record<string, (options: Record<string, any>) => Assistant>
 	}
 
+	/** Interceptor registrations to be applied to every assistant this manager creates. */
+	private _interceptors: Array<{ point: InterceptorPoint; fn: InterceptorFn<any> }> = []
+
+	/**
+	 * Registers a pipeline interceptor that is applied to every assistant created by this manager.
+	 * Interceptors are applied at the given interception point on each assistant at creation time.
+	 * This mirrors the per-assistant `assistant.intercept(point, fn)` API, but scopes it globally
+	 * across all assistants managed here — useful for cross-cutting concerns like logging, tracing,
+	 * or policy enforcement.
+	 *
+	 * @param {InterceptorPoint} point - The interception point (beforeAsk, beforeTurn, beforeToolCall, afterToolCall, beforeResponse)
+	 * @param {InterceptorFn<InterceptorPoints[K]>} fn - Middleware function receiving (ctx, next)
+	 * @returns {this} This instance, for chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * manager.intercept('beforeAsk', async (ctx, next) => {
+	 *   console.log(`[${ctx.assistant.name}] asking: ${ctx.message}`)
+	 *   await next()
+	 * })
+	 * ```
+	 */
+	intercept<K extends InterceptorPoint>(point: K, fn: InterceptorFn<InterceptorPoints[K]>): this {
+		this._interceptors.push({ point, fn })
+		return this
+	}
+
 	/**
 	 * Discovers assistants by listing subdirectories in ~/.luca/assistants/
 	 * and cwd/assistants/. Each subdirectory containing a CORE.md is an assistant.
 	 *
 	 * @returns {Promise<this>} This instance, for chaining
 	 */
+	/**
+	 * Registers an additional folder to scan during assistant discovery and
+	 * immediately triggers a new discovery pass.
+	 *
+	 * @param {string} folderPath - Absolute path to a folder containing assistant subdirectories
+	 * @returns {Promise<this>} This instance, for chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * await manager.addDiscoveryFolder('/path/to/more/assistants')
+	 * console.log(manager.available) // includes assistants from the new folder
+	 * ```
+	 */
+	async addDiscoveryFolder(folderPath: string): Promise<this> {
+		const current = this.state.get('extraFolders') as string[]
+		if (!current.includes(folderPath)) {
+			this.state.set('extraFolders', [...current, folderPath])
+		}
+		return this.discover()
+	}
+
 	async discover(): Promise<this> {
 		const { fs, paths, os } = this.container
 
@@ -127,6 +178,7 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 		const locations = [
 			`${os.homedir}/.luca/assistants`,
 			paths.resolve('assistants'),
+			...(this.state.get('extraFolders') as string[]),
 		]
 
 		for (const location of locations) {
@@ -143,6 +195,25 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 
 				// Don't overwrite earlier entries (home takes precedence for same name)
 				if (!discovered[entry]) {
+					const hasAbout = fs.exists(`${folder}/ABOUT.md`)
+					let about: string | undefined
+					let meta: Record<string, any> | undefined
+
+					if (hasAbout) {
+						about = fs.readFileSync(`${folder}/ABOUT.md`, 'utf8')
+					}
+
+					try {
+						const coreContent = fs.readFileSync(`${folder}/CORE.md`, 'utf8')
+						const fmMatch = coreContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+						if (fmMatch) {
+							const yaml = this.container.feature('yaml')
+							meta = yaml.parse(fmMatch[1])
+						}
+					} catch {
+						// CORE.md exists but couldn't be parsed — skip meta
+					}
+
 					discovered[entry] = {
 						name: entry,
 						folder,
@@ -150,6 +221,8 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 						hasTools: fs.exists(`${folder}/tools.ts`),
 						hasHooks: fs.exists(`${folder}/hooks.ts`),
 						hasVoice: fs.exists(`${folder}/voice.yaml`),
+						...(about != null && { about }),
+						...(meta != null && { meta }),
 					}
 				}
 			}
@@ -262,6 +335,7 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 		const factory = this.factories[name]
 		if (factory) {
 			const instance = factory(options)
+			this._bindAssistant(instance)
 			const updated = { ...this.instances, [name]: instance }
 			this.state.setState({ instances: updated, activeCount: Object.keys(updated).length })
 			this.emit('assistantCreated', name, instance)
@@ -281,6 +355,7 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 			...options,
 		})
 
+		this._bindAssistant(instance)
 		const updated = { ...this.instances, [name]: instance }
 		this.state.setState({ instances: updated, activeCount: Object.keys(updated).length })
 		this.emit('assistantCreated', name, instance)
@@ -288,6 +363,21 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 		return instance
 	}
 
+	/**
+	 * Wires an assistant into the manager: bridges all assistant events up to the manager
+	 * as `assistantEvent:<eventName>` with (assistant, ...originalArgs), and applies any
+	 * globally registered interceptors.
+	 */
+	private _bindAssistant(instance: Assistant): void {
+		instance.on('*', (event: string, ...args: any[]) => {
+			this.emit(`assistantEvent:${event}` as any, instance, ...args)
+		})
+
+		for (const { point, fn } of this._interceptors) {
+			instance.intercept(point, fn)
+		}
+	}
+
 	/**
 	 * Returns a previously created assistant instance by name.
 	 *

package/src/agi/features/autonomous-assistant.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { Feature } from '@soederpop/luca/feature'
-import type { AGIContainer } from '../container.server.js'
+import { Feature } from '../feature.js'
 import type { Assistant } from './assistant.js'
 import type { ToolCallCtx } from '../lib/interceptor-chain.js'
 
@@ -158,9 +157,6 @@ export class AutonomousAssistant extends Feature<AutonomousAssistantState, Auton
 		}
 	}
 
-	override get container(): AGIContainer {
-		return super.container as AGIContainer
-	}
 
 	/** The inner assistant. Throws if not started. */
 	get assistant(): Assistant {

package/src/agi/features/browser-use.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
+import type { Helper } from '../../helper.js'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {
@@ -61,7 +62,7 @@ export class BrowserUse extends Feature<BrowserUseState, BrowserUseOptions> {
   static override optionsSchema = BrowserUseOptionsSchema
   static override eventsSchema = BrowserUseEventsSchema
 
-  static tools = {
+  static override tools = {
     browserOpen: {
       description: 'Navigate the browser to a URL. Call this first to open a page before any interaction.',
       schema: z.object({
@@ -223,6 +224,35 @@ export class BrowserUse extends Feature<BrowserUseState, BrowserUseOptions> {
 
   static { Feature.register(this, 'browserUse') }
 
+  /**
+   * When an assistant uses browserUse, inject system prompt guidance
+   * about the browser interaction loop.
+   */
+  override setupToolsConsumer(consumer: Helper) {
+    if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+      (consumer as any).addSystemPromptExtension('browserUse', [
+        '## Browser Automation',
+        '',
+        '**The core loop:** `browserOpen` → `browserGetState` → interact → `browserGetState` again.',
+        '',
+        '`browserGetState` is your eyes. It returns all interactive elements with index numbers. You MUST call it:',
+        '- After every `browserOpen` or navigation',
+        '- After any action that changes the page (click, submit, scroll)',
+        '- Before any interaction — to get fresh element indices',
+        '',
+        'Element indices change whenever the page updates. Never reuse indices from a previous `browserGetState` call after the page has changed.',
+        '',
+        '**Interacting with elements:** Use `browserInput` (click + type) for form fields. Use `browserClick` for buttons and links. Use `browserSelect` for dropdowns. All require an element index from `browserGetState`.',
+        '',
+        '**When things load asynchronously:** Use `browserWaitForSelector` or `browserWaitForText` after actions that trigger page updates (form submissions, AJAX). Then call `browserGetState` to see the updated page.',
+        '',
+        '**Debugging:** If an interaction doesn\'t work, take a `browserScreenshot` to see the actual page state. Check `browserGetState` to see what elements are available.',
+        '',
+        '**Cleanup:** Call `browserClose` when you\'re done to free resources.',
+      ].join('\n'))
+    }
+  }
+
   override async afterInitialize() {
     if (this.options.session) this.state.set('session', this.options.session)
     if (this.options.headed) this.state.set('headed', true)

package/src/agi/features/claude-code.ts

@@ -2,7 +2,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {
@@ -1349,6 +1349,170 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
     }
   }
 
+  /**
+   * List all Claude Code processes currently registered in ~/.claude/sessions/.
+   * Returns each session's metadata along with whether the process is still alive.
+   *
+   * @returns {Promise<Array<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string; alive: boolean }>>}
+   *
+   * @example
+   * const sessions = await cc.listProcessSessions()
+   * for (const s of sessions) {
+   *   console.log(`[${s.alive ? 'LIVE' : 'dead'}] PID ${s.pid} in ${s.cwd}`)
+   * }
+   */
+  async listProcessSessions(): Promise<Array<{
+    pid: number
+    sessionId: string
+    cwd: string
+    startedAt: number
+    kind: string
+    entrypoint: string
+    alive: boolean
+  }>> {
+    const fs = this.container.feature('fs')
+    const proc = this.container.feature('proc')
+    const home = process.env.HOME ?? '/tmp'
+    const sessionsDir = `${home}/.claude/sessions`
+
+    let files: string[]
+    try {
+      files = await fs.readdir(sessionsDir)
+    } catch {
+      return []
+    }
+
+    const jsonFiles = files.filter((f: string) => f.endsWith('.json'))
+
+    const results = await Promise.all(jsonFiles.map(async (file: string) => {
+      try {
+        const raw = await fs.readFile(`${sessionsDir}/${file}`, 'utf8')
+        const data = JSON.parse(raw)
+        let alive = false
+        try {
+          await proc.exec(`kill -0 ${data.pid}`)
+          alive = true
+        } catch {
+          alive = false
+        }
+        return { ...data, alive }
+      } catch {
+        return null
+      }
+    }))
+
+    return results.filter(Boolean)
+  }
+
+  /**
+   * Read a single process session by PID from ~/.claude/sessions/<pid>.json.
+   *
+   * @param {number} pid - The process ID
+   * @returns {Promise<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string } | null>}
+   *
+   * @example
+   * const session = await cc.getProcessSession(12345)
+   * console.log(session?.cwd)
+   */
+  async getProcessSession(pid: number): Promise<{
+    pid: number
+    sessionId: string
+    cwd: string
+    startedAt: number
+    kind: string
+    entrypoint: string
+  } | null> {
+    const fs = this.container.feature('fs')
+    const home = process.env.HOME ?? '/tmp'
+    try {
+      const raw = await fs.readFile(`${home}/.claude/sessions/${pid}.json`, 'utf8')
+      return JSON.parse(raw)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Read the conversation history for a Claude Code session from its JSONL file in
+   * ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl.
+   *
+   * Returns an array of parsed message objects (user, assistant, tool_use, tool_result).
+   *
+   * @param {string} sessionId - The Claude CLI session ID (from listProcessSessions or getProcessSession)
+   * @param {string} cwd - The working directory of the session (used to locate the project folder)
+   * @returns {Promise<any[]>} Array of parsed JSONL records
+   *
+   * @example
+   * const sessions = await cc.listProcessSessions()
+   * const s = sessions[0]
+   * const history = await cc.getConversationHistory(s.sessionId, s.cwd)
+   * console.log(history.length, 'turns')
+   */
+  async getConversationHistory(sessionId: string, cwd?: string): Promise<any[]> {
+    const fs = this.container.feature('fs')
+    const home = process.env.HOME ?? '/tmp'
+    const resolvedCwd = cwd ?? this.options.cwd ?? (this.container as any).cwd
+    const encodedCwd = resolvedCwd.replace(/\//g, '-').replace(/@/g, '-')
+    const filePath = `${home}/.claude/projects/${encodedCwd}/${sessionId}.jsonl`
+    try {
+      const raw = await fs.readFile(filePath, 'utf8')
+      return raw
+        .split('\n')
+        .filter((line: string) => line.trim())
+        .map((line: string) => JSON.parse(line))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * List all conversation sessions stored for a given working directory.
+   * Reads ~/.claude/projects/<encoded-cwd>/ and returns metadata for each .jsonl file.
+   *
+   * @param {string} cwd - The working directory path to look up
+   * @returns {Promise<Array<{ sessionId: string; filePath: string; messageCount: number }>>}
+   *
+   * @example
+   * const sessions = await cc.listSessionsForCwd('/Users/me/my-project')
+   * for (const s of sessions) {
+   *   console.log(s.sessionId, s.messageCount, 'messages')
+   * }
+   */
+  async listSessionsForCwd(cwd?: string): Promise<Array<{
+    sessionId: string
+    filePath: string
+    messageCount: number
+  }>> {
+    const fs = this.container.feature('fs')
+    const home = process.env.HOME ?? '/tmp'
+    const resolvedCwd = cwd ?? this.options.cwd ?? (this.container as any).cwd
+    const encodedCwd = resolvedCwd.replace(/\//g, '-').replace(/@/g, '-')
+    const projectDir = `${home}/.claude/projects/${encodedCwd}`
+
+    let files: string[]
+    try {
+      files = await fs.readdir(projectDir)
+    } catch {
+      return []
+    }
+
+    const jsonlFiles = files.filter((f: string) => f.endsWith('.jsonl'))
+
+    const results = await Promise.all(jsonlFiles.map(async (file: string) => {
+      const sessionId = file.replace(/\.jsonl$/, '')
+      const filePath = `${projectDir}/${file}`
+      try {
+        const raw = await fs.readFile(filePath, 'utf8')
+        const messageCount = raw.split('\n').filter((l: string) => l.trim()).length
+        return { sessionId, filePath, messageCount }
+      } catch {
+        return { sessionId, filePath, messageCount: 0 }
+      }
+    }))
+
+    return results
+  }
+
   /**
    * Clean up any temp MCP config files created during sessions.
    */