luca 2.0.0 → 3.0.2

package/src/agi/features/conversation-history.ts

@@ -0,0 +1,672 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { type AvailableFeatures } from 'luca/feature'
+import { Feature } from '../feature.js'
+import type { DiskCache } from 'luca/node/container'
+import type { OpenAIClient } from '../../clients/openai'
+import type { Message } from './conversation'
+
+declare module 'luca/feature' {
+	interface AvailableFeatures {
+		conversationHistory: typeof ConversationHistory
+	}
+}
+
+export interface TokenUsage {
+	prompt: number
+	completion: number
+	total: number
+	cachedTokens?: number
+	reasoningTokens?: number
+}
+
+export interface CostInfo {
+	inputCost: number
+	outputCost: number
+	totalCost: number
+}
+
+export interface ConversationRecord {
+	id: string
+	title: string
+	model: string
+	messages: Message[]
+	tags: string[]
+	thread: string
+	createdAt: string
+	updatedAt: string
+	messageCount: number
+	tokenUsage?: TokenUsage
+	cost?: CostInfo
+	metadata: Record<string, any>
+}
+
+export type ConversationMeta = Omit<ConversationRecord, 'messages'>
+
+export interface SearchOptions {
+	tag?: string
+	tags?: string[]
+	thread?: string
+	model?: string
+	before?: string | Date
+	after?: string | Date
+	query?: string
+	limit?: number
+	offset?: number
+}
+
+export const ConversationHistoryOptionsSchema = FeatureOptionsSchema.extend({
+	cachePath: z.string().optional().describe('Custom cache directory for conversation storage'),
+	namespace: z.string().optional().describe('Namespace prefix for cache keys to isolate datasets'),
+})
+
+export const ConversationHistoryStateSchema = FeatureStateSchema.extend({
+	conversationCount: z.number().describe('Total number of stored conversations'),
+	lastSaved: z.string().optional().describe('ISO timestamp of the last save operation'),
+})
+
+export const ConversationHistoryEventsSchema = FeatureEventsSchema.extend({
+	saved: z.tuple([z.string().describe('The conversation ID that was saved')]).describe('Fired after a conversation record is persisted'),
+	deleted: z.tuple([z.string().describe('The conversation ID that was deleted')]).describe('Fired after a conversation record is deleted'),
+}).describe('ConversationHistory events')
+
+export type ConversationHistoryOptions = z.infer<typeof ConversationHistoryOptionsSchema>
+export type ConversationHistoryState = z.infer<typeof ConversationHistoryStateSchema>
+
+/**
+ * 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.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const history = container.feature('conversationHistory', {
+ *   namespace: 'my-app',
+ *   cachePath: '/tmp/conversations'
+ * })
+ *
+ * // Create and retrieve conversations
+ * const record = await history.create({ messages, title: 'My Chat' })
+ * const loaded = await history.load(record.id)
+ *
+ * // Search and filter
+ * const results = await history.search({ tag: 'important', limit: 10 })
+ * ```
+ */
+export class ConversationHistory extends Feature<ConversationHistoryState, ConversationHistoryOptions> {
+	static override stateSchema = ConversationHistoryStateSchema
+	static override optionsSchema = ConversationHistoryOptionsSchema
+	static override eventsSchema = ConversationHistoryEventsSchema
+	static override shortcut = 'features.conversationHistory' as const
+
+	static { Feature.register(this, 'conversationHistory') }
+
+	/** @returns Default state with zero conversations and no last-saved timestamp. */
+	override get initialState(): ConversationHistoryState {
+		return {
+			...super.initialState,
+			conversationCount: 0,
+			lastSaved: undefined,
+		}
+	}
+
+
+	/** @returns The diskCache feature instance used for persistence, configured with the optional cachePath. */
+	get diskCache(): DiskCache {
+		const opts: Record<string, any> = {}
+		if (this.options.cachePath) {
+			opts.path = this.options.cachePath
+		}
+		return this.container.feature('diskCache', opts) as DiskCache
+	}
+
+	/** @returns The namespace prefix used for all cache keys, defaults to 'conversation-history'. */
+	get namespace(): string {
+		return this.options.namespace || 'conversation-history'
+	}
+
+	private buildCacheKey(id: string): string {
+		return `${this.namespace}:${id}`
+	}
+
+	private metaKey(id: string): string {
+		return `${this.namespace}:meta:${id}`
+	}
+
+	private indexKey(): string {
+		return `${this.namespace}:__index__`
+	}
+
+	/**
+	 * Save a conversation. Creates or overwrites by ID.
+	 *
+	 * @param {ConversationRecord} record - The full conversation record to persist
+	 * @returns {Promise<void>}
+	 */
+	async save(record: ConversationRecord): Promise<void> {
+		record.updatedAt = new Date().toISOString()
+		record.messageCount = record.messages.length
+
+		// store the full conversation (messages included)
+		await this.diskCache.set(this.buildCacheKey(record.id), record)
+
+		// store lightweight metadata separately for fast listing
+		const meta: ConversationMeta = { ...record }
+		delete (meta as any).messages
+		await this.diskCache.set(this.metaKey(record.id), meta)
+
+		// update the index
+		await this.addToIndex(record.id)
+
+		this.state.set('lastSaved', record.updatedAt)
+		this.emit('saved', record.id)
+	}
+
+	/**
+	 * Create a new conversation from messages, returning the saved record.
+	 *
+	 * @param {object} opts - Creation options including messages, optional title, model, tags, thread, and metadata
+	 * @returns {Promise<ConversationRecord>} The newly created and persisted conversation record
+	 */
+	async create(opts: {
+		id?: string
+		title?: string
+		model?: string
+		messages: Message[]
+		tags?: string[]
+		thread?: string
+		tokenUsage?: TokenUsage
+		cost?: CostInfo
+		metadata?: Record<string, any>
+	}): Promise<ConversationRecord> {
+		const now = new Date().toISOString()
+		const title = opts.title || await this.autoTitle(opts.messages)
+		const record: ConversationRecord = {
+			id: opts.id || crypto.randomUUID(),
+			title,
+			model: opts.model || 'unknown',
+			messages: opts.messages,
+			tags: opts.tags || [],
+			thread: opts.thread || 'default',
+			createdAt: now,
+			updatedAt: now,
+			messageCount: opts.messages.length,
+			tokenUsage: opts.tokenUsage,
+			cost: opts.cost,
+			metadata: opts.metadata || {},
+		}
+
+		await this.save(record)
+		return record
+	}
+
+	/**
+	 * Load a full conversation by ID, including all messages.
+	 *
+	 * @param {string} id - The conversation ID
+	 * @returns {Promise<ConversationRecord | null>} The full record, or null if not found
+	 */
+	async load(id: string): Promise<ConversationRecord | null> {
+		const exists = await this.diskCache.has(this.buildCacheKey(id))
+		if (!exists) return null
+		return this.diskCache.get(this.buildCacheKey(id), true)
+	}
+
+	/**
+	 * Load just the metadata for a conversation (no messages).
+	 *
+	 * @param {string} id - The conversation ID
+	 * @returns {Promise<ConversationMeta | null>} The lightweight metadata record, or null if not found
+	 */
+	async getMeta(id: string): Promise<ConversationMeta | null> {
+		const exists = await this.diskCache.has(this.metaKey(id))
+		if (!exists) return null
+		return this.diskCache.get(this.metaKey(id), true)
+	}
+
+	/**
+	 * Append messages to an existing conversation.
+	 *
+	 * @param {string} id - The conversation ID to append to
+	 * @param {Message[]} messages - The messages to append
+	 * @returns {Promise<ConversationRecord | null>} The updated record, or null if the conversation was not found
+	 */
+	async append(id: string, messages: Message[]): Promise<ConversationRecord | null> {
+		const record = await this.load(id)
+		if (!record) return null
+
+		record.messages.push(...messages)
+		await this.save(record)
+		return record
+	}
+
+	/**
+	 * Delete a conversation by ID.
+	 *
+	 * @param {string} id - The conversation ID to delete
+	 * @returns {Promise<boolean>} True if the conversation existed and was deleted
+	 */
+	async delete(id: string): Promise<boolean> {
+		const exists = await this.diskCache.has(this.buildCacheKey(id))
+		if (!exists) return false
+
+		await this.diskCache.rm(this.buildCacheKey(id))
+		await this.diskCache.rm(this.metaKey(id)).catch(() => {})
+		await this.removeFromIndex(id)
+
+		this.emit('deleted', id)
+		return true
+	}
+
+	/**
+	 * List all conversation metadata, with optional search/filter.
+	 * Loads only the lightweight meta records, never the full messages.
+	 *
+	 * @param {SearchOptions} [options] - Optional filters for tag, thread, model, date range, and text query
+	 * @returns {Promise<ConversationMeta[]>} Filtered and sorted metadata records (newest first)
+	 */
+	async list(options?: SearchOptions): Promise<ConversationMeta[]> {
+		const ids = await this.getIndex()
+		const metas: ConversationMeta[] = []
+
+		for (const id of ids) {
+			const meta = await this.getMeta(id)
+			if (meta) metas.push(meta)
+		}
+
+		return this.applyFilters(metas, options)
+	}
+
+	/**
+	 * Search conversations by text query across titles, tags, and metadata.
+	 * Also supports filtering by tag, thread, model, and date range.
+	 *
+	 * @param {SearchOptions} options - Search and filter criteria
+	 * @returns {Promise<ConversationMeta[]>} Matching metadata records (newest first)
+	 */
+	async search(options: SearchOptions): Promise<ConversationMeta[]> {
+		return this.list(options)
+	}
+
+	/**
+	 * Get all unique tags across all conversations.
+	 *
+	 * @returns {Promise<string[]>} Sorted array of unique tag strings
+	 */
+	async allTags(): Promise<string[]> {
+		const metas = await this.list()
+		const tags = new Set<string>()
+		for (const meta of metas) {
+			for (const tag of meta.tags) {
+				tags.add(tag)
+			}
+		}
+		return [...tags].sort()
+	}
+
+	/**
+	 * Get all unique threads across all conversations.
+	 *
+	 * @returns {Promise<string[]>} Sorted array of unique thread identifiers
+	 */
+	async allThreads(): Promise<string[]> {
+		const metas = await this.list()
+		const threads = new Set<string>()
+		for (const meta of metas) {
+			threads.add(meta.thread)
+		}
+		return [...threads].sort()
+	}
+
+	/**
+	 * Tag a conversation. Adds tags without duplicates.
+	 *
+	 * @param {string} id - The conversation ID
+	 * @param {...string} tags - One or more tags to add
+	 * @returns {Promise<boolean>} True if the conversation was found and updated
+	 */
+	async tag(id: string, ...tags: string[]): Promise<boolean> {
+		const record = await this.load(id)
+		if (!record) return false
+
+		const tagSet = new Set(record.tags)
+		for (const t of tags) tagSet.add(t)
+		record.tags = [...tagSet]
+
+		await this.save(record)
+		return true
+	}
+
+	/**
+	 * Remove tags from a conversation.
+	 *
+	 * @param {string} id - The conversation ID
+	 * @param {...string} tags - One or more tags to remove
+	 * @returns {Promise<boolean>} True if the conversation was found and updated
+	 */
+	async untag(id: string, ...tags: string[]): Promise<boolean> {
+		const record = await this.load(id)
+		if (!record) return false
+
+		const removeSet = new Set(tags)
+		record.tags = record.tags.filter(t => !removeSet.has(t))
+
+		await this.save(record)
+		return true
+	}
+
+	/**
+	 * Update metadata on a conversation without touching messages.
+	 *
+	 * @param {string} id - The conversation ID
+	 * @param {object} updates - Partial updates for title, tags, thread, and/or metadata
+	 * @returns {Promise<boolean>} True if the conversation was found and updated
+	 */
+	async updateMeta(id: string, updates: Partial<Pick<ConversationRecord, 'title' | 'tags' | 'thread' | 'metadata'>>): Promise<boolean> {
+		const record = await this.load(id)
+		if (!record) return false
+
+		if (updates.title !== undefined) record.title = updates.title
+		if (updates.tags !== undefined) record.tags = updates.tags
+		if (updates.thread !== undefined) record.thread = updates.thread
+		if (updates.metadata !== undefined) record.metadata = { ...record.metadata, ...updates.metadata }
+
+		await this.save(record)
+		return true
+	}
+
+	/**
+	 * Find the most recent conversation for an exact thread ID.
+	 *
+	 * @param {string} thread - The exact thread ID to match
+	 * @returns {Promise<ConversationRecord | null>} The full record with messages, or null if none found
+	 */
+	async findByThread(thread: string): Promise<ConversationRecord | null> {
+		const metas = await this.list({ thread })
+		if (!metas.length) return null
+		return this.load(metas[0]!.id)
+	}
+
+	/**
+	 * Find all conversations whose thread starts with a prefix.
+	 *
+	 * @param {string} prefix - The thread prefix to match
+	 * @returns {Promise<ConversationMeta[]>} Matching metadata records (newest first)
+	 */
+	async findByThreadPrefix(prefix: string): Promise<ConversationMeta[]> {
+		const all = await this.list()
+		return all.filter(m => m.thread.startsWith(prefix))
+	}
+
+	/**
+	 * Delete all conversations for an exact thread.
+	 *
+	 * @param {string} thread - The exact thread ID
+	 * @returns {Promise<number>} Number of conversations deleted
+	 */
+	async deleteThread(thread: string): Promise<number> {
+		const metas = await this.list({ thread })
+		let count = 0
+		for (const meta of metas) {
+			if (await this.delete(meta.id)) count++
+		}
+		return count
+	}
+
+	/**
+	 * Delete all conversations matching a thread prefix.
+	 *
+	 * @param {string} prefix - The thread prefix to match
+	 * @returns {Promise<number>} Number of conversations deleted
+	 */
+	async deleteByThreadPrefix(prefix: string): Promise<number> {
+		const metas = await this.findByThreadPrefix(prefix)
+		let count = 0
+		for (const meta of metas) {
+			if (await this.delete(meta.id)) count++
+		}
+		return count
+	}
+
+	/** @returns An OpenAI client from the container for LLM calls. */
+	private get openai(): OpenAIClient {
+		return (this.container as any).client('openai') as OpenAIClient
+	}
+
+	/**
+	 * Generate a short title from conversation messages. Uses the first user
+	 * message (and optionally the first assistant reply) to produce a concise
+	 * title via a cheap LLM call. Falls back to a truncated first message
+	 * if the LLM call fails.
+	 */
+	private async autoTitle(messages: Message[]): Promise<string> {
+		const userMsg = messages.find(m => m.role === 'user')
+		if (!userMsg) return `Conversation ${new Date().toISOString().slice(0, 16)}`
+
+		const userContent = typeof userMsg.content === 'string'
+			? userMsg.content
+			: Array.isArray(userMsg.content)
+				? (userMsg.content as any[]).filter((p: any) => p.type === 'text').map((p: any) => p.text).join(' ')
+				: ''
+
+		if (!userContent.trim()) return `Conversation ${new Date().toISOString().slice(0, 16)}`
+
+		// Build a small context snippet: first user message + first assistant reply if available
+		const assistantMsg = messages.find(m => m.role === 'assistant')
+		let context = `User: ${userContent}`
+		if (assistantMsg) {
+			const assistantContent = typeof assistantMsg.content === 'string'
+				? assistantMsg.content
+				: Array.isArray(assistantMsg.content)
+					? (assistantMsg.content as any[]).filter((p: any) => p.type === 'text').map((p: any) => p.text).join(' ')
+					: ''
+			if (assistantContent.trim()) {
+				context += `\nAssistant: ${assistantContent.slice(0, 300)}`
+			}
+		}
+
+		try {
+			const response = await this.openai.raw.chat.completions.create({
+				model: 'gpt-4o-mini',
+				messages: [
+					{
+						role: 'system',
+						content: 'Generate a short title (max 8 words) for this conversation. Output only the title, no quotes or punctuation wrapping.',
+					},
+					{ role: 'user', content: context.slice(0, 1000) },
+				],
+				max_tokens: 30,
+				temperature: 0.3,
+				stream: false,
+			})
+
+			const title = (response as any).choices?.[0]?.message?.content?.trim()
+			if (title) return title
+		} catch {
+			// LLM unavailable — fall back to truncation
+		}
+
+		// Fallback: truncate the first user message
+		return userContent.length > 60 ? userContent.slice(0, 57) + '...' : userContent
+	}
+
+	/**
+	 * Build a plain-text transcript from a messages array,
+	 * suitable for feeding to a summarizer or title generator.
+	 */
+	private buildTranscript(messages: Message[]): string {
+		return messages
+			.map(m => {
+				const role = m.role
+				const content = typeof m.content === 'string'
+					? m.content
+					: Array.isArray(m.content)
+						? (m.content as any[]).filter((p: any) => p.type === 'text').map((p: any) => p.text).join('\n')
+						: (m.content != null ? JSON.stringify(m.content) : '(no content)')
+				return `[${role}]: ${content || '(no text content)'}`
+			})
+			.join('\n\n')
+	}
+
+	/**
+	 * Generate a concise summary of a stored conversation using the LLM.
+	 * The summary is stored in `metadata.summary` and returned.
+	 * No tool calls are made — this is a single completion request.
+	 *
+	 * @param {string} id - The conversation ID to summarize
+	 * @param {object} [options] - Optional settings
+	 * @param {string} [options.model] - Override the model used for summarization
+	 * @returns {Promise<string | null>} The generated summary, or null if conversation not found
+	 */
+	async summarize(id: string, options?: { model?: string }): Promise<string | null> {
+		const record = await this.load(id)
+		if (!record) return null
+
+		const transcript = this.buildTranscript(record.messages)
+		const model = options?.model || record.model || 'gpt-5'
+
+		const response = await this.openai.raw.chat.completions.create({
+			model,
+			messages: [
+				{
+					role: 'system',
+					content: 'You are a conversation summarizer. Produce a concise but comprehensive summary of the following conversation. Preserve all key facts, decisions, context, user preferences, and any important details needed to understand what was discussed. Output only the summary.',
+				},
+				{ role: 'user', content: transcript },
+			],
+			stream: false,
+		})
+
+		const summary = (response as any).choices?.[0]?.message?.content || ''
+
+		record.metadata = { ...record.metadata, summary }
+		await this.save(record)
+
+		return summary
+	}
+
+	/**
+	 * Generate a short, descriptive title for a stored conversation using the LLM.
+	 * The title is stored both as the record's `title` field and in `metadata.generatedTitle`,
+	 * then returned. No tool calls are made.
+	 *
+	 * @param {string} id - The conversation ID to generate a title for
+	 * @param {object} [options] - Optional settings
+	 * @param {string} [options.model] - Override the model used for title generation
+	 * @returns {Promise<string | null>} The generated title, or null if conversation not found
+	 */
+	async generateTitle(id: string, options?: { model?: string }): Promise<string | null> {
+		const record = await this.load(id)
+		if (!record) return null
+
+		const transcript = this.buildTranscript(record.messages)
+		const model = options?.model || record.model || 'gpt-5'
+
+		const response = await this.openai.raw.chat.completions.create({
+			model,
+			messages: [
+				{
+					role: 'system',
+					content: 'Generate a short, descriptive title (under 60 characters) for the following conversation. The title should capture the main topic or purpose. Output only the title text, with no quotes or punctuation wrapping it.',
+				},
+				{ role: 'user', content: transcript },
+			],
+			stream: false,
+		})
+
+		const title = ((response as any).choices?.[0]?.message?.content || '').trim()
+
+		record.title = title
+		record.metadata = { ...record.metadata, generatedTitle: title }
+		await this.save(record)
+
+		return title
+	}
+
+	// -- index management --
+
+	private async getIndex(): Promise<string[]> {
+		const exists = await this.diskCache.has(this.indexKey())
+		if (!exists) return []
+		return this.diskCache.get(this.indexKey(), true)
+	}
+
+	private async setIndex(ids: string[]): Promise<void> {
+		await this.diskCache.set(this.indexKey(), ids)
+		this.state.set('conversationCount', ids.length)
+	}
+
+	private async addToIndex(id: string): Promise<void> {
+		const ids = await this.getIndex()
+		if (!ids.includes(id)) {
+			ids.push(id)
+			await this.setIndex(ids)
+		}
+	}
+
+	private async removeFromIndex(id: string): Promise<void> {
+		const ids = await this.getIndex()
+		await this.setIndex(ids.filter(i => i !== id))
+	}
+
+	// -- filtering --
+
+	private applyFilters(metas: ConversationMeta[], options?: SearchOptions): ConversationMeta[] {
+		if (!options) return metas
+
+		let results = metas
+
+		if (options.tag) {
+			results = results.filter(m => m.tags.includes(options.tag!))
+		}
+
+		if (options.tags && options.tags.length) {
+			results = results.filter(m => options.tags!.every(t => m.tags.includes(t)))
+		}
+
+		if (options.thread) {
+			results = results.filter(m => m.thread === options.thread)
+		}
+
+		if (options.model) {
+			results = results.filter(m => m.model === options.model)
+		}
+
+		if (options.after) {
+			const after = new Date(options.after).getTime()
+			results = results.filter(m => new Date(m.createdAt).getTime() >= after)
+		}
+
+		if (options.before) {
+			const before = new Date(options.before).getTime()
+			results = results.filter(m => new Date(m.createdAt).getTime() <= before)
+		}
+
+		if (options.query) {
+			const q = options.query.toLowerCase()
+			results = results.filter(m =>
+				m.title.toLowerCase().includes(q) ||
+				m.tags.some(t => t.toLowerCase().includes(q)) ||
+				m.thread.toLowerCase().includes(q) ||
+				JSON.stringify(m.metadata).toLowerCase().includes(q)
+			)
+		}
+
+		// sort newest first
+		results.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
+
+		if (options.offset) {
+			results = results.slice(options.offset)
+		}
+
+		if (options.limit) {
+			results = results.slice(0, options.limit)
+		}
+
+		return results
+	}
+}
+
+export default ConversationHistory