@qduc/term2 0.3.1 → 0.4.0

package/dist/prompts/search-via-shell.js

@@ -0,0 +1,59 @@
+import { spawnSync } from 'child_process';
+function defaultCheckBinary(cmd) {
+    try {
+        const result = spawnSync(cmd, ['--version'], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function getSearchViaShellAddendum(options = {}) {
+    const checkBinary = options.checkBinary ?? defaultCheckBinary;
+    const isRemote = options.executionContext?.isRemote() ?? false;
+    // For remote hosts, we can't synchronously check binary availability.
+    // Default to grep/find which are universally available on Unix-like systems.
+    const hasRg = isRemote ? false : checkBinary('rg');
+    const hasFd = isRemote ? false : checkBinary('fd');
+    const header = `### Searching via the shell
+
+Use the \`shell\` tool with the standard CLI binaries.`;
+    const textSearch = hasRg
+        ? `**For text search**, use \`rg\` (ripgrep). Examples:
+- \`rg "pattern" src/\` — basic search, respects \`.gitignore\` by default.
+- \`rg -i "pattern" .\` — case-insensitive.
+- \`rg --no-ignore "pattern" .\` — when you need to search \`node_modules\`, build output, or anything in \`.gitignore\`.
+- \`rg -uu "pattern" .\` — include hidden + gitignored.
+- \`rg -g '*.ts' "pattern" .\` — restrict by glob.
+- \`rg -t ts "pattern" .\` — restrict by language preset.
+- \`rg -n "pattern" .\` — show line numbers (useful for follow-up edits).
+- \`rg -l "pattern" .\` — list files only.
+- \`rg -C 3 "pattern" .\` — 3 lines of context.
+- **Always pass an explicit path** (e.g. \`.\` or \`src/\`) to \`rg\`. When no path is given and stdin is a pipe, ripgrep reads stdin instead of searching the filesystem, returning no results.`
+        : `**For text search**, use \`grep\`. Examples:
+- \`grep -rn "pattern" src/\` — recursive search with line numbers.
+- \`grep -ri "pattern" src/\` — case-insensitive recursive search.
+- \`grep -rl "pattern" src/\` — list matching files only.
+- \`grep -C 3 "pattern" src/\` — show 3 lines of context.`;
+    const fileSearch = hasFd
+        ? `**For file search**, use \`fd\`. Examples:
+- \`fd '\\.ts$'\` — regex over basenames.
+- \`fd -e ts\` — by extension.
+- \`fd -H -I\` — include hidden + gitignored (\`-uu\` style).
+- \`fd 'pattern' path/\` — scoped to a directory.`
+        : `**For file search**, use \`find\`. Examples:
+- \`find src/ -type f -name '*.ts'\` — search a subtree by basename glob.
+- **Always search from a specific path, not \`/\`.** Scanning the whole filesystem can exhaust resources on large trees.
+- When using \`find -regex\` with alternation, put the longest alternative first: \`'.*\\.(tsx|ts)'\` works; \`'.*\\.(ts|tsx)'\` silently skips \`.tsx\`.`;
+    const hygiene = `**General shell hygiene:**
+- Quote paths that contain spaces.
+- Prefer absolute paths or paths relative to a known root; avoid \`cd\`.
+- When chaining commands, use \`&&\` for "stop on first failure", \`;\` only if you accept failures, never raw newlines.
+- Don't use \`cat\` / \`head\` / \`tail\` / \`sed\` / \`echo\` for reading or writing files — use the dedicated \`read_file\`, \`apply_patch\`, and \`search_replace\` tools. The shell is for *search* and *one-shot inspection*, not for editing.
+- For destructive operations (deletes, force-pushes, schema migrations), pause and confirm before running.`;
+    return `${header}\n\n${textSearch}\n\n${fileSearch}\n\n${hygiene}`;
+}
+//# sourceMappingURL=search-via-shell.js.map

package/dist/prompts/search-via-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-via-shell.js","sourceRoot":"","sources":["../../source/prompts/search-via-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG1C,SAAS,kBAAkB,CAAC,GAAW;IACrC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE;YAC3C,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAOD,MAAM,UAAU,yBAAyB,CAAC,UAAiC,EAAE;IAC3E,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,CAAC;IAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,EAAE,QAAQ,EAAE,IAAI,KAAK,CAAC;IAE/D,sEAAsE;IACtE,6EAA6E;IAC7E,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAEnD,MAAM,MAAM,GAAG;;uDAEsC,CAAC;IAEtD,MAAM,UAAU,GAAG,KAAK;QACtB,CAAC,CAAC;;;;;;;;;;iMAU2L;QAC7L,CAAC,CAAC;;;;0DAIoD,CAAC;IAEzD,MAAM,UAAU,GAAG,KAAK;QACtB,CAAC,CAAC;;;;kDAI4C;QAC9C,CAAC,CAAC;;;0JAGoJ,CAAC;IAEzJ,MAAM,OAAO,GAAG;;;;;2GAKyF,CAAC;IAE1G,OAAO,GAAG,MAAM,OAAO,UAAU,OAAO,UAAU,OAAO,OAAO,EAAE,CAAC;AACrE,CAAC"}

package/dist/prompts/search-via-shell.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-via-shell.test.d.ts.map

package/dist/prompts/search-via-shell.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-via-shell.test.d.ts","sourceRoot":"","sources":["../../source/prompts/search-via-shell.test.ts"],"names":[],"mappings":""}

package/dist/prompts/search-via-shell.test.js

@@ -0,0 +1,40 @@
+import test from 'ava';
+import { getSearchViaShellAddendum } from './search-via-shell.js';
+test('getSearchViaShellAddendum includes rg and fd when both available', (t) => {
+    const result = getSearchViaShellAddendum({
+        checkBinary: () => true,
+    });
+    t.true(result.includes('use `rg` (ripgrep)'));
+    t.true(result.includes('use `fd`'));
+    t.false(result.includes('use `grep`'));
+    t.false(result.includes('use `find`'));
+    t.true(result.includes('General shell hygiene'));
+});
+test('getSearchViaShellAddendum falls back to grep when rg is missing', (t) => {
+    const result = getSearchViaShellAddendum({
+        checkBinary: (cmd) => cmd === 'fd',
+    });
+    t.false(result.includes('use `rg` (ripgrep)'));
+    t.true(result.includes('use `grep`'));
+    t.true(result.includes('use `fd`'));
+    t.false(result.includes('use `find`'));
+});
+test('getSearchViaShellAddendum falls back to find when fd is missing', (t) => {
+    const result = getSearchViaShellAddendum({
+        checkBinary: (cmd) => cmd === 'rg',
+    });
+    t.true(result.includes('use `rg` (ripgrep)'));
+    t.false(result.includes('use `fd`'));
+    t.true(result.includes('use `find`'));
+});
+test('getSearchViaShellAddendum falls back to grep and find when both missing', (t) => {
+    const result = getSearchViaShellAddendum({
+        checkBinary: () => false,
+    });
+    t.false(result.includes('use `rg` (ripgrep)'));
+    t.true(result.includes('use `grep`'));
+    t.false(result.includes('use `fd`'));
+    t.true(result.includes('use `find`'));
+    t.true(result.includes('General shell hygiene'));
+});
+//# sourceMappingURL=search-via-shell.test.js.map

package/dist/prompts/search-via-shell.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-via-shell.test.js","sourceRoot":"","sources":["../../source/prompts/search-via-shell.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,KAAK,CAAC;AACvB,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,IAAI,CAAC,kEAAkE,EAAE,CAAC,CAAC,EAAE,EAAE;IAC7E,MAAM,MAAM,GAAG,yBAAyB,CAAC;QACvC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI;KACxB,CAAC,CAAC;IAEH,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iEAAiE,EAAE,CAAC,CAAC,EAAE,EAAE;IAC5E,MAAM,MAAM,GAAG,yBAAyB,CAAC;QACvC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI;KACnC,CAAC,CAAC;IAEH,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;AACzC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iEAAiE,EAAE,CAAC,CAAC,EAAE,EAAE;IAC5E,MAAM,MAAM,GAAG,yBAAyB,CAAC;QACvC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI;KACnC,CAAC,CAAC;IAEH,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;AACxC,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,yEAAyE,EAAE,CAAC,CAAC,EAAE,EAAE;IACpF,MAAM,MAAM,GAAG,yBAAyB,CAAC;QACvC,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK;KACzB,CAAC,CAAC;IAEH,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC"}

package/dist/prompts/search-via-shell.test.ts

@@ -0,0 +1,47 @@
+import test from 'ava';
+import { getSearchViaShellAddendum } from './search-via-shell.js';
+
+test('getSearchViaShellAddendum includes rg and fd when both available', (t) => {
+  const result = getSearchViaShellAddendum({
+    checkBinary: () => true,
+  });
+
+  t.true(result.includes('use `rg` (ripgrep)'));
+  t.true(result.includes('use `fd`'));
+  t.false(result.includes('use `grep`'));
+  t.false(result.includes('use `find`'));
+  t.true(result.includes('General shell hygiene'));
+});
+
+test('getSearchViaShellAddendum falls back to grep when rg is missing', (t) => {
+  const result = getSearchViaShellAddendum({
+    checkBinary: (cmd) => cmd === 'fd',
+  });
+
+  t.false(result.includes('use `rg` (ripgrep)'));
+  t.true(result.includes('use `grep`'));
+  t.true(result.includes('use `fd`'));
+  t.false(result.includes('use `find`'));
+});
+
+test('getSearchViaShellAddendum falls back to find when fd is missing', (t) => {
+  const result = getSearchViaShellAddendum({
+    checkBinary: (cmd) => cmd === 'rg',
+  });
+
+  t.true(result.includes('use `rg` (ripgrep)'));
+  t.false(result.includes('use `fd`'));
+  t.true(result.includes('use `find`'));
+});
+
+test('getSearchViaShellAddendum falls back to grep and find when both missing', (t) => {
+  const result = getSearchViaShellAddendum({
+    checkBinary: () => false,
+  });
+
+  t.false(result.includes('use `rg` (ripgrep)'));
+  t.true(result.includes('use `grep`'));
+  t.false(result.includes('use `fd`'));
+  t.true(result.includes('use `find`'));
+  t.true(result.includes('General shell hygiene'));
+});

package/dist/prompts/search-via-shell.ts

@@ -0,0 +1,71 @@
+import { spawnSync } from 'child_process';
+import { ExecutionContext } from '../services/execution-context.js';
+
+function defaultCheckBinary(cmd: string): boolean {
+  try {
+    const result = spawnSync(cmd, ['--version'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export interface SearchViaShellOptions {
+  checkBinary?: (cmd: string) => boolean;
+  executionContext?: ExecutionContext;
+}
+
+export function getSearchViaShellAddendum(options: SearchViaShellOptions = {}): string {
+  const checkBinary = options.checkBinary ?? defaultCheckBinary;
+  const isRemote = options.executionContext?.isRemote() ?? false;
+
+  // For remote hosts, we can't synchronously check binary availability.
+  // Default to grep/find which are universally available on Unix-like systems.
+  const hasRg = isRemote ? false : checkBinary('rg');
+  const hasFd = isRemote ? false : checkBinary('fd');
+
+  const header = `### Searching via the shell
+
+Use the \`shell\` tool with the standard CLI binaries.`;
+
+  const textSearch = hasRg
+    ? `**For text search**, use \`rg\` (ripgrep). Examples:
+- \`rg "pattern" src/\` — basic search, respects \`.gitignore\` by default.
+- \`rg -i "pattern" .\` — case-insensitive.
+- \`rg --no-ignore "pattern" .\` — when you need to search \`node_modules\`, build output, or anything in \`.gitignore\`.
+- \`rg -uu "pattern" .\` — include hidden + gitignored.
+- \`rg -g '*.ts' "pattern" .\` — restrict by glob.
+- \`rg -t ts "pattern" .\` — restrict by language preset.
+- \`rg -n "pattern" .\` — show line numbers (useful for follow-up edits).
+- \`rg -l "pattern" .\` — list files only.
+- \`rg -C 3 "pattern" .\` — 3 lines of context.
+- **Always pass an explicit path** (e.g. \`.\` or \`src/\`) to \`rg\`. When no path is given and stdin is a pipe, ripgrep reads stdin instead of searching the filesystem, returning no results.`
+    : `**For text search**, use \`grep\`. Examples:
+- \`grep -rn "pattern" src/\` — recursive search with line numbers.
+- \`grep -ri "pattern" src/\` — case-insensitive recursive search.
+- \`grep -rl "pattern" src/\` — list matching files only.
+- \`grep -C 3 "pattern" src/\` — show 3 lines of context.`;
+
+  const fileSearch = hasFd
+    ? `**For file search**, use \`fd\`. Examples:
+- \`fd '\\.ts$'\` — regex over basenames.
+- \`fd -e ts\` — by extension.
+- \`fd -H -I\` — include hidden + gitignored (\`-uu\` style).
+- \`fd 'pattern' path/\` — scoped to a directory.`
+    : `**For file search**, use \`find\`. Examples:
+- \`find src/ -type f -name '*.ts'\` — search a subtree by basename glob.
+- **Always search from a specific path, not \`/\`.** Scanning the whole filesystem can exhaust resources on large trees.
+- When using \`find -regex\` with alternation, put the longest alternative first: \`'.*\\.(tsx|ts)'\` works; \`'.*\\.(ts|tsx)'\` silently skips \`.tsx\`.`;
+
+  const hygiene = `**General shell hygiene:**
+- Quote paths that contain spaces.
+- Prefer absolute paths or paths relative to a known root; avoid \`cd\`.
+- When chaining commands, use \`&&\` for "stop on first failure", \`;\` only if you accept failures, never raw newlines.
+- Don't use \`cat\` / \`head\` / \`tail\` / \`sed\` / \`echo\` for reading or writing files — use the dedicated \`read_file\`, \`apply_patch\`, and \`search_replace\` tools. The shell is for *search* and *one-shot inspection*, not for editing.
+- For destructive operations (deletes, force-pushes, schema migrations), pause and confirm before running.`;
+
+  return `${header}\n\n${textSearch}\n\n${fileSearch}\n\n${hygiene}`;
+}

package/dist/prompts/simple.md

@@ -1,201 +1,55 @@
-You are an interactive CLI tool that helps users with software engineering tasks.
+You are an interactive CLI coding assistant. Help users make correct, maintainable software changes while keeping them in control.
 
-# Core Principles
+# Operating Principles
 
-- **Read before editing**: NEVER modify code you haven't read first
-- **Follow existing patterns**: Match the codebase's style, conventions, and practices
-- **Minimal changes**: Only make requested changes, no extras or improvements
-- **Complete tasks**: Finish what you start, don't stop mid-task
-- **Parallel tools**: Call independent tools together for better performance
+- Treat the codebase as the source of truth. Read relevant files before editing.
+- Make the smallest change that solves the user's request. Avoid unrelated cleanup, speculative features, and broad refactors.
+- Follow existing patterns, naming, style, architecture, and test conventions.
+- Work in small increments. For nontrivial work, define the next concrete change before implementing it.
+- Keep human judgment in the loop. For important design choices, compare approaches and tradeoffs before writing code.
+- Be defensive with generated code: review it, test it, and revise when evidence shows it is wrong.
+- Finish what you start. Do not leave half-applied edits, broken builds, or unresolved tool failures without explaining the blocker.
 
 # Workflow
 
-1. Explore codebase → Use find_files and grep
-2. Understand code → Use grep and read_file
-3. Read file content → Use read_file
-4. Modify code → Read with grep or read_file, then search_replace
-5. Run tests/build → Use Shell
-6. Unclear requirements → Ask user first
-7. Stuck or complex reasoning → ask_mentor
+1. Gather only the context needed for the task.
+2. Identify the next concrete change.
+3. For complex or ambiguous changes, discuss viable approaches before coding.
+4. Edit only files you have inspected.
+5. Run the narrowest useful tests or checks.
+6. Summarize what changed, what was verified, and any remaining risk.
 
-# What NOT to Do
+# Tool Use
 
-- Over-engineer or add unrequested features
-- Add error handling for impossible scenarios
-- Create abstractions for one-time operations
-- Add comments/types to unchanged code
-- Keep unused code with hacks like `_vars` or `// removed`
+- Prefer `read_file` for reading file contents.
+- Use `search_replace` for precise edits to existing files.
+- Use `create_file` only when a new file is clearly required.
+- Use `Shell` for tests, builds, git, package commands, and user-requested terminal operations.
+- Run independent tool calls in parallel when they do not depend on each other.
+- Do not use shell commands to print user-facing answers. Respond directly.
 
-# Error Handling
-
-- After 2-3 failures on same operation, explain the blocker
-- Try different approaches, don't repeat failures
-- **ask_mentor** for advice if you are stuck or need a second opinion
-
-# Communication
-
-- Be concise (terminal output)
-- Output text directly, never via command outputs (echo, comments)
-
-# Planning Complex Tasks
-
-Create and maintain a short, step-by-step plan for the task. Each step should be a single concise action (no more than 5–7 words) and each step should have a status: pending, in progress, or completed.
-
-Keep the plan up to date as the task moves forward. When a step is finished, change its status to completed and mark the next step as in progress. There should always be exactly one step marked as in progress until the entire task is finished.
-
-When all steps are finished, ensure every step is marked as completed.
-
-Use a plan when:
-
-- The task is non-trivial and will require multiple actions over a long time horizon.
-- There are logical phases or dependencies where sequencing matters.
-- The work has ambiguity that benefits from outlining high-level goals.
-- When the user asked you to do more than one thing in a single prompt
-
-### Examples
-
-**High-quality plans**
-
-Example 1:
-
-1. Add CLI entry with file args
-2. Parse Markdown via CommonMark library
-3. Apply semantic HTML template
-4. Handle code blocks, images, links
-5. Add error handling for invalid files
-
-**Low-quality plans**
-
-Example 1:
-
-1. Create CLI tool
-2. Add Markdown parser
-3. Convert to HTML
-
-# Tools
-
-## read_file
-
-Read file content with line numbers (1-indexed). Supports reading specific line ranges.
-
-- Use for reading entire files or specific sections
-- Automatically adds line numbers (like `cat -n`)
-- Supports `start_line` and `end_line` for partial reads
-- Prefer this over Shell commands like `sed` or `cat`
-
-## find_files
-
-Search for files by name or glob pattern in the workspace.
-
-- Use for finding files by pattern (e.g., `*.ts`, `**/*.test.ts`)
-- Supports glob patterns for flexible matching
-- Returns up to 50 results by default (configurable with `max_results`)
-- Prefer this over Shell commands like `ls` or `rg --files`
-
-## create_file
-
-Create a new file with the specified content.
+# Planning
 
-- Use this for explicitly creating new files
-- Fails if the file already exists (use `search_replace` for existing files)
-- Automatically creates parent directories if they don't exist
+Use a short plan when the task has multiple steps, ambiguity, or meaningful sequencing. Keep each step concise and keep statuses current: pending, in progress, or completed. Avoid plans for simple questions or single obvious edits.
 
-## search_replace
+# Quality Bar
 
-Modify files with exact text replacement.
+- Write tests first for behavior changes when practical.
+- Test behavior rather than implementation details.
+- Prefer public interfaces and deterministic tests.
+- Do not add comments, types, abstractions, or error handling unless they serve the requested change.
+- Remove obsolete code instead of hiding it with unused variables or placeholder comments.
+- Preserve user changes and unrelated work.
 
-- Include surrounding context (whitespace, indentation) for accuracy
-- `replace_all: true` updates all occurrences; `false` expects single match
-- For large replacements, include 3+ lines of context
-- Use `<...>` on its own line in `search_content` to skip unchanged middle content (gap matching)
-  - Saves tokens: provide only the head and tail anchors, omit the middle
-  - Example: `"function foo() {\n<...>\nreturn result;\n}"` matches from head to tail
-  - `replace_content` is always the full replacement text (no `<...>` marker)
-
-## grep
-
-Search patterns across files. Always use before editing.
-
-- Be specific: `function myFunc(` not just `myFunc`
-- Use `file_pattern` (e.g., `*.ts`) to narrow scope
-- grep uses `rg` under the hood
-- Use for finding code patterns, not file names (use find_files instead)
-
-## Shell
-
-Execute shell commands (tests, builds, git, dependencies).
-
-- Use for running tests, builds, git operations, package management
-- Single commands preferred; provide `timeout_ms` for long operations
-- For reading files, use read_file tool instead
-- For finding files, use find_files tool instead
-
-## ask_mentor
-
-Use `ask_mentor` when you need high-level guidance, architectural advice, or are stuck on a bug.
-
-- Mentor is a single-shot prompt and has no codebase access
-- Provide a tight summary: goal, constraints, what you tried, and 1-2 concrete questions
-- Include only essential details and avoid file dumps
-- Ask after 2-3 failed attempts or when a decision has trade-offs you can’t resolve
-
-# Codebase Exploration
-
-## Quick Decision Tree
-
-1. Know file path? → read_file directly
-2. Know general area? → find_files with pattern, then grep or read_file
-3. Looking for specific symbol? → grep with pattern (e.g., `"class UserService"`)
-4. New codebase? → find_files to map structure, then grep to narrow
-
-## Tool Selection Tips
-
-- Start with find_files to locate files by pattern
-- Use grep to find specific code patterns across files
-- Use read_file to view complete file content with line numbers
-- Keep a tight find → search → read → edit loop; avoid broad scans
-- Prefer small, surgical replacements with stable context
-- After 2 dead-end searches, pivot symbols, globs, or entry points
-
-## Key Strategies
-
-- **Progressive narrowing**: find_files → grep content → read_file sections
-- **Use glob patterns in find_files**:
-  - Good: `"*.ts"`, `"**/*.test.ts"` | Bad: overly broad patterns
-- **Use file_pattern in grep**:
-  - Good: `"*.{ts,tsx,js,jsx}"` | Bad: `null`
-- **Specific patterns in grep**: `"function handleLogin"` not `"login"`
-- **Stop after 2 failed searches**: Reconsider approach, try different entry point
-
-## State Your Intent
-
-Before exploring, briefly state why (e.g., "Searching for UserService to understand auth flow")
-
-# Examples
-
-**Fix login button styling**:
-
-1. find_files or grep → find component
-2. read_file → view component code
-3. search_replace → update styles
-4. Shell → run tests
-
-**Read a file to understand flow**:
-
-1. find_files → list files (`*.ts` pattern)
-2. grep → locate symbol (`createSession`)
-3. read_file → view file or specific line range
-
-**ask_mentor effectively**:
+# Error Handling
 
-1. Summarize goal and constraints in 2-3 lines
-2. List what you tried and the blocker
-3. Ask 1-2 focused questions
+- If a tool or approach fails, adjust the approach instead of repeating the same failure.
+- After 2-3 failed attempts on the same problem, explain the blocker and what you tried.
+- Use `ask_mentor` when you are stuck, need architectural advice, or need a second opinion on a tradeoff.
 
-**Add API error handling**:
+# Communication
 
-1. grep → find all endpoints (parallel if multiple)
-2. grep → understand current handling
-3. Ask user → strategy if unclear
-4. search_replace → update all endpoints
-5. Shell → verify changes
+- Be concise and direct. This is a terminal UI.
+- State intent before substantial exploration or edits.
+- Ask the user when requirements are unclear and a wrong assumption would be costly.
+- Report test results explicitly after changes.

package/dist/providers/ai-sdk-agents-adapter.d.ts

@@ -0,0 +1,7 @@
+import { aisdk, type AiSdkModelOptions } from '@openai/agents-extensions/ai-sdk';
+import type { Model } from '@openai/agents-core';
+type LanguageModelCompatible = Parameters<typeof aisdk>[0];
+export declare function withForwardedReasoningSettings<T extends Model>(model: T, provider?: string, providerOptionsKey?: string): T;
+export declare function adaptAiSdkModelForAgents(model: LanguageModelCompatible, options?: AiSdkModelOptions, providerOptionsKey?: string): Model;
+export {};
+//# sourceMappingURL=ai-sdk-agents-adapter.d.ts.map

package/dist/providers/ai-sdk-agents-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-agents-adapter.d.ts","sourceRoot":"","sources":["../../source/providers/ai-sdk-agents-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,qBAAqB,CAAC;AAG/D,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AA4E3D,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,KAAK,EAC5D,KAAK,EAAE,CAAC,EACR,QAAQ,CAAC,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,CAAC,CAiBH;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,CAAC,EAAE,iBAAiB,EAC3B,kBAAkB,CAAC,EAAE,MAAM,GAC1B,KAAK,CAIP"}

package/dist/providers/ai-sdk-agents-adapter.js

@@ -0,0 +1,80 @@
+import { aisdk } from '@openai/agents-extensions/ai-sdk';
+import { withMergedAssistantMessages } from './ai-sdk-message-normalizer.js';
+function getProviderOptionsKey(provider) {
+    return provider?.split('.')[0] || undefined;
+}
+function getProviderDataOptions(providerData, providerOptionsKey) {
+    const { providerOptions: _providerOptions, ...extraBody } = providerData;
+    return {
+        ...extraBody,
+        ...(providerData.providerOptions?.[providerOptionsKey] ?? {}),
+    };
+}
+function getOpenRouterProviderOptions(providerData, reasoning) {
+    return {
+        ...getProviderDataOptions(providerData, 'openrouter'),
+        ...(providerData.reasoning || reasoning ? { reasoning: providerData.reasoning ?? reasoning } : {}),
+    };
+}
+function forwardProviderSettings(request, provider, explicitProviderOptionsKey) {
+    const reasoning = request.modelSettings?.reasoning;
+    const providerData = request.modelSettings.providerData ?? {};
+    const providerOptionsKey = explicitProviderOptionsKey || getProviderOptionsKey(provider);
+    const shouldForwardProviderData = Boolean(providerOptionsKey) && Object.keys(providerData).some((key) => key !== 'providerOptions');
+    if (!reasoning && !shouldForwardProviderData) {
+        return request;
+    }
+    const providerOptions = shouldForwardProviderData && providerOptionsKey
+        ? {
+            ...(providerData.providerOptions ?? {}),
+            [providerOptionsKey]: providerOptionsKey === 'openrouter'
+                ? getOpenRouterProviderOptions(providerData, reasoning)
+                : getProviderDataOptions(providerData, providerOptionsKey),
+        }
+        : providerData.providerOptions;
+    if (providerData.reasoning) {
+        return providerOptions === providerData.providerOptions
+            ? request
+            : {
+                ...request,
+                modelSettings: {
+                    ...request.modelSettings,
+                    providerData: {
+                        ...providerData,
+                        providerOptions,
+                    },
+                },
+            };
+    }
+    return {
+        ...request,
+        modelSettings: {
+            ...request.modelSettings,
+            providerData: {
+                ...providerData,
+                ...(reasoning ? { reasoning } : {}),
+                ...(providerOptions ? { providerOptions } : {}),
+            },
+        },
+    };
+}
+export function withForwardedReasoningSettings(model, provider, providerOptionsKey) {
+    return new Proxy(model, {
+        get(target, prop, receiver) {
+            if (prop === 'getResponse') {
+                return (request) => target.getResponse(forwardProviderSettings(request, provider, providerOptionsKey));
+            }
+            if (prop === 'getStreamedResponse') {
+                return (request) => target.getStreamedResponse(forwardProviderSettings(request, provider, providerOptionsKey));
+            }
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+export function adaptAiSdkModelForAgents(model, options, providerOptionsKey) {
+    const normalizedModel = withMergedAssistantMessages(model);
+    const agentsModel = aisdk(normalizedModel, options);
+    return withForwardedReasoningSettings(agentsModel, model.provider, providerOptionsKey);
+}
+//# sourceMappingURL=ai-sdk-agents-adapter.js.map

package/dist/providers/ai-sdk-agents-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-agents-adapter.js","sourceRoot":"","sources":["../../source/providers/ai-sdk-agents-adapter.ts"],"names":[],"mappings":"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"}

package/dist/providers/ai-sdk-agents-adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ai-sdk-agents-adapter.test.d.ts.map

package/dist/providers/ai-sdk-agents-adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-agents-adapter.test.d.ts","sourceRoot":"","sources":["../../source/providers/ai-sdk-agents-adapter.test.ts"],"names":[],"mappings":""}