luca 3.0.0 → 3.0.2

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
 	}

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

@@ -5,14 +5,17 @@ import type { FS } from '../../node/features/fs.js'
 import type { Grep, GrepMatch } from '../../node/features/grep.js'
 import type { Helper } from '../../helper.js'
 
-declare module '@soederpop/luca/feature' {
+declare module 'luca/feature' {
 	interface AvailableFeatures {
 		fileTools: typeof FileTools
 	}
 }
 
 export const FileToolsStateSchema = FeatureStateSchema.extend({})
-export const FileToolsOptionsSchema = FeatureOptionsSchema.extend({})
+export const FileToolsOptionsSchema = FeatureOptionsSchema.extend({
+	lockToFolder: z.string().optional().describe('When set, all file operations are restricted to this folder. Paths outside it are rejected.'),
+	forbid: z.array(z.union([z.string(), z.instanceof(RegExp)])).optional().describe('Patterns (strings or RegExps) that block access to any matching path.'),
+})
 
 /**
  * Curated file-system and code-search tools for AI assistants.
@@ -133,11 +136,43 @@ export class FileTools extends Feature {
 		return this.container.feature('grep') as unknown as Grep
 	}
 
+	/**
+	 * Resolve a user-supplied path to an absolute path and validate it against
+	 * `lockToFolder` and `forbid` constraints. Throws if the path is blocked.
+	 */
+	private validatePath(inputPath: string): string {
+		const resolved = this.container.paths.resolve(inputPath)
+
+		const { lockToFolder, forbid } = this.options as { lockToFolder?: string; forbid?: (string | RegExp)[] }
+
+		if (lockToFolder) {
+			const folder = this.container.paths.resolve(lockToFolder)
+			// The resolved path must be inside the locked folder (or be the folder itself)
+			if (resolved !== folder && !resolved.startsWith(folder + '/')) {
+				throw new Error(`Access denied: "${inputPath}" is outside the allowed folder "${lockToFolder}"`)
+			}
+		}
+
+		if (forbid && forbid.length) {
+			for (const pattern of forbid) {
+				const matches = pattern instanceof RegExp
+					? pattern.test(resolved)
+					: resolved.includes(pattern)
+				if (matches) {
+					throw new Error(`Access denied: "${inputPath}" matches forbidden pattern "${pattern}"`)
+				}
+			}
+		}
+
+		return resolved
+	}
+
 	// -------------------------------------------------------------------------
 	// Tool implementations — each matches a static tools key by name
 	// -------------------------------------------------------------------------
 
 	async readFile(args: { path: string; offset?: number; limit?: number }): Promise<string> {
+		this.validatePath(args.path)
 		const content = await this.fs.readFileAsync(args.path) as string
 
 		if (args.offset || args.limit) {
@@ -151,12 +186,14 @@ export class FileTools extends Feature {
 	}
 
 	async writeFile(args: { path: string; content: string }): Promise<string> {
+		this.validatePath(args.path)
 		await this.fs.ensureFolderAsync(args.path.includes('/') ? args.path.split('/').slice(0, -1).join('/') : '.')
 		await this.fs.writeFileAsync(args.path, args.content)
 		return `Wrote ${args.content.length} bytes to ${args.path}`
 	}
 
 	async editFile(args: { path: string; oldString: string; newString: string; replaceAll?: boolean }): Promise<string> {
+		this.validatePath(args.path)
 		const content = await this.fs.readFileAsync(args.path) as string
 
 		if (args.replaceAll) {
@@ -183,6 +220,7 @@ export class FileTools extends Feature {
 
 	async listDirectory(args: { path?: string; recursive?: boolean; include?: string; exclude?: string }): Promise<string> {
 		const dir = args.path || '.'
+		this.validatePath(dir)
 		const result = await this.fs.walkAsync(dir, {
 			files: true,
 			directories: true,
@@ -201,6 +239,7 @@ export class FileTools extends Feature {
 	}
 
 	async searchFiles(args: { pattern: string; path?: string; include?: string; exclude?: string; ignoreCase?: boolean; maxResults?: number }): Promise<string> {
+		if (args.path) this.validatePath(args.path)
 		const results: GrepMatch[] = await this.grep.search({
 			pattern: args.pattern,
 			path: args.path,
@@ -219,6 +258,7 @@ export class FileTools extends Feature {
 
 	async findFiles(args: { pattern: string; path?: string; exclude?: string }): Promise<string> {
 		const dir = args.path || '.'
+		this.validatePath(dir)
 		const result = await this.fs.walkAsync(dir, {
 			files: true,
 			directories: false,
@@ -230,6 +270,7 @@ export class FileTools extends Feature {
 	}
 
 	async fileInfo(args: { path: string }): Promise<string> {
+		this.validatePath(args.path)
 		const exists = await this.fs.existsAsync(args.path)
 		if (!exists) return JSON.stringify({ exists: false })
 
@@ -244,21 +285,27 @@ export class FileTools extends Feature {
 	}
 
 	async createDirectory(args: { path: string }): Promise<string> {
+		this.validatePath(args.path)
 		await this.fs.ensureFolderAsync(args.path)
 		return `Created ${args.path}`
 	}
 
 	async moveFile(args: { source: string; destination: string }): Promise<string> {
+		this.validatePath(args.source)
+		this.validatePath(args.destination)
 		await this.fs.moveAsync(args.source, args.destination)
 		return `Moved ${args.source} → ${args.destination}`
 	}
 
 	async copyFile(args: { source: string; destination: string }): Promise<string> {
+		this.validatePath(args.source)
+		this.validatePath(args.destination)
 		await this.fs.copyAsync(args.source, args.destination)
 		return `Copied ${args.source} → ${args.destination}`
 	}
 
 	async deleteFile(args: { path: string }): Promise<string> {
+		this.validatePath(args.path)
 		const isDir = await this.fs.isDirectoryAsync(args.path)
 		if (isDir) return `Error: "${args.path}" is a directory. Use deleteFile only for files.`
 		await this.fs.rm(args.path)

package/src/agi/features/luca-coder.ts

@@ -4,7 +4,7 @@ import { Feature } from '../feature.js'
 import type { Assistant } from './assistant.js'
 import type { ToolCallCtx } from '../lib/interceptor-chain.js'
 
-declare module '@soederpop/luca/feature' {
+declare module 'luca/feature' {
 	interface AvailableFeatures {
 		lucaCoder: typeof LucaCoder
 	}
@@ -104,8 +104,8 @@ export const LucaCoderOptionsSchema = FeatureOptionsSchema.extend({
 	/** Skills to auto-load into the system prompt context. If not specified, auto-detects luca-framework. */
 	skills: z.array(z.string()).optional().describe('Skill names to auto-load into the system prompt'),
 
-	/** Whether to auto-detect and load the luca-framework skill. Defaults to true. */
-	autoLoadLucaSkill: z.boolean().default(true).describe('Auto-load luca-framework skill if found in .claude/skills path'),
+	/** Whether to auto-detect and load the luca-framework skill from conventional agent skill folders. Defaults to true. */
+	autoLoadLucaSkill: z.boolean().default(true).describe('Auto-load luca-framework skill if found in agent skill folders (.claude/skills or .agents/skills)'),
 })
 
 export type LucaCoderState = z.infer<typeof LucaCoderStateSchema>
@@ -116,7 +116,7 @@ export type LucaCoderOptions = z.infer<typeof LucaCoderOptionsSchema>
  * gates all tool calls through a permission system.
  *
  * Comes with built-in Bash tool (via proc.execAndCapture) and auto-loads
- * the luca-framework skill when found in .claude/skills paths.
+ * the luca-framework skill when found in conventional agent skill folders (.claude/skills or .agents/skills).
  *
  * Tools are stacked from feature bundles (fileTools, etc.)
  * and each tool can be set to 'allow' (runs immediately), 'ask' (blocks
@@ -415,11 +415,13 @@ export class LucaCoder extends Feature<LucaCoderState, LucaCoderOptions> {
 		const skillContent: string[] = []
 		const loadedSkills: string[] = []
 
-		// Check for luca-framework skill in known locations
+		// Check for luca-framework skill in conventional agent skill folders
 		if (this.options.autoLoadLucaSkill !== false) {
 			const skillLocations = [
 				paths.resolve(this.container.cwd, '.claude', 'skills', 'luca-framework', 'SKILL.md'),
+				paths.resolve(this.container.cwd, '.agents', 'skills', 'luca-framework', 'SKILL.md'),
 				paths.resolve(os.homedir, '.claude', 'skills', 'luca-framework', 'SKILL.md'),
+				paths.resolve(os.homedir, '.agents', 'skills', 'luca-framework', 'SKILL.md'),
 			]
 
 			for (const skillPath of skillLocations) {