luca 3.0.0 → 3.1.0

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

@@ -1,10 +1,10 @@
 // @ts-nocheck
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from 'luca/feature'
 import { Feature } from '../feature.js'
 
-declare module '@soederpop/luca/feature' {
+declare module 'luca/feature' {
   interface AvailableFeatures {
     claudeCode: typeof ClaudeCode
   }
@@ -184,6 +184,12 @@ export const ClaudeCodeOptionsSchema = FeatureOptionsSchema.extend({
   skillsFolders: z.array(z.string()).optional().describe('Directories containing Claude Code skills to load into sessions'),
   /** Launch Claude Code with a Chrome browser tool. */
   chrome: z.boolean().optional().describe('Launch Claude Code with a Chrome browser tool'),
+  /** Base URL for the Anthropic API. Injected as ANTHROPIC_BASE_URL env var. */
+  baseURL: z.string().optional().describe('Base URL for the Anthropic API, injected as ANTHROPIC_BASE_URL'),
+  /** Auth token for the Anthropic API. Injected as ANTHROPIC_AUTH_TOKEN env var. */
+  authToken: z.string().optional().describe('Auth token for the Anthropic API, injected as ANTHROPIC_AUTH_TOKEN'),
+  /** Use local models. Sets baseURL and model from LOCAL_CHAT_ENDPOINT and LOCAL_CODER_MODEL env vars. */
+  local: z.boolean().optional().describe('Use local models, sets baseURL to LOCAL_CHAT_ENDPOINT and model to LOCAL_CODER_MODEL'),
 })
 
 export const ClaudeCodeEventsSchema = FeatureEventsSchema.extend({
@@ -269,6 +275,12 @@ export interface RunOptions {
   settingsFile?: string
   /** Launch Claude Code with a Chrome browser tool. */
   chrome?: boolean
+  /** Base URL for the Anthropic API. Injected as ANTHROPIC_BASE_URL in the subprocess env. */
+  baseURL?: string
+  /** Auth token for the Anthropic API. Injected as ANTHROPIC_AUTH_TOKEN in the subprocess env. */
+  authToken?: string
+  /** Use local models. Sets baseURL to LOCAL_CHAT_ENDPOINT (or http://localhost:1234) and model to LOCAL_CODER_MODEL (or qwen/qwen3.6-27b). */
+  local?: boolean
 }
 
 /**
@@ -506,7 +518,8 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
       args.push('--include-partial-messages')
     }
 
-    const model = options.model ?? this.options.model
+    const isLocal = options.local ?? this.options.local
+    const model = options.model ?? this.options.model ?? (isLocal ? (process.env.LOCAL_CODER_MODEL || 'qwen/qwen3.6-27b') : undefined)
     if (model) args.push('--model', model)
 
     const systemPrompt = options.systemPrompt ?? this.options.systemPrompt
@@ -613,6 +626,39 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
     return args
   }
 
+  /**
+   * Build the environment object for a claude CLI invocation.
+   * Injects ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN when baseURL/authToken are set,
+   * or when local mode is enabled.
+   *
+   * @param {RunOptions} options - Session options
+   * @returns {Record<string, string>} Environment variables
+   */
+  private buildEnv(options: RunOptions = {}): Record<string, string> {
+    const env = { ...process.env }
+    const isLocal = options.local ?? this.options.local
+
+    if (isLocal) {
+      const baseURL = process.env.LOCAL_CHAT_ENDPOINT || 'http://localhost:1234'
+      env.ANTHROPIC_BASE_URL = baseURL
+      if (!options.authToken) {
+        env.ANTHROPIC_AUTH_TOKEN = process.env.LOCAL_CHAT_AUTH_TOKEN || 'sk-anticropic-00000000000000000000001'
+      }
+    }
+
+    const baseURL = options.baseURL
+    if (baseURL) {
+      env.ANTHROPIC_BASE_URL = baseURL
+    }
+
+    const authToken = options.authToken
+    if (authToken) {
+      env.ANTHROPIC_AUTH_TOKEN = authToken
+    }
+
+    return env
+  }
+
   /**
    * Create a unique session ID.
    *
@@ -780,7 +826,7 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
       stdout: 'pipe',
       stderr: 'pipe',
       stdin: Buffer.from(prompt),
-      environment: { ...process.env },
+      environment: this.buildEnv(options),
     })
 
     this.updateSession(id, { process: proc })
@@ -842,7 +888,7 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
       stdout: 'pipe',
       stderr: 'pipe',
       stdin: Buffer.from(prompt),
-      environment: { ...process.env },
+      environment: this.buildEnv(options),
     })
 
     this.updateSession(id, { process: proc })

package/src/agi/features/coding-tools.ts

@@ -4,7 +4,7 @@ import { Feature } from '../feature.js'
 import type { Helper } from '../../helper.js'
 import type { ChildProcess } from '../../node/features/proc.js'
 
-declare module '@soederpop/luca/feature' {
+declare module 'luca/feature' {
 	interface AvailableFeatures {
 		codingTools: typeof CodingTools
 	}

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

@@ -1,16 +1,31 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from 'luca/feature'
 import { Feature } from '../feature.js'
-import type { DiskCache } from '@soederpop/luca/node/container'
+import type { DiskCache } from 'luca/node/container'
+import type { OpenAIClient } from '../../clients/openai'
 import type { Message } from './conversation'
 
-declare module '@soederpop/luca/feature' {
+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
@@ -21,6 +36,8 @@ export interface ConversationRecord {
 	createdAt: string
 	updatedAt: string
 	messageCount: number
+	tokenUsage?: TokenUsage
+	cost?: CostInfo
 	metadata: Record<string, any>
 }
 
@@ -160,12 +177,15 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 		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: opts.title || 'Untitled',
+			title,
 			model: opts.model || 'unknown',
 			messages: opts.messages,
 			tags: opts.tags || [],
@@ -173,6 +193,8 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 			createdAt: now,
 			updatedAt: now,
 			messageCount: opts.messages.length,
+			tokenUsage: opts.tokenUsage,
+			cost: opts.cost,
 			metadata: opts.metadata || {},
 		}
 
@@ -408,6 +430,161 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 		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[]> {

package/src/agi/features/conversation.ts

@@ -1,13 +1,13 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from 'luca/feature'
 import { Feature } from '../feature.js'
 import type { OpenAIClient } from '../../clients/openai';
 import type OpenAI from 'openai';
 import type { ConversationHistory } from './conversation-history';
-import { countMessageTokens, getContextWindow } from '../lib/token-counter.js';
+import { countMessageTokens, getContextWindow, calculateCost } from '../lib/token-counter.js';
 
-declare module '@soederpop/luca/feature' {
+declare module 'luca/feature' {
 	interface AvailableFeatures {
 		conversation: typeof Conversation
 	}
@@ -37,6 +37,20 @@ export interface ConversationMCPServer {
 	}
 }
 
+const INPUT_TOKEN_SIZES: Record<string, number> = {
+	tiny: 8_000,
+	small: 16_000,
+	medium: 32_000,
+	large: 64_000,
+	xlarge: 256_000,
+}
+
+function resolveMaxInputTokens(value: number | string | undefined): number | undefined {
+	if (value == null) return undefined
+	if (typeof value === 'number') return value
+	return INPUT_TOKEN_SIZES[value]
+}
+
 export const ConversationOptionsSchema = FeatureOptionsSchema.extend({
 	/** A unique identifier for the conversation */
 	id: z.string().optional().describe('A unique identifier for the conversation'),
@@ -87,6 +101,12 @@ export const ConversationOptionsSchema = FeatureOptionsSchema.extend({
 	contextWindow: z.number().optional().describe('Override the inferred context window size for this model'),
 	/** Number of recent messages to preserve after compaction (default 4) */
 	compactKeepRecent: z.number().optional().describe('Number of recent messages to preserve after compaction (default 4)'),
+
+	/** Maximum input tokens to send to the API. When set, older messages are trimmed to stay within this budget, keeping the system prompt and most recent messages. Useful for avoiding long-context pricing tiers. Accepts a number or a named size: tiny (8k), small (16k), medium (32k), large (64k), xlarge (256k — max before long-context pricing). */
+	maxInputTokens: z.union([
+		z.number(),
+		z.enum(['tiny', 'small', 'medium', 'large', 'xlarge']),
+	]).default('large').describe('Maximum input tokens. Accepts a number or a named size: tiny (8k), small (16k), medium (32k), large (64k), xlarge (256k). Defaults to large (64k)'),
 })
 
 export const ConversationStateSchema = FeatureStateSchema.extend({
@@ -103,7 +123,14 @@ export const ConversationStateSchema = FeatureStateSchema.extend({
 		prompt: z.number().describe('Total prompt tokens consumed'),
 		completion: z.number().describe('Total completion tokens consumed'),
 		total: z.number().describe('Total tokens consumed'),
-	}).describe('Cumulative token usage statistics'),
+		cachedTokens: z.number().describe('Input tokens served from cache (billed at reduced rate)'),
+		reasoningTokens: z.number().describe('Output tokens used for reasoning (o-series models)'),
+	}).describe('Cumulative token usage statistics including detail breakdowns from the API'),
+	cost: z.object({
+		inputCost: z.number().describe('Estimated cost in dollars for input tokens'),
+		outputCost: z.number().describe('Estimated cost in dollars for output tokens'),
+		totalCost: z.number().describe('Estimated total cost in dollars'),
+	}).describe('Running cost estimate based on cumulative token usage and model pricing'),
 	estimatedInputTokens: z.number().describe('Estimated input token count for the current messages array'),
 	compactionCount: z.number().describe('Number of times compact() has been called'),
 	contextWindow: z.number().describe('The context window size for the current model'),
@@ -267,7 +294,8 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			toolCalls: 0,
 			api: this.apiMode,
 			lastResponseId: null,
-			tokenUsage: { prompt: 0, completion: 0, total: 0 },
+			tokenUsage: { prompt: 0, completion: 0, total: 0, cachedTokens: 0, reasoningTokens: 0 },
+			cost: { inputCost: 0, outputCost: 0, totalCost: 0 },
 			estimatedInputTokens: 0,
 			compactionCount: 0,
 			contextWindow: this.options.contextWindow || getContextWindow(this.options.model || 'gpt-5'),
@@ -598,7 +626,15 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			? messages[0]
 			: null
 
-		const recentMessages = messages.slice(-keepRecent)
+		let sliceStart = messages.length - keepRecent
+		// Walk back to avoid splitting a tool call group — if we'd start on a tool message,
+		// include the preceding assistant message (and its full tool response block)
+		if (sliceStart > 0) {
+			while (sliceStart > 0 && messages[sliceStart]?.role === 'tool') {
+				sliceStart--
+			}
+		}
+		const recentMessages = messages.slice(sliceStart)
 
 		const newMessages: Message[] = []
 		if (systemMessage) newMessages.push(systemMessage)
@@ -724,16 +760,20 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			let raw: string
 
 			if (this.apiMode === 'responses') {
-				const previousResponseId = this.state.get('lastResponseId') || undefined
+				// When maxInputTokens is set, skip previous_response_id continuation
+				// so we control exactly how many tokens the API processes (server-side
+				// context from previous_response_id would accumulate unbounded).
+				const canChain = !this.options.maxInputTokens
+				const previousResponseId = canChain ? (this.state.get('lastResponseId') || undefined) : undefined
 				let input: OpenAI.Responses.ResponseInput
 
 				if (previousResponseId) {
 					// Can chain via previous_response_id — only send the new user message
 					input = [this.toResponsesUserMessage(content)]
 				} else {
-					// No previous response ID (first call or resumed from disk).
-					// Convert full message history to Responses API input so the model has context.
-					input = this.messagesToResponsesInput()
+					// No previous response ID (first call, resumed from disk, or maxInputTokens active).
+					// Convert (possibly trimmed) message history to Responses API input.
+					input = this.messagesToResponsesInput(this.getMessagesWithinBudget())
 				}
 
 				raw = await this.runResponsesLoop({
@@ -816,10 +856,10 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	 * Convert the full Chat Completions message history into Responses API input items.
 	 * Used when resuming a conversation without a previous_response_id.
 	 */
-	private messagesToResponsesInput(): OpenAI.Responses.ResponseInput {
+	private messagesToResponsesInput(messages?: Message[]): OpenAI.Responses.ResponseInput {
 		const input: OpenAI.Responses.ResponseInput = []
 
-		for (const msg of this.messages) {
+		for (const msg of (messages || this.messages)) {
 			if (msg.role === 'system' || msg.role === 'developer') {
 				// System/developer messages are handled via the instructions parameter
 				continue
@@ -917,9 +957,15 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		const lastResponseId = this.state.get('lastResponseId')
 		const responseMeta = lastResponseId ? { lastResponseId } : {}
 
+		// Grab the live token usage and cost from state
+		const tokenUsage = this.state.get('tokenUsage')!
+		const cost = this.state.get('cost')!
+
 		if (existing) {
 			existing.messages = this.messages
 			existing.model = this.model
+			existing.tokenUsage = tokenUsage
+			existing.cost = cost
 			if (opts?.title) existing.title = opts.title
 			if (opts?.tags) existing.tags = opts.tags
 			if (opts?.thread) existing.thread = opts.thread
@@ -930,11 +976,13 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 		return this.history.create({
 			id,
-			title: opts?.title || this.options.title || 'Untitled',
+			title: opts?.title || this.options.title,
 			model: this.model,
 			messages: this.messages,
 			tags: opts?.tags || this.options.tags || [],
 			thread: opts?.thread || this.options.thread || this.state.get('thread'),
+			tokenUsage,
+			cost,
 			metadata: { ...responseMeta, ...(opts?.metadata || this.options.metadata || {}) },
 		})
 	}
@@ -1163,6 +1211,16 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return accumulated || finalText
 	}
 
+	/** Recalculate the running cost estimate from current token usage and update state. */
+	private updateCost() {
+		const tokenUsage = this.state.get('tokenUsage')!
+		const { inputCost, outputCost, totalCost } = calculateCost(this.model, tokenUsage.prompt, tokenUsage.completion, {
+			cachedTokens: tokenUsage.cachedTokens,
+			reasoningTokens: tokenUsage.reasoningTokens,
+		})
+		this.state.set('cost', { inputCost, outputCost, totalCost })
+	}
+
 	/** Apply Responses API usage stats to this conversation's token usage counters. */
 	private applyResponsesUsage(usage?: OpenAI.Responses.ResponseUsage) {
 		if (!usage) return
@@ -1171,7 +1229,10 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			prompt: prev.prompt + (usage.input_tokens || 0),
 			completion: prev.completion + (usage.output_tokens || 0),
 			total: prev.total + (usage.total_tokens || 0),
+			cachedTokens: prev.cachedTokens + (usage.input_tokens_details?.cached_tokens || 0),
+			reasoningTokens: prev.reasoningTokens + (usage.output_tokens_details?.reasoning_tokens || 0),
 		})
+		this.updateCost()
 	}
 
 	/**
@@ -1208,7 +1269,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		try {
 			const stream = await this.openai.raw.chat.completions.create({
 				model: this.model,
-				messages: this.messages,
+				messages: this.sanitizeMessages(this.getMessagesWithinBudget()),
 				stream: true,
 				...(toolsParam ? { tools: toolsParam, tool_choice: 'auto' } : {}),
 				...(this.maxTokens ? { [this.maxTokensParam]: this.maxTokens } : {}),
@@ -1258,8 +1319,11 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 					this.state.set('tokenUsage', {
 						prompt: prev.prompt + (chunk.usage.prompt_tokens || 0),
 						completion: prev.completion + (chunk.usage.completion_tokens || 0),
-						total: prev.total + (chunk.usage.total_tokens || 0)
+						total: prev.total + (chunk.usage.total_tokens || 0),
+						cachedTokens: prev.cachedTokens + (chunk.usage.prompt_tokens_details?.cached_tokens || 0),
+						reasoningTokens: prev.reasoningTokens + (chunk.usage.completion_tokens_details?.reasoning_tokens || 0),
 					})
+					this.updateCost()
 				}
 			}
 		} finally {
@@ -1310,6 +1374,113 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return accumulated
 	}
 
+	/**
+	 * Returns the messages array trimmed to fit within the maxInputTokens budget.
+	 * Keeps the system/developer message and drops oldest atomic groups first.
+	 *
+	 * Messages are grouped into atomic units so tool call/response pairs are never
+	 * split (which would cause a 400 from OpenAI):
+	 *   - assistant with tool_calls + its subsequent tool response messages = one group
+	 *   - standalone user, assistant (no tools), system = one group each
+	 *
+	 * If no maxInputTokens is set, returns messages as-is.
+	 */
+	private getMessagesWithinBudget(): Message[] {
+		const budget = resolveMaxInputTokens(this.options.maxInputTokens)
+		if (!budget) return this.messages
+
+		const messages = this.messages
+		if (messages.length === 0) return messages
+
+		// Check if the full history already fits
+		const fullCount = countMessageTokens(messages, this.model)
+		if (fullCount <= budget) return messages
+
+		// Separate system prompt from the rest
+		const systemMsg = (messages[0]?.role === 'system' || messages[0]?.role === 'developer')
+			? messages[0]
+			: null
+		const nonSystem = systemMsg ? messages.slice(1) : [...messages]
+
+		// Group messages into atomic units.
+		// An assistant message with tool_calls and its subsequent tool responses form one group.
+		type MessageGroup = Message[]
+		const groups: MessageGroup[] = []
+		let i = 0
+		while (i < nonSystem.length) {
+			const msg = nonSystem[i]!
+			if (msg.role === 'assistant' && (msg as any).tool_calls?.length) {
+				// Collect the assistant + all following tool responses that belong to it
+				const expectedIds = new Set(((msg as any).tool_calls as any[]).map((tc: any) => tc.id))
+				const group: Message[] = [msg]
+				let j = i + 1
+				while (j < nonSystem.length && nonSystem[j]!.role === 'tool' && expectedIds.has((nonSystem[j] as any).tool_call_id)) {
+					group.push(nonSystem[j]!)
+					j++
+				}
+				groups.push(group)
+				i = j
+			} else {
+				groups.push([msg])
+				i++
+			}
+		}
+
+		// Walk backwards through groups, accumulating tokens until we exceed the budget
+		const systemTokens = systemMsg ? countMessageTokens([systemMsg], this.model) : 0
+		let running = systemTokens
+		let cutoff = groups.length // start with nothing included
+
+		for (let g = groups.length - 1; g >= 0; g--) {
+			const groupTokens = countMessageTokens(groups[g]!, this.model)
+			if (running + groupTokens > budget) break
+			running += groupTokens
+			cutoff = g
+		}
+
+		const kept = groups.slice(cutoff).flat()
+		return systemMsg ? [systemMsg, ...kept] : kept
+	}
+
+	private sanitizeMessages(messages: Message[]): Message[] {
+		const result: Message[] = []
+
+		for (let i = 0; i < messages.length; i++) {
+			const msg = messages[i]!
+			result.push(msg)
+
+			// Check if this is an assistant message with tool_calls
+			if (msg.role === 'assistant' && (msg as any).tool_calls?.length) {
+				const toolCalls: Array<{ id: string }> = (msg as any).tool_calls
+				const expectedIds = new Set(toolCalls.map(tc => tc.id))
+
+				// Scan forward for matching tool responses
+				const foundIds = new Set<string>()
+				for (let j = i + 1; j < messages.length; j++) {
+					const next = messages[j]!
+					if (next.role === 'tool' && expectedIds.has((next as any).tool_call_id)) {
+						foundIds.add((next as any).tool_call_id)
+					} else if (next.role !== 'tool') {
+						break
+					}
+				}
+
+				// Add stub responses for any missing tool_call_ids
+				for (const id of expectedIds) {
+					if (!foundIds.has(id)) {
+						result.push({
+							role: 'tool',
+							tool_call_id: id,
+							content: '[tool execution was interrupted]',
+						} as any)
+					}
+				}
+			}
+		}
+
+		return result
+	}
+
 	/**
 	 * Append a message to the conversation state.
 	 *

package/src/agi/features/docs-reader.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from 'luca/feature'
 import { Feature } from '../feature.js'
 import type { ContentDb } from '@/node.js'
 import type Assistant from './assistant.js'
 
-declare module '@soederpop/luca/feature' {
+declare module 'luca/feature' {
 	interface AvailableFeatures {
 		docsReader: typeof DocsReader
 	}