@soederpop/luca 0.1.2 → 0.2.1

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

@@ -0,0 +1,175 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { Feature } from '../feature.js'
+import type { Helper } from '../../helper.js'
+import type { ChildProcess } from '../../node/features/proc.js'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		codingTools: typeof CodingTools
+	}
+}
+
+export const CodingToolsStateSchema = FeatureStateSchema.extend({})
+export const CodingToolsOptionsSchema = FeatureOptionsSchema.extend({})
+
+/**
+ * Shell primitives for AI coding assistants: rg, ls, cat, sed, awk.
+ *
+ * Wraps standard Unix tools into the assistant tool surface with
+ * LLM-optimized descriptions and system prompt guidance. These are
+ * the raw, flexible tools for reading, searching, and exploring code.
+ *
+ * Compose with other features (fileTools, processManager, skillsLibrary)
+ * in assistant hooks for a complete coding tool surface.
+ *
+ * Usage:
+ * ```typescript
+ * assistant.use(container.feature('codingTools'))
+ * ```
+ *
+ * @extends Feature
+ */
+export class CodingTools extends Feature {
+	static override shortcut = 'features.codingTools' as const
+	static override stateSchema = CodingToolsStateSchema
+	static override optionsSchema = CodingToolsOptionsSchema
+
+	static { Feature.register(this, 'codingTools') }
+
+	static override tools: Record<string, { schema: z.ZodType; description?: string }> = {
+		rg: {
+			description: 'ripgrep — fast content search across files. The fastest way to find where something is defined, referenced, or used. Supports regex, file type filtering, context lines, and everything ripgrep supports.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to rg, exactly as you would on the command line. ' +
+					'Examples: "TODO --type ts", "-n "function handleAuth" src/", ' +
+					'"import.*lodash -g "*.ts" --count", "-C 3 "class User" src/models/"'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('ripgrep — fast content search across files. Supports regex, file type filtering, context lines. Use this as your primary search tool for finding code.'),
+		},
+		ls: {
+			description: 'List files and directories. Use to orient yourself in the project structure, check what exists in a directory, or verify paths before operating on them.',
+			schema: z.object({
+				args: z.string().optional().describe(
+					'Arguments to pass to ls. Examples: "-la src/", "-R --color=never commands/", "-1 *.ts". ' +
+					'Defaults to listing the project root.'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('List files and directories. Use to orient yourself, check directory contents, or verify paths.'),
+		},
+		cat: {
+			description: 'Read file contents. Use for reading entire files or specific line ranges. For large files, prefer reading specific ranges with sed or use rg to find the relevant section first.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to cat. Typically just a file path. ' +
+					'Examples: "src/index.ts", "-n src/index.ts" (with line numbers). ' +
+					'For line ranges, use sed instead: sed -n "10,20p" file.ts'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('Read file contents. Best for reading entire files or viewing file content with line numbers.'),
+		},
+		sed: {
+			description: 'Stream editor for extracting or transforming text. Use for reading specific line ranges from files, or performing find-and-replace operations.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to sed. Examples: ' +
+					'"-n \\"10,30p\\" src/index.ts" (print lines 10-30), ' +
+					'"-n \\"1,5p\\" package.json" (first 5 lines), ' +
+					'"s/oldName/newName/g src/config.ts" (find-and-replace)'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('Stream editor for extracting line ranges or transforming text in files.'),
+		},
+		awk: {
+			description: 'Pattern scanning and text processing. Use for extracting specific fields from structured output, summarizing data, or complex text transformations.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to awk. Examples: ' +
+					'"\'{print $1}\' file.txt" (first column), ' +
+					'"-F: \'{print $1, $3}\' /etc/passwd" (colon-delimited fields), ' +
+					'"\'/pattern/ {print}\' file.txt" (lines matching pattern)'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('Pattern scanning and text processing. Extract fields, summarize data, or perform complex text transformations.'),
+		},
+	}
+
+	private get proc(): ChildProcess {
+		return this.container.feature('proc') as unknown as ChildProcess
+	}
+
+	// -------------------------------------------------------------------------
+	// Shell tool implementations
+	// -------------------------------------------------------------------------
+
+	private async _exec(command: string, args: string, cwd?: string): Promise<string> {
+		const fullCommand = args ? `${command} ${args}` : command
+		const result = await this.proc.execAndCapture(fullCommand, {
+			cwd: cwd ?? this.container.cwd,
+		})
+
+		if (result.exitCode !== 0) {
+			const parts: string[] = []
+			if (result.stdout?.trim()) parts.push(result.stdout.trim())
+			if (result.stderr?.trim()) parts.push(`[stderr] ${result.stderr.trim()}`)
+			parts.push(`[exit code: ${result.exitCode}]`)
+			return parts.join('\n')
+		}
+
+		return result.stdout || '(no output)'
+	}
+
+	async rg(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('rg', args.args, args.cwd)
+	}
+
+	async ls(args: { args?: string; cwd?: string }): Promise<string> {
+		return this._exec('ls', args.args || '', args.cwd)
+	}
+
+	async cat(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('cat', args.args, args.cwd)
+	}
+
+	async sed(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('sed', args.args, args.cwd)
+	}
+
+	async awk(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('awk', args.args, args.cwd)
+	}
+
+	override setupToolsConsumer(consumer: Helper) {
+		if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+			(consumer as any).addSystemPromptExtension('codingTools', SYSTEM_PROMPT_EXTENSION)
+		}
+	}
+}
+
+// ─── System Prompt Extension ──────────────────────────────────────────────────
+
+const SYSTEM_PROMPT_EXTENSION = [
+	'## Shell Tools',
+	'',
+	'You have direct access to standard Unix tools. These are your primary read/search/explore tools:',
+	'',
+	'**`rg` (ripgrep) — your most important tool.** Use it before guessing where anything is.',
+	'- `rg -n "pattern" --type ts` — search TypeScript files with line numbers',
+	'- `rg -C 3 "pattern"` — show 3 lines of context around matches',
+	'- `rg -l "pattern"` — list only filenames that match',
+	'- `rg "TODO|FIXME" --type ts --count` — count matches per file',
+	'',
+	'**`cat` — read files.** Use `cat -n` for line numbers. For large files, use `sed -n "10,30p"` to read a range.',
+	'',
+	'**`ls` — orient yourself.** `ls -la src/` for details, `ls -R` for recursive listing.',
+	'',
+	'**`sed` — extract line ranges.** `sed -n "50,80p" file.ts` reads lines 50-80.',
+	'',
+	'**`awk` — structured text processing.** Extract columns, summarize, transform.',
+	'',
+	'**Workflow:** `rg` to find → `cat -n` to read → `editFile` to change → `runCommand` to verify.',
+].join('\n')
+
+export default CodingTools

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

@@ -1,8 +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 { NodeContainer, type DiskCache, type NodeFeatures } from '@soederpop/luca/node/container'
+import { Feature } from '../feature.js'
+import type { DiskCache } from '@soederpop/luca/node/container'
 import type { Message } from './conversation'
 
 declare module '@soederpop/luca/feature' {
@@ -95,10 +95,6 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 		}
 	}
 
-	/** @returns The parent NodeContainer, narrowed from the base Container type. */
-	override get container() {
-		return super.container as NodeContainer<NodeFeatures, any>
-	}
 
 	/** @returns The diskCache feature instance used for persistence, configured with the optional cachePath. */
 	get diskCache(): DiskCache {

package/src/agi/features/conversation.ts

@@ -1,7 +1,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'
 import type { OpenAIClient } from '../../clients/openai';
 import type OpenAI from 'openai';
 import type { ConversationHistory } from './conversation-history';
@@ -212,9 +212,12 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	/** The active structured output schema for the current ask() call, if any. */
 	private _activeSchema: z.ZodType | null = null
 
-	/** Resolved max tokens: per-call override > options-level > default 512. */
+	/** Registered stubs: matched against user input to short-circuit the API with a canned response. */
+	private _stubs: Array<{ matcher: string | RegExp; response: string | (() => string) }> = []
+
+	/** Resolved max tokens: per-call override > options-level. Undefined means no limit (model default). */
 	private get maxTokens(): number | undefined {
-		return (this.state.get('callMaxTokens') as number | null) ?? this.options.maxTokens ?? 512
+		return (this.state.get('callMaxTokens') as number | null) ?? this.options.maxTokens ?? undefined
 	}
 
 	/** @returns Default state seeded from options: id, thread, model, initial history, and zero token usage. */
@@ -276,6 +279,22 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return this
 	}
 
+	/**
+	 * Register a hardcoded stub response that bypasses the API when the user's message matches.
+	 * Streaming is still simulated — chunk/preview events fire word-by-word.
+	 *
+	 * @param matcher - Exact string match, substring, or RegExp tested against user input
+	 * @param response - The text to stream back, or a zero-arg function that returns it
+	 *
+	 * @example
+	 * conversation.stub('hello', 'Hi there!')
+	 * conversation.stub(/weather/i, () => 'Sunny and 72°F.')
+	 */
+	stub(matcher: string | RegExp, response: string | (() => string)): this {
+		this._stubs.push({ matcher, response })
+		return this
+	}
+
 	/** Returns configured remote MCP servers keyed by server label. */
 	get mcpServers(): Record<string, ConversationMCPServer> {
 		return (this.options.mcpServers || {}) as Record<string, ConversationMCPServer>
@@ -286,6 +305,30 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return this.state.get('messages') || []
 	}
 
+	/**
+	 * Fork the conversation into a new independent instance.
+	 * The fork inherits the same system prompt, tools, and full message history,
+	 * but has its own identity and state — changes in either direction do not affect the other.
+	 *
+	 * @param overrides - Optional option overrides for the forked conversation (e.g. different model or title)
+	 *
+	 * @example
+	 * ```typescript
+	 * const fork = conversation.fork()
+	 * await fork.ask('What if we took a different approach?')
+	 * // original conversation is unchanged
+	 * ```
+	 */
+	fork(overrides: Partial<ConversationOptions> = {}): Conversation {
+		return this.container.feature('conversation', {
+			...this.options,
+			id: undefined,
+			history: JSON.parse(JSON.stringify(this.messages)),
+			tools: { ...this.tools },
+			...overrides,
+		})
+	}
+
 	/** Returns the OpenAI model name being used for completions. */
 	get model(): string {
 		return this.state.get('model')!
@@ -518,6 +561,11 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		this.emit('userMessage', content)
 
 		try {
+			const stubText = this._matchStub(typeof content === 'string' ? content : '')
+			if (stubText !== null) {
+				return await this._streamStub(stubText)
+			}
+
 			let raw: string
 
 			if (this.apiMode === 'responses') {
@@ -764,6 +812,50 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		}
 	}
 
+	/** Check registered stubs against user input. Returns the response text, or null if no match. */
+	private _matchStub(input: string): string | null {
+		for (const { matcher, response } of this._stubs) {
+			const matched = typeof matcher === 'string'
+				? input === matcher || input.includes(matcher)
+				: matcher.test(input)
+			if (matched) {
+				return typeof response === 'function' ? response() : response
+			}
+		}
+		return null
+	}
+
+	/**
+	 * Simulate a streaming response for a hardcoded stub text.
+	 * Emits chunk/preview events word-by-word, yielding between each to keep the event loop alive.
+	 */
+	private async _streamStub(text: string): Promise<string> {
+		this.state.set('streaming', true)
+		this.emit('turnStart', { turn: 1, isFollowUp: false })
+
+		let accumulated = ''
+		const chunks = text.match(/\S+\s*/g) ?? [text]
+
+		try {
+			for (const chunk of chunks) {
+				accumulated += chunk
+				this.emit('chunk', chunk)
+				this.emit('preview', accumulated)
+				await Promise.resolve()
+			}
+		} finally {
+			this.state.set('streaming', false)
+		}
+
+		const trimmed = text
+		this.pushMessage({ role: 'assistant', content: trimmed })
+		this.state.set('lastResponse', trimmed)
+		this.emit('turnEnd', { turn: 1, hasToolCalls: false })
+		this.emit('response', trimmed)
+
+		return trimmed
+	}
+
 	/**
 	 * Runs the streaming Responses API loop. Handles local function calls by
 	 * executing handlers and submitting `function_call_output` items until

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

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures, Feature } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 import type { ContentDb } from '@/node.js'
 import type Assistant from './assistant.js'
 

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

@@ -1,6 +1,6 @@
 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 { FS } from '../../node/features/fs.js'
 import type { Grep, GrepMatch } from '../../node/features/grep.js'
 import type { Helper } from '../../helper.js'
@@ -38,7 +38,7 @@ export class FileTools extends Feature {
 
 	static { Feature.register(this, 'fileTools') }
 
-	static tools: Record<string, { schema: z.ZodType; description?: string }> = {
+	static override tools: Record<string, { schema: z.ZodType; description?: string }> = {
 		readFile: {
 			description: 'Read the contents of a file. Returns the text content. Use offset/limit to read portions of large files.',
 			schema: z.object({
@@ -48,20 +48,20 @@ export class FileTools extends Feature {
 			}).describe('Read the contents of a file. Returns the text content. Use offset/limit to read portions of large files.'),
 		},
 		writeFile: {
-			description: 'Create a new file or overwrite an existing file with the given content. Prefer editFile for modifying existing files.',
+			description: 'Create a new file or completely overwrite an existing file. WARNING: this replaces the entire file — use editFile instead for modifying existing files. Use writeFile only for creating new files or intentional full rewrites.',
 			schema: z.object({
-				path: z.string().describe('File path relative to the project root'),
-				content: z.string().describe('The full content to write'),
-			}).describe('Create a new file or overwrite an existing file with the given content. Prefer editFile for modifying existing files.'),
+				path: z.string().describe('File path relative to the project root. Parent directories are created automatically.'),
+				content: z.string().describe('The complete file content. This replaces everything in the file — there is no merge or append.'),
+			}).describe('Create a new file or completely overwrite an existing file. WARNING: this replaces the entire file — use editFile instead for modifying existing files. Use writeFile only for creating new files or intentional full rewrites.'),
 		},
 		editFile: {
-			description: 'Make a surgical edit to a file by replacing an exact string match. The oldString must appear exactly once in the file (unless replaceAll is true). This is the preferred way to modify existing files.',
+			description: 'Make a surgical edit to a file by replacing an exact string match. The preferred way to modify existing files — always use this over writeFile for changes to existing code.',
 			schema: z.object({
 				path: z.string().describe('File path relative to the project root'),
-				oldString: z.string().describe('The exact text to find and replace'),
-				newString: z.string().describe('The replacement text'),
-				replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness (default: false)'),
-			}).describe('Make a surgical edit to a file by replacing an exact string match. The oldString must appear exactly once in the file (unless replaceAll is true).'),
+				oldString: z.string().describe('The EXACT text to find, copied verbatim from the file — including whitespace and indentation. Must appear exactly once in the file (unless replaceAll is true). If the match fails, read the file again and copy the exact text.'),
+				newString: z.string().describe('The replacement text. Preserve the same indentation style as the surrounding code.'),
+				replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness. Use for renaming a variable across a file. Default: false.'),
+			}).describe('Make a surgical edit to a file by replacing an exact string match. The preferred way to modify existing files — always use this over writeFile for changes to existing code.'),
 		},
 		listDirectory: {
 			description: 'List files and directories at a path. Returns arrays of file and directory names.',
@@ -73,23 +73,23 @@ export class FileTools extends Feature {
 			}).describe('List files and directories at a path. Returns arrays of file and directory names.'),
 		},
 		searchFiles: {
-			description: 'Search file contents for a pattern using ripgrep. Returns structured matches with file, line number, and content.',
+			description: 'Search inside file contents for a pattern (like grep/ripgrep). Returns matching lines with file path and line number. Use this to find where code is defined, where a function is called, or any text pattern across the codebase.',
 			schema: z.object({
-				pattern: z.string().describe('Search pattern (regex supported)'),
-				path: z.string().optional().describe('Directory to search in (defaults to project root)'),
-				include: z.string().optional().describe('Glob pattern to filter files (e.g. "*.ts")'),
-				exclude: z.string().optional().describe('Glob pattern to exclude (e.g. "node_modules")'),
-				ignoreCase: z.boolean().optional().describe('Case insensitive search'),
-				maxResults: z.number().optional().describe('Maximum number of results to return'),
-			}).describe('Search file contents for a pattern using ripgrep. Returns structured matches with file, line number, and content.'),
+				pattern: z.string().describe('Search pattern — supports regex. Examples: "function handleAuth", "TODO|FIXME", "import.*from.*react"'),
+				path: z.string().optional().describe('Directory to search in (defaults to project root). Narrow this to avoid searching node_modules or irrelevant directories.'),
+				include: z.string().optional().describe('Glob to filter which files to search (e.g. "*.ts", "*.tsx"). Use this to scope to specific file types.'),
+				exclude: z.string().optional().describe('Glob to exclude files (e.g. "node_modules", "dist"). node_modules is excluded by default.'),
+				ignoreCase: z.boolean().optional().describe('Case insensitive search. Default: false.'),
+				maxResults: z.number().optional().describe('Maximum results to return. Default: 50. Use a smaller number for broad patterns.'),
+			}).describe('Search inside file contents for a pattern (like grep/ripgrep). Returns matching lines with file path and line number. Use this to find where code is defined, where a function is called, or any text pattern across the codebase.'),
 		},
 		findFiles: {
-			description: 'Find files by name/glob pattern. Returns matching file paths.',
+			description: 'Find files by name or glob pattern. Returns file paths, not contents. Use this to locate files ("where is the config?"), not to search inside them (use searchFiles for that).',
 			schema: z.object({
-				pattern: z.string().describe('Glob pattern to match (e.g. "**/*.test.ts", "src/**/*.tsx")'),
+				pattern: z.string().describe('Glob pattern to match file names. Examples: "**/*.test.ts", "src/**/*.tsx", "**/config.*"'),
 				path: z.string().optional().describe('Directory to search from (defaults to project root)'),
-				exclude: z.string().optional().describe('Glob pattern to exclude'),
-			}).describe('Find files by name/glob pattern. Returns matching file paths.'),
+				exclude: z.string().optional().describe('Glob pattern to exclude. node_modules and .git are excluded by default.'),
+			}).describe('Find files by name or glob pattern. Returns file paths, not contents. Use this to locate files ("where is the config?"), not to search inside them (use searchFiles for that).'),
 		},
 		fileInfo: {
 			description: 'Get information about a file or directory: whether it exists, its type (file/directory), size, and modification time.',
@@ -273,11 +273,18 @@ export class FileTools extends Feature {
 		if (typeof (consumer as any).addSystemPromptExtension === 'function') {
 			(consumer as any).addSystemPromptExtension('fileTools', [
 				'## File Tools',
-				'- All file paths are relative to the project root unless they start with /',
-				'- Use `searchFiles` to understand code before modifying it',
-				'- Use `editFile` for surgical changes to existing files — prefer it over `writeFile`',
-				'- Use `listDirectory` to explore before assuming paths exist',
-				'- Use `readFile` with offset/limit for large files instead of reading the entire file',
+				'',
+				'All paths are relative to the project root unless they start with /.',
+				'',
+				'**Before modifying code:** Always read the file first. Use `searchFiles` to find where something is defined before making changes. Use `listDirectory` to verify paths exist before assuming.',
+				'',
+				'**Editing files:** Prefer `editFile` over `writeFile` for existing files — it makes surgical replacements. The `oldString` must appear exactly once in the file (unless using `replaceAll`). If your match isn\'t unique, include more surrounding context to make it unique. Never guess at file contents — read first, then edit.',
+				'',
+				'**Finding things:** Use `findFiles` to locate files by name or glob pattern (e.g. "**/*.test.ts"). Use `searchFiles` to find specific content inside files (grep). These are different tools for different questions: "where is the file?" vs "where is this code?".',
+				'',
+				'**Large files:** Use `readFile` with `offset` and `limit` to read portions. Don\'t load a 5000-line file when you only need lines 100-150.',
+				'',
+				'**`writeFile` is destructive** — it overwrites the entire file. Only use it for creating new files or when you intend a complete rewrite.',
 			].join('\n'))
 		}
 	}

package/src/agi/features/luca-coder.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'
 
@@ -214,9 +213,6 @@ export class LucaCoder extends Feature<LucaCoderState, LucaCoderOptions> {
 		}
 	}
 
-	override get container(): AGIContainer {
-		return super.container as AGIContainer
-	}
 
 	/** The inner assistant. Throws if not started. */
 	get assistant(): Assistant {

package/src/agi/features/openai-codex.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 {

package/src/agi/features/openapi.ts

@@ -1,4 +1,4 @@
-import { Feature } from '../../feature.js'
+import { Feature } from '../feature.js'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { z } from 'zod'
 import { camelCase } from 'lodash-es'
@@ -95,7 +95,7 @@ export interface OpenAIToolDef {
  * api.endpoint('getPetById')
  *
  * // Convert to OpenAI tool definitions
- * api.toTools()
+ * api.toOpenAITools()
  *
  * // Convert a single endpoint to a function definition
  * api.toFunction('getPetById')
@@ -205,7 +205,7 @@ export class OpenAPI extends Feature<OpenAPIState, OpenAPIOptions> {
    * @param {Function} [filter] - Optional predicate to select which endpoints to include
    * @returns {OpenAIToolDef[]} Array of tool definitions ready for the OpenAI tools parameter
    */
-  toTools(filter?: (ep: EndpointInfo) => boolean): OpenAIToolDef[] {
+  toOpenAITools(filter?: (ep: EndpointInfo) => boolean): OpenAIToolDef[] {
     const eps = filter ? this.endpoints.filter(filter) : this.endpoints
     return eps.map((ep) => ({
       type: 'function' as const,