v3.5.0

.smartconfig.json

@@ -0,0 +1,32 @@
+{
+  "@git.zone/cli": {
+    "projectType": "npm",
+    "module": {
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
+      "gitrepo": "smartagent",
+      "description": "Agentic loop for ai-sdk (Vercel AI SDK). Wraps streamText with stopWhen for parallel multi-step tool execution. Built on @push.rocks/smartai.",
+      "npmPackagename": "@push.rocks/smartagent",
+      "license": "MIT",
+      "projectDomain": "push.rocks"
+    },
+    "release": {
+      "targets": {
+        "npm": {
+          "registries": [
+            "https://verdaccio.lossless.digital",
+            "https://registry.npmjs.org"
+          ],
+          "accessLevel": "public"
+        }
+      }
+    },
+    "schemaVersion": 2
+  },
+  "@git.zone/tsdoc": {
+    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
+  }
+}

changelog.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## Pending
+
+
+
+
+
+
+## 2026-05-15 - 3.5.0
+
+### Features
+
+- add reusable execution contexts for shell, filesystem, and browser tools (tools)
+  - introduces shared tool execution context interfaces plus a local Node.js context implementation
+  - adds createShellTools, createFilesystemTools, and createBrowserTools for host-provided transports with permission hooks
+  - re-exports the new tool factories and context types from the main package entrypoint while keeping compatibility wrappers
+
+## 2026-05-14 - 3.4.0
+
+### Features
+
+- add streamed reasoning summary callbacks to runAgent (agent)
+  - Introduces onReasoningStart, onReasoningDelta, and onReasoningEnd callbacks in the agent options interface
+  - Handles reasoning-start, reasoning-delta, and reasoning-end stream chunks while accumulating reasoning text by id
+  - Ensures incomplete reasoning streams are finalized after the response completes
+  - Adds tests for reasoning summary streaming and updates the README API documentation
+
+## 2026-05-14 - 3.3.0
+
+### Features
+
+- upgrade @push.rocks/smartai to ^4.0.0 (deps)
+  - Updates the core smartai dependency from ^2.3.0 to ^4.0.0.
+  - Refreshes README hints to document the new smartai version.
+
+## 2026-05-14 - 3.2.0
+
+### Features
+
+- add prompt caching options and cache token usage reporting (agent)
+  - adds sessionId and cache run options to configure provider-specific prompt caching defaults
+  - applies OpenAI cache provider options and Anthropic cache breakpoints automatically, with support to disable defaults
+  - extends usage reporting to include cacheReadTokens and cacheWriteTokens
+  - exports cache-related types and helpers and updates tests and README to cover the new behavior
+
+## 2026-05-11 - 3.1.1
+
+### Fixes
+
+- update release configuration to schema version 2 with npm target settings (smartconfig)
+  - migrates release settings from a flat registries/accessLevel structure to a nested targets.npm configuration
+  - adds schemaVersion 2 to align the smartconfig format with the updated release schema
+
+## 2026-05-07 - 3.1.0 - feat(agent)
+add provider options passthrough, tool call records, and completion validation retries
+
+- forward provider-specific options to the underlying streamText call
+- return structured tool call records with inputs, outputs, and errors in agent results
+- support validateCompletion with reprompting and configurable validation retry limits
+- export ProviderOptions and tool call record types for consumers
+- update tests and documentation for the new agent run options and result fields
+
+## 2026-04-30 - 3.0.3 - fix(build)
+tighten TypeScript configuration and update dependencies for zod v4 compatibility
+
+- enable stricter TypeScript checks with noImplicitAny and explicit node types
+- update HTTP tool schemas to use explicit z.record key and value types for newer zod versions
+- adjust test typing for calculator operations and refresh build-related dependencies and package metadata
+
+## 2026-03-06 - 3.0.2 - fix(agent)
+use output parameter when invoking onToolResult instead of toolCall.result
+
+- Replace (toolCall as any).result with the explicit output parameter when calling options.onToolResult.
+- Prevents undefined/misread results by aligning the callback with the tool runner's output signature.
+
 ## 2026-03-06 - 3.0.1 - fix(readme)
 adjust ASCII art in README to fix box widths and spacing in agent diagram
 
@@ -166,4 +240,4 @@ Bump version to 1.0.2 (patch release)
 Initial commit: project scaffold and first release.
 
 - Repository initialized with initial project structure and baseline files.
-- Version set to 1.0.1.
+- Version set to 1.0.1.

license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartagent",
-  "version": "3.0.1",
+  "version": "3.5.0",
   "private": false,
   "description": "Agentic loop for ai-sdk (Vercel AI SDK). Wraps streamText with stopWhen for parallel multi-step tool execution. Built on @push.rocks/smartai.",
   "main": "dist_ts/index.js",
@@ -24,26 +24,27 @@
   "license": "MIT",
   "scripts": {
     "test": "(tstest test/ --verbose --logfile --timeout 120)",
-    "build": "(tsbuild tsfolders --allowimplicitany)",
+    "build": "(tsbuild tsfolders)",
     "buildDocs": "(tsdoc)"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.3.0",
-    "@git.zone/tsbundle": "^2.9.1",
-    "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^3.3.0",
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tstest": "^3.6.3",
     "@push.rocks/qenv": "^6.1.3",
-    "@types/node": "^25.3.5"
+    "@types/json-schema": "^7.0.15",
+    "@types/lodash.clonedeep": "^4.5.9",
+    "@types/node": "^25.6.0"
   },
   "dependencies": {
-    "@push.rocks/smartai": "^2.0.0",
-    "@push.rocks/smartfs": "^1.4.0",
+    "@push.rocks/smartai": "^4.0.0",
+    "@push.rocks/smartfs": "^1.5.1",
     "@push.rocks/smartrequest": "^5.0.1",
-    "@push.rocks/smartshell": "^3.3.7",
-    "ai": "^6.0.0",
-    "zod": "^3.25.0"
+    "@push.rocks/smartshell": "^3.3.8",
+    "ai": "^6.0.182",
+    "zod": "^4.4.1"
   },
-  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34",
+  "packageManager": "pnpm@10.28.2",
   "repository": {
     "type": "git",
     "url": "https://code.foss.global/push.rocks/smartagent.git"
@@ -59,10 +60,9 @@
     "dist/**/*",
     "dist_*/**/*",
     "assets/**/*",
+    ".smartconfig.json",
+    "license",
     "npmextra.json",
     "readme.md"
-  ],
-  "pnpm": {
-    "overrides": {}
-  }
+  ]
 }

readme.hints.md

@@ -24,7 +24,7 @@ Each exports a factory returning a flat `ToolSet` (Record<string, Tool>):
 4. **jsonTool()** → `json_validate`, `json_transform`
 
 ## Key Dependencies
-- `@push.rocks/smartai` ^2.0.0 — provider registry, `getModel()`, re-exports `tool`, `jsonSchema`
+- `@push.rocks/smartai` ^4.0.0 — provider registry, `getModel()`, re-exports `tool`, `jsonSchema`
 - `ai` ^6.0.0 — Vercel AI SDK v6 (`streamText`, `stepCountIs`, `ModelMessage`, `ToolSet`)
 - `zod` ^3.25.0 — tool input schema definitions
 - `@push.rocks/smartfs`, `smartshell`, `smartrequest` — tool implementations

readme.md

@@ -49,7 +49,7 @@ const result = await runAgent({
 
 console.log(result.text);    // "7 + 35 = 42"
 console.log(result.steps);   // number of agentic steps taken
-console.log(result.usage);   // { promptTokens, completionTokens, totalTokens }
+console.log(result.usage);   // { inputTokens, outputTokens, totalTokens, cacheReadTokens, cacheWriteTokens }
 ```
 
 ## Architecture
@@ -76,7 +76,7 @@ console.log(result.usage);   // { promptTokens, completionTokens, totalTokens }
 - ⚡ **Parallel tool execution** — multiple tool calls in a single step are executed concurrently
 - 🔧 **Auto-retry with backoff** — handles 429/529/503 errors with header-aware retry delays
 - 🩹 **Tool call repair** — case-insensitive name matching + invalid tool sink prevents crashes
-- 📊 **Token streaming** — `onToken` and `onToolCall` callbacks for real-time progress
+- 📊 **Token and reasoning streaming** — `onToken`, `onReasoning*`, and `onToolCall` callbacks for real-time progress
 - 💥 **Context overflow handling** — detects overflow and invokes your `onContextOverflow` callback
 
 ## Core API
@@ -91,11 +91,20 @@ The single entry point. Options:
 | `prompt` | `string` | *required* | The user's task/question |
 | `system` | `string` | `undefined` | System prompt |
 | `tools` | `ToolSet` | `{}` | Tools the agent can call |
+| `providerOptions` | `ProviderOptions` | `undefined` | Provider-specific AI SDK request options passed through to `streamText()` |
+| `sessionId` | `string` | `undefined` | Stable session id used as provider prompt-cache affinity key where supported |
+| `cache` | `'auto' \| false \| IAgentCacheOptions` | `'auto'` | Prompt-cache policy. Set `false` to disable SmartAgent cache defaults |
 | `maxSteps` | `number` | `20` | Max agentic steps before stopping |
 | `messages` | `ModelMessage[]` | `[]` | Conversation history (for multi-turn) |
 | `maxRetries` | `number` | `5` | Max retries on rate-limit/server errors |
 | `onToken` | `(delta: string) => void` | — | Streaming token callback |
+| `onReasoningStart` | `(id: string) => void` | — | Called when a reasoning summary starts |
+| `onReasoningDelta` | `(id: string, delta: string) => void` | — | Called for streamed reasoning summary text |
+| `onReasoningEnd` | `(id: string, text: string) => void` | — | Called when a reasoning summary completes |
 | `onToolCall` | `(name: string) => void` | — | Called when a tool is invoked |
+| `onToolResult` | `(name: string, result: unknown) => void` | — | Called when a tool finishes |
+| `validateCompletion` | `(result) => string \| void` | — | Return a string to reject and reprompt an incomplete run |
+| `maxValidationRetries` | `number` | `0` | Number of validation-triggered reprompts allowed |
 | `onContextOverflow` | `(messages) => messages` | — | Handle context overflow (e.g., compact messages) |
 
 ### `IAgentRunResult`
@@ -107,13 +116,101 @@ interface IAgentRunResult {
   steps: number;             // Number of agentic steps taken
   messages: ModelMessage[];  // Full conversation for multi-turn
   usage: {
-    promptTokens: number;
-    completionTokens: number;
+    inputTokens: number;
+    outputTokens: number;
     totalTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
   };
+  toolCalls: Array<{
+    toolName: string;
+    input: unknown;
+    output?: unknown;
+    error?: string;
+  }>;
 }
 ```
 
+### OpenAI Provider Options
+
+Use `providerOptions` for provider-specific request settings such as GPT reasoning effort. SmartAgent merges cache defaults first, then applies your `providerOptions` so explicit caller options win.
+
+```typescript
+import { getModelSetup } from '@push.rocks/smartai';
+import { runAgent } from '@push.rocks/smartagent';
+
+const setup = getModelSetup({
+  provider: 'openai',
+  model: 'gpt-5.5',
+  apiKey: process.env.OPENAI_API_KEY,
+  providerOptions: {
+    openai: {
+      reasoningEffort: 'xhigh',
+    },
+  },
+});
+
+const result = await runAgent({
+  model: setup.model,
+  system: 'You handle financial documents carefully.',
+  prompt: 'Process this inbox document.',
+  tools,
+  maxSteps: 20,
+  providerOptions: setup.providerOptions,
+});
+
+const saved = result.toolCalls.some((call) =>
+  call.toolName === 'saveVoucher' || call.toolName === 'saveBankStatement',
+);
+```
+
+### Prompt Caching
+
+SmartAgent enables prompt-cache defaults by default:
+
+- Anthropic-compatible models get cache breakpoints on the first two system messages and the two most recent non-system messages.
+- OpenAI models get `store: false` by default and, when `sessionId` is provided, `promptCacheKey: sessionId` with `promptCacheRetention: 'in_memory'`.
+- Longer retention is opt-in. Use `cache: { retention: '24h' }` for OpenAI or `cache: { retention: '1h' }` for Anthropic.
+- Set `cache: false` to disable these defaults for a run.
+
+```typescript
+const result = await runAgent({
+  model,
+  sessionId: 'stable-session-id',
+  prompt: 'Continue the task.',
+  tools,
+});
+
+const noCache = await runAgent({
+  model,
+  prompt: 'One-off request.',
+  cache: false,
+});
+```
+
+### Completion Validation
+
+Use `validateCompletion` when a workflow must not finish unless a required side-effect happened. Return `void` to accept the run, or return a string to append that string as a new user message and continue. If retries are exhausted, `runAgent()` throws.
+
+```typescript
+const result = await runAgent({
+  model,
+  prompt: 'Process this inbox document.',
+  tools,
+  maxSteps: 20,
+  maxValidationRetries: 1,
+  validateCompletion: (result) => {
+    const saved = result.toolCalls.some((call) =>
+      call.toolName === 'saveVoucher' || call.toolName === 'saveBankStatement',
+    );
+
+    if (!saved) {
+      return 'You must call saveVoucher or saveBankStatement before finalizing.';
+    }
+  },
+});
+```
+
 ## Defining Tools 🛠️
 
 Tools use Vercel AI SDK's `tool()` helper with Zod schemas:
@@ -145,6 +242,36 @@ await runAgent({
 });
 ```
 
+## Reusable Tool Contexts
+
+SmartAgent can build tools once and execute them through a host-provided context. The same shell, filesystem, and browser tool schemas can target local Node.js, SSH, MCP, or another transport supplied by the host app.
+
+```typescript
+import { createFilesystemTools, createShellTools, type IToolExecutionContext } from '@push.rocks/smartagent';
+
+const context: IToolExecutionContext = {
+  cwd: '/workspace/project',
+  requestPermission: async (request) => {
+    // Host app decides whether to allow writes, commands, browser actions, etc.
+  },
+  shell: {
+    run: async (command, options) => sshRun(command, options),
+  },
+  fs: {
+    readFile: async (path, options) => sshRead(path, options),
+    writeFile: async (path, content) => sshWrite(path, content),
+    listDirectory: async (path, options) => sshList(path, options),
+  },
+};
+
+const tools = {
+  ...createShellTools(context),
+  ...createFilesystemTools(context, { includeDelete: false }),
+};
+```
+
+For local execution, use `createLocalToolExecutionContext()` or the compatibility wrappers `shellTool()` and `filesystemTool()`.
+
 ## ToolRegistry
 
 A lightweight helper for collecting tools:

test/test.agent-e2e.ts

@@ -66,6 +66,7 @@ tap.test('agent should call a single tool and incorporate the result', async ()
 
 tap.test('agent should pick the right tool from multiple options', async () => {
   const callLog: string[] = [];
+  type TCalculatorOperation = 'add' | 'subtract' | 'multiply' | 'divide';
 
   const result = await runAgent({
     model,
@@ -79,7 +80,7 @@ tap.test('agent should pick the right tool from multiple options', async () => {
           a: z.number(),
           b: z.number(),
         }),
-        execute: async ({ operation, a, b }: { operation: string; a: number; b: number }) => {
+        execute: async ({ operation, a, b }: { operation: TCalculatorOperation; a: number; b: number }) => {
           callLog.push(`calculator:${operation}(${a}, ${b})`);
           switch (operation) {
             case 'add': return String(a + b);

test/test.ts

@@ -1,8 +1,75 @@
 import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { MockLanguageModelV3, convertArrayToReadableStream } from 'ai/test';
 import * as smartagent from '../ts/index.js';
-import { filesystemTool, shellTool, httpTool, jsonTool, truncateOutput } from '../ts_tools/index.js';
+import { createBrowserTools, createFilesystemTools, createShellTools, filesystemTool, shellTool, httpTool, jsonTool, truncateOutput } from '../ts_tools/index.js';
 import { compactMessages } from '../ts_compaction/index.js';
 
+const createUsage = (inputTokens: number, outputTokens: number) => ({
+  inputTokens: {
+    total: inputTokens,
+    noCache: inputTokens,
+    cacheRead: 0,
+    cacheWrite: 0,
+  },
+  outputTokens: {
+    total: outputTokens,
+    text: outputTokens,
+    reasoning: 0,
+  },
+});
+
+const createTextStreamResult = (text: string) => ({
+  stream: convertArrayToReadableStream([
+    { type: 'stream-start', warnings: [] },
+    { type: 'response-metadata', id: 'response-1', timestamp: new Date(0), modelId: 'mock-model' },
+    { type: 'text-start', id: 'text-1' },
+    { type: 'text-delta', id: 'text-1', delta: text },
+    { type: 'text-end', id: 'text-1' },
+    {
+      type: 'finish',
+      finishReason: { unified: 'stop', raw: 'stop' },
+      usage: createUsage(1, 1),
+    },
+  ] as any[]),
+});
+
+const createReasoningStreamResult = (reasoning: string, text: string) => ({
+  stream: convertArrayToReadableStream([
+    { type: 'stream-start', warnings: [] },
+    { type: 'response-metadata', id: 'response-1', timestamp: new Date(0), modelId: 'mock-model' },
+    { type: 'reasoning-start', id: 'reasoning-1' },
+    { type: 'reasoning-delta', id: 'reasoning-1', delta: reasoning.slice(0, 7) },
+    { type: 'reasoning-delta', id: 'reasoning-1', delta: reasoning.slice(7) },
+    { type: 'reasoning-end', id: 'reasoning-1' },
+    { type: 'text-start', id: 'text-1' },
+    { type: 'text-delta', id: 'text-1', delta: text },
+    { type: 'text-end', id: 'text-1' },
+    {
+      type: 'finish',
+      finishReason: { unified: 'stop', raw: 'stop' },
+      usage: createUsage(2, 2),
+    },
+  ] as any[]),
+});
+
+const createToolCallStreamResult = (toolName: string, input: unknown) => ({
+  stream: convertArrayToReadableStream([
+    { type: 'stream-start', warnings: [] },
+    { type: 'response-metadata', id: 'response-1', timestamp: new Date(0), modelId: 'mock-model' },
+    {
+      type: 'tool-call',
+      toolCallId: 'tool-call-1',
+      toolName,
+      input: JSON.stringify(input),
+    },
+    {
+      type: 'finish',
+      finishReason: { unified: 'tool-calls', raw: 'tool-calls' },
+      usage: createUsage(2, 1),
+    },
+  ] as any[]),
+});
+
 // ============================================================
 // Core exports
 // ============================================================
@@ -35,6 +102,202 @@ tap.test('should re-export stepCountIs', async () => {
   expect(smartagent.stepCountIs).toBeTypeOf('function');
 });
 
+tap.test('runAgent should forward providerOptions to streamText', async () => {
+  const model = new MockLanguageModelV3({
+    doStream: async () => createTextStreamResult('ok') as any,
+  });
+
+  const providerOptions = {
+    openai: {
+      reasoningEffort: 'xhigh',
+    },
+  } as const;
+
+  const result = await smartagent.runAgent({
+    model,
+    prompt: 'hello',
+    providerOptions,
+  });
+
+  expect(result.text).toEqual('ok');
+  expect((model.doStreamCalls[0].providerOptions as any).openai.reasoningEffort).toEqual('xhigh');
+});
+
+tap.test('runAgent should add OpenAI cache defaults when sessionId is provided', async () => {
+  const model = new MockLanguageModelV3({
+    provider: 'openai',
+    modelId: 'gpt-5',
+    doStream: async () => createTextStreamResult('ok') as any,
+  });
+
+  const result = await smartagent.runAgent({
+    model,
+    prompt: 'hello',
+    sessionId: 'session-123',
+    providerOptions: {
+      openai: {
+        reasoningEffort: 'high',
+      },
+    } as any,
+  });
+
+  const openaiOptions = (model.doStreamCalls[0].providerOptions as any).openai;
+
+  expect(result.text).toEqual('ok');
+  expect(openaiOptions.store).toEqual(false);
+  expect(openaiOptions.promptCacheKey).toEqual('session-123');
+  expect(openaiOptions.promptCacheRetention).toEqual('in_memory');
+  expect(openaiOptions.reasoningEffort).toEqual('high');
+});
+
+tap.test('runAgent should stream reasoning summary callbacks', async () => {
+  const reasoningEvents: string[] = [];
+  const tokenDeltas: string[] = [];
+  const model = new MockLanguageModelV3({
+    doStream: async () => createReasoningStreamResult('thinking through it', 'done') as any,
+  });
+
+  const result = await smartagent.runAgent({
+    model,
+    prompt: 'hello',
+    onToken: (delta) => tokenDeltas.push(delta),
+    onReasoningStart: (id) => reasoningEvents.push('start:' + id),
+    onReasoningDelta: (id, delta) => reasoningEvents.push('delta:' + id + ':' + delta),
+    onReasoningEnd: (id, text) => reasoningEvents.push('end:' + id + ':' + text),
+  });
+
+  expect(result.text).toEqual('done');
+  expect(tokenDeltas.join('')).toEqual('done');
+  expect(reasoningEvents).toEqual([
+    'start:reasoning-1',
+    'delta:reasoning-1:thinkin',
+    'delta:reasoning-1:g through it',
+    'end:reasoning-1:thinking through it',
+  ]);
+});
+
+tap.test('runAgent should mark Anthropic prompt cache breakpoints by default', async () => {
+  const model = new MockLanguageModelV3({
+    provider: 'anthropic',
+    modelId: 'claude-sonnet-4-5-20250929',
+    doStream: async () => createTextStreamResult('ok') as any,
+  });
+
+  const result = await smartagent.runAgent({
+    model,
+    system: 'stable system prompt',
+    prompt: 'hello',
+  });
+  const prompt = model.doStreamCalls[0].prompt as any[];
+  const systemMessage = prompt.find((message) => message.role === 'system');
+  const userMessage = prompt.find((message) => message.role === 'user');
+
+  expect(result.text).toEqual('ok');
+  expect(systemMessage.providerOptions?.anthropic?.cacheControl?.type).toEqual('ephemeral');
+  expect(userMessage.providerOptions?.anthropic?.cacheControl?.type).toEqual('ephemeral');
+});
+
+tap.test('runAgent should allow cache defaults to be disabled', async () => {
+  const model = new MockLanguageModelV3({
+    provider: 'openai',
+    modelId: 'gpt-5',
+    doStream: async () => createTextStreamResult('ok') as any,
+  });
+
+  await smartagent.runAgent({
+    model,
+    prompt: 'hello',
+    sessionId: 'session-123',
+    cache: false,
+  });
+
+  expect(model.doStreamCalls[0].providerOptions).toBeUndefined();
+});
+
+tap.test('runAgent should return final tool call records', async () => {
+  let streamCallCount = 0;
+  const callbackToolCalls: Array<{ name: string; input: unknown }> = [];
+  const callbackToolResults: Array<{ name: string; result: unknown }> = [];
+  const model = new MockLanguageModelV3({
+    doStream: async () => {
+      streamCallCount++;
+      return streamCallCount === 1
+        ? createToolCallStreamResult('echo', { text: 'hello' }) as any
+        : createTextStreamResult('saved') as any;
+    },
+  });
+
+  const result = await smartagent.runAgent({
+    model,
+    prompt: 'echo hello',
+    tools: {
+      echo: smartagent.tool({
+        description: 'Echo text',
+        inputSchema: smartagent.z.object({ text: smartagent.z.string() }),
+        execute: async ({ text }: { text: string }) => `saved:${text}`,
+      }),
+    },
+    maxSteps: 5,
+    onToolCall: (name, input) => callbackToolCalls.push({ name, input }),
+    onToolResult: (name, result) => callbackToolResults.push({ name, result }),
+  });
+
+  const echoCall = result.toolCalls.find((toolCall) => toolCall.toolName === 'echo');
+
+  expect(result.text).toEqual('saved');
+  expect(echoCall).toBeTruthy();
+  expect(echoCall!.input).toEqual({ text: 'hello' });
+  expect(echoCall!.output).toEqual('saved:hello');
+  expect(callbackToolCalls[0]).toEqual({ name: 'echo', input: { text: 'hello' } });
+  expect(callbackToolResults[0]).toEqual({ name: 'echo', result: 'saved:hello' });
+});
+
+tap.test('runAgent should reprompt when validateCompletion returns a string', async () => {
+  let streamCallCount = 0;
+  let validationCallCount = 0;
+  const model = new MockLanguageModelV3({
+    doStream: async () => {
+      streamCallCount++;
+      return createTextStreamResult(streamCallCount === 1 ? 'incomplete' : 'complete') as any;
+    },
+  });
+
+  const result = await smartagent.runAgent({
+    model,
+    prompt: 'process document',
+    maxValidationRetries: 1,
+    validateCompletion: (runResult) => {
+      validationCallCount++;
+      return runResult.text === 'complete' ? undefined : 'Call a save tool before finalizing.';
+    },
+  });
+
+  expect(result.text).toEqual('complete');
+  expect(validationCallCount).toEqual(2);
+  expect(model.doStreamCalls.length).toEqual(2);
+  expect(JSON.stringify(model.doStreamCalls[1].prompt)).toInclude('Call a save tool before finalizing.');
+});
+
+tap.test('runAgent should reject when validation retries are exhausted', async () => {
+  let threw = false;
+  const model = new MockLanguageModelV3({
+    doStream: async () => createTextStreamResult('incomplete') as any,
+  });
+
+  try {
+    await smartagent.runAgent({
+      model,
+      prompt: 'process document',
+      validateCompletion: () => 'Missing required save tool call.',
+    });
+  } catch (error) {
+    threw = true;
+    expect((error as Error).message).toInclude('Missing required save tool call.');
+  }
+
+  expect(threw).toBeTrue();
+});
+
 // ============================================================
 // ToolRegistry
 // ============================================================
@@ -94,6 +357,29 @@ tap.test('shellTool returns expected tool names', async () => {
   expect(names).toContain('run_command');
 });
 
+tap.test('createShellTools should execute through supplied context', async () => {
+  const permissions: unknown[] = [];
+  const calls: unknown[] = [];
+  const tools = createShellTools({
+    cwd: '/workspace',
+    requestPermission: async (request) => {
+      permissions.push(request);
+    },
+    shell: {
+      run: async (command, options) => {
+        calls.push({ command, options });
+        return { exitCode: 0, stdout: 'context-output', stderr: '' };
+      },
+    },
+  });
+
+  const result = await (tools.run_command as any).execute({ command: 'echo test', timeoutMs: 1234 });
+
+  expect(result).toEqual('context-output');
+  expect(calls[0]).toEqual({ command: 'echo test', options: { cwd: '/workspace', timeoutMs: 1234, abortSignal: undefined } });
+  expect(JSON.stringify(permissions[0])).toInclude('echo test');
+});
+
 tap.test('httpTool returns expected tool names', async () => {
   const tools = httpTool();
   const names = Object.keys(tools);
@@ -108,6 +394,63 @@ tap.test('jsonTool returns expected tool names', async () => {
   expect(names).toContain('json_transform');
 });
 
+tap.test('createFilesystemTools should execute through supplied context', async () => {
+  const permissions: unknown[] = [];
+  const files = new Map<string, string>([['hello.txt', 'line1\nline2\nline3']]);
+  const tools = createFilesystemTools({
+    requestPermission: async (request) => {
+      permissions.push(request);
+    },
+    fs: {
+      readFile: async (filePath, options) => {
+        const content = files.get(filePath) ?? '';
+        if (options?.startLine || options?.endLine) {
+          const lines = content.split('\n');
+          return lines.slice((options.startLine ?? 1) - 1, options.endLine ?? lines.length).join('\n');
+        }
+        return content;
+      },
+      writeFile: async (filePath, content) => {
+        files.set(filePath, content);
+        return 'written';
+      },
+      listDirectory: async () => [...files.keys()],
+    },
+  }, { includeDelete: false });
+
+  const readResult = await (tools.read_file as any).execute({ path: 'hello.txt', startLine: 2, endLine: 2 });
+  const writeResult = await (tools.write_file as any).execute({ path: 'created.txt', content: 'created' });
+  const listResult = await (tools.list_directory as any).execute({ path: '.' });
+
+  expect(readResult).toEqual('line2');
+  expect(writeResult).toEqual('written');
+  expect(listResult).toInclude('created.txt');
+  expect(Object.keys(tools)).not.toContain('delete_file');
+  expect(JSON.stringify(permissions[0])).toInclude('created.txt');
+});
+
+tap.test('createBrowserTools should execute through supplied browser context', async () => {
+  const permissions: unknown[] = [];
+  const calls: unknown[] = [];
+  const tools = createBrowserTools({
+    requestPermission: async (request) => {
+      permissions.push(request);
+    },
+    browser: {
+      execute: async (input, options) => {
+        calls.push({ input, options });
+        return `browser:${input.action}:${input.url ?? ''}`;
+      },
+    },
+  });
+
+  const result = await (tools.browser as any).execute({ action: 'navigate', url: 'https://example.com', timeoutMs: 500 });
+
+  expect(result).toEqual('browser:navigate:https://example.com');
+  expect(JSON.stringify(calls[0])).toInclude('navigate');
+  expect(JSON.stringify(permissions[0])).toInclude('https://example.com');
+});
+
 tap.test('json_validate tool should validate valid JSON', async () => {
   const tools = jsonTool();
   const result = await (tools.json_validate as any).execute({

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartagent',
-  version: '3.0.1',
+  version: '3.5.0',
   description: 'Agentic loop for ai-sdk (Vercel AI SDK). Wraps streamText with stopWhen for parallel multi-step tool execution. Built on @push.rocks/smartai.'
 }

ts/index.ts

@@ -3,7 +3,44 @@ export { ToolRegistry } from './smartagent.classes.toolregistry.js';
 export { truncateOutput } from './smartagent.utils.truncation.js';
 export type { ITruncateResult } from './smartagent.utils.truncation.js';
 export { ContextOverflowError } from './smartagent.interfaces.js';
-export type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
+export type {
+  IAgentCacheOptions,
+  IAgentRunOptions,
+  IAgentRunResult,
+  IAgentToolCallRecord,
+  ProviderOptions,
+  TAgentCacheRetention,
+  TAgentCacheSetting,
+} from './smartagent.interfaces.js';
+export {
+  createBrowserTools,
+  createFilesystemTools,
+  createLocalToolExecutionContext,
+  createShellTools,
+  filesystemTool,
+  formatShellResult,
+  formatToolOutput,
+  shellTool,
+} from '../ts_tools/index.js';
+export type {
+  IBrowserToolInput,
+  ICreateBrowserToolsOptions,
+  ICreateFilesystemToolsOptions,
+  ICreateShellToolsOptions,
+  IFilesystemToolOptions,
+  ILocalToolExecutionContextOptions,
+  IShellToolOptions,
+  IToolBrowserContext,
+  IToolExecutionContext,
+  IToolFilesystemContext,
+  IToolFilesystemListOptions,
+  IToolFilesystemReadOptions,
+  IToolPermissionRequest,
+  IToolRunOptions,
+  IToolShellContext,
+  IToolShellResult,
+  TBrowserToolAction,
+} from '../ts_tools/index.js';
 
 // Re-export tool() and z so consumers can define tools without extra imports
 export { tool, jsonSchema } from '@push.rocks/smartai';

ts/plugins.ts

@@ -4,9 +4,9 @@ import * as path from 'path';
 export { path };
 
 // ai-sdk core
-import { streamText, generateText, stepCountIs } from 'ai';
+import { streamText, generateText, stepCountIs, wrapLanguageModel } from 'ai';
 
-export { streamText, generateText, stepCountIs };
+export { streamText, generateText, stepCountIs, wrapLanguageModel };
 
 export type {
   ModelMessage,
@@ -15,11 +15,29 @@ export type {
 } from 'ai';
 
 // @push.rocks/smartai
-import { tool, jsonSchema } from '@push.rocks/smartai';
+import {
+  applySmartAiCacheProviderOptions,
+  createSmartAiCachingMiddleware,
+  jsonSchema,
+  resolveSmartAiCacheProvider,
+  tool,
+} from '@push.rocks/smartai';
 
-export { tool, jsonSchema };
+export {
+  applySmartAiCacheProviderOptions,
+  createSmartAiCachingMiddleware,
+  resolveSmartAiCacheProvider,
+  tool,
+  jsonSchema,
+};
 
-export type { LanguageModelV3 } from '@push.rocks/smartai';
+export type {
+  ISmartAiCacheOptions,
+  LanguageModelV3,
+  TSmartAiCacheRetention,
+  TSmartAiCacheSetting,
+  TSmartAiProviderOptions as ProviderOptions,
+} from '@push.rocks/smartai';
 
 // zod
 import { z } from 'zod';

ts/smartagent.classes.agent.ts

@@ -1,7 +1,7 @@
 // Retry backoff and context overflow logic derived from opencode (MIT) — https://github.com/sst/opencode
 
 import * as plugins from './plugins.js';
-import type { IAgentRunOptions, IAgentRunResult } from './smartagent.interfaces.js';
+import type { IAgentRunOptions, IAgentRunResult, IAgentToolCallRecord } from './smartagent.interfaces.js';
 import { ContextOverflowError } from './smartagent.interfaces.js';
 
 // Retry constants
@@ -76,13 +76,110 @@ function isContextOverflow(err: unknown): boolean {
   return false;
 }
 
+function parseToolInput(input: unknown): unknown {
+  if (typeof input !== 'string') return input;
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
+  }
+}
+
+function errorToString(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+function tokenTotal(tokenUsage: unknown): number {
+  if (typeof tokenUsage === 'number') return tokenUsage;
+  if (tokenUsage && typeof tokenUsage === 'object' && typeof (tokenUsage as any).total === 'number') {
+    return (tokenUsage as any).total;
+  }
+  return 0;
+}
+
+function tokenCacheRead(tokenUsage: unknown): number {
+  if (tokenUsage && typeof tokenUsage === 'object' && typeof (tokenUsage as any).cacheRead === 'number') {
+    return (tokenUsage as any).cacheRead;
+  }
+  return 0;
+}
+
+function tokenCacheWrite(tokenUsage: unknown): number {
+  if (tokenUsage && typeof tokenUsage === 'object' && typeof (tokenUsage as any).cacheWrite === 'number') {
+    return (tokenUsage as any).cacheWrite;
+  }
+  return 0;
+}
+
+function recordToolCall(
+  toolCalls: IAgentToolCallRecord[],
+  toolCallIndexes: Map<string, number>,
+  toolCall: unknown,
+  update: { output?: unknown; error?: unknown } = {},
+): void {
+  const call = toolCall as any;
+  const toolCallId = call?.toolCallId;
+  const nextRecord: IAgentToolCallRecord = {
+    toolName: String(call?.toolName ?? ''),
+    input: parseToolInput(call?.input ?? call?.args),
+  };
+  const hasOutput = Object.prototype.hasOwnProperty.call(update, 'output');
+  const hasError = Object.prototype.hasOwnProperty.call(update, 'error');
+
+  if (hasOutput) nextRecord.output = update.output;
+  if (hasError && update.error !== undefined) nextRecord.error = errorToString(update.error);
+
+  const existingIndex = typeof toolCallId === 'string' ? toolCallIndexes.get(toolCallId) : undefined;
+  if (existingIndex !== undefined) {
+    const existingRecord = toolCalls[existingIndex];
+    existingRecord.toolName = nextRecord.toolName || existingRecord.toolName;
+    if (nextRecord.input !== undefined) existingRecord.input = nextRecord.input;
+    if (hasOutput) existingRecord.output = nextRecord.output;
+    if (nextRecord.error !== undefined) existingRecord.error = nextRecord.error;
+    return;
+  }
+
+  toolCalls.push(nextRecord);
+  if (typeof toolCallId === 'string') {
+    toolCallIndexes.set(toolCallId, toolCalls.length - 1);
+  }
+}
+
 export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult> {
   let stepCount = 0;
   let attempt = 0;
   let totalInput = 0;
   let totalOutput = 0;
+  let totalCacheRead = 0;
+  let totalCacheWrite = 0;
+  let validationRetries = 0;
+  const toolCalls: IAgentToolCallRecord[] = [];
+  const toolCallIndexes = new Map<string, number>();
+  const reasoningTextById = new Map<string, string>();
 
   const tools = options.tools ?? {};
+  const cache = options.cache ?? 'auto';
+  const configuredCacheProvider = typeof cache === 'object' ? cache.provider : undefined;
+  const messageCacheProvider = cache === false
+    ? undefined
+    : configuredCacheProvider ?? plugins.resolveSmartAiCacheProvider(options.model.provider, options.model.modelId);
+  const model = messageCacheProvider
+    ? plugins.wrapLanguageModel({
+        model: options.model,
+        middleware: plugins.createSmartAiCachingMiddleware({
+          ...(typeof cache === 'object' ? cache : {}),
+          provider: messageCacheProvider,
+        }),
+      }) as unknown as plugins.LanguageModelV3
+    : options.model;
+  const providerOptions = plugins.applySmartAiCacheProviderOptions({
+    provider: options.model.provider,
+    modelId: options.model.modelId,
+    providerOptions: options.providerOptions,
+    cache,
+    sessionId: options.sessionId,
+  });
 
   // Add a no-op sink for repaired-but-unrecognised tool calls
   const allTools: plugins.ToolSet = {
@@ -106,10 +203,11 @@ export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResu
   while (true) {
     try {
       const result = plugins.streamText({
-        model: options.model,
+        model,
         system: options.system,
         messages,
         tools: allTools,
+        providerOptions,
         stopWhen: plugins.stepCountIs(options.maxSteps ?? 20),
         maxRetries: 0, // handled manually below
         abortSignal: options.abort,
@@ -130,27 +228,82 @@ export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResu
         },
 
         onChunk: ({ chunk }) => {
-          if (chunk.type === 'text-delta' && options.onToken) {
-            options.onToken((chunk as any).textDelta ?? (chunk as any).text ?? '');
+          const chunkType = String((chunk as any).type || '');
+          if (chunkType === 'text-delta' && options.onToken) {
+            options.onToken((chunk as any).delta ?? (chunk as any).textDelta ?? (chunk as any).text ?? '');
+            return;
+          }
+          if (chunkType === 'reasoning-start') {
+            const id = (chunk as any).id || 'reasoning';
+            reasoningTextById.set(id, '');
+            options.onReasoningStart?.(id, (chunk as any).providerMetadata);
+            return;
+          }
+          if (chunkType === 'reasoning-delta') {
+            const id = (chunk as any).id || 'reasoning';
+            const delta = (chunk as any).delta ?? (chunk as any).textDelta ?? (chunk as any).text ?? '';
+            if (!reasoningTextById.has(id)) {
+              reasoningTextById.set(id, '');
+              options.onReasoningStart?.(id, (chunk as any).providerMetadata);
+            }
+            reasoningTextById.set(id, (reasoningTextById.get(id) ?? '') + delta);
+            options.onReasoningDelta?.(id, delta, (chunk as any).providerMetadata);
+            return;
+          }
+          if (chunkType === 'reasoning-end') {
+            const id = (chunk as any).id || 'reasoning';
+            const text = reasoningTextById.get(id) ?? '';
+            reasoningTextById.delete(id);
+            options.onReasoningEnd?.(id, text, (chunk as any).providerMetadata);
           }
         },
 
         experimental_onToolCallStart: options.onToolCall
           ? ({ toolCall }) => {
-              options.onToolCall!(toolCall.toolName, (toolCall as any).input ?? (toolCall as any).args);
+              const input = parseToolInput((toolCall as any).input ?? (toolCall as any).args);
+              recordToolCall(toolCalls, toolCallIndexes, toolCall);
+              options.onToolCall!(toolCall.toolName, input);
             }
-          : undefined,
+          : ({ toolCall }) => {
+              recordToolCall(toolCalls, toolCallIndexes, toolCall);
+            },
 
         experimental_onToolCallFinish: options.onToolResult
-          ? ({ toolCall }) => {
-              options.onToolResult!(toolCall.toolName, (toolCall as any).result);
+          ? (event) => {
+              recordToolCall(
+                toolCalls,
+                toolCallIndexes,
+                event.toolCall,
+                event.success ? { output: event.output } : { error: event.error },
+              );
+              options.onToolResult!(event.toolCall.toolName, event.success ? event.output : undefined);
             }
-          : undefined,
+          : (event) => {
+              recordToolCall(
+                toolCalls,
+                toolCallIndexes,
+                event.toolCall,
+                event.success ? { output: event.output } : { error: event.error },
+              );
+            },
 
-        onStepFinish: ({ usage }) => {
+        onStepFinish: ({ usage, toolCalls: stepToolCalls, toolResults, content }) => {
           stepCount++;
-          totalInput += usage?.inputTokens ?? 0;
-          totalOutput += usage?.outputTokens ?? 0;
+          totalInput += tokenTotal((usage as any)?.inputTokens);
+          totalOutput += tokenTotal((usage as any)?.outputTokens);
+          totalCacheRead += tokenCacheRead((usage as any)?.inputTokens);
+          totalCacheWrite += tokenCacheWrite((usage as any)?.inputTokens);
+          for (const toolCall of stepToolCalls) {
+            recordToolCall(toolCalls, toolCallIndexes, toolCall);
+          }
+          for (const toolResult of toolResults) {
+            recordToolCall(toolCalls, toolCallIndexes, toolResult, { output: (toolResult as any).output });
+          }
+          for (const part of content) {
+            if ((part as any).type === 'tool-error') {
+              recordToolCall(toolCalls, toolCallIndexes, part, { error: (part as any).error });
+            }
+          }
         },
       });
 
@@ -158,20 +311,46 @@ export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResu
       const text = await result.text;
       const finishReason = await result.finishReason;
       const responseData = await result.response;
+      const responseMessages = responseData.messages as plugins.ModelMessage[];
+      for (const [id, reasoningText] of reasoningTextById) {
+        options.onReasoningEnd?.(id, reasoningText);
+        reasoningTextById.delete(id);
+      }
 
       attempt = 0; // reset on success
 
-      return {
+      const runResult: IAgentRunResult = {
         text,
-        messages: responseData.messages as plugins.ModelMessage[],
+        messages: responseMessages,
         steps: stepCount,
         finishReason,
         usage: {
           inputTokens: totalInput,
           outputTokens: totalOutput,
           totalTokens: totalInput + totalOutput,
+          cacheReadTokens: totalCacheRead,
+          cacheWriteTokens: totalCacheWrite,
         },
+        toolCalls,
       };
+
+      if (options.validateCompletion) {
+        const validationPrompt = await options.validateCompletion(runResult);
+        if (typeof validationPrompt === 'string') {
+          if (validationRetries >= (options.maxValidationRetries ?? 0)) {
+            throw new Error(`Agent completion validation failed: ${validationPrompt}`);
+          }
+          validationRetries++;
+          messages = [
+            ...messages,
+            ...responseMessages,
+            { role: 'user' as const, content: validationPrompt },
+          ];
+          continue;
+        }
+      }
+
+      return runResult;
     } catch (err: unknown) {
       // Abort — don't retry
       if (err instanceof DOMException && err.name === 'AbortError') throw err;

ts/smartagent.interfaces.ts

@@ -1,4 +1,24 @@
-import type { ToolSet, ModelMessage, LanguageModelV3 } from './plugins.js';
+import type {
+  ISmartAiCacheOptions,
+  ToolSet,
+  ModelMessage,
+  LanguageModelV3,
+  ProviderOptions,
+  TSmartAiCacheRetention,
+  TSmartAiCacheSetting,
+} from './plugins.js';
+
+export type { ProviderOptions };
+export type IAgentCacheOptions = ISmartAiCacheOptions;
+export type TAgentCacheRetention = TSmartAiCacheRetention;
+export type TAgentCacheSetting = TSmartAiCacheSetting;
+
+export interface IAgentToolCallRecord {
+  toolName: string;
+  input: unknown;
+  output?: unknown;
+  error?: string;
+}
 
 export interface IAgentRunOptions {
   /** The LanguageModelV3 to use — from smartai.getModel() */
@@ -9,6 +29,12 @@ export interface IAgentRunOptions {
   system?: string;
   /** Tools available to the agent */
   tools?: ToolSet;
+  /** Provider-specific AI SDK request options passed through to streamText() */
+  providerOptions?: ProviderOptions;
+  /** Stable session id used as provider prompt-cache affinity key where supported. */
+  sessionId?: string;
+  /** Prompt-cache policy. Default: 'auto'. Set false to disable smartagent cache defaults. */
+  cache?: TAgentCacheSetting;
   /**
    * Maximum number of LLM↔tool round trips.
    * Each step may execute multiple tools in parallel.
@@ -19,10 +45,23 @@ export interface IAgentRunOptions {
   messages?: ModelMessage[];
   /** Called for each streamed text delta */
   onToken?: (delta: string) => void;
+  /** Called when the model starts a streamed reasoning summary */
+  onReasoningStart?: (id: string, providerMetadata?: unknown) => void;
+  /** Called for each streamed reasoning summary delta */
+  onReasoningDelta?: (id: string, delta: string, providerMetadata?: unknown) => void;
+  /** Called when a streamed reasoning summary completes */
+  onReasoningEnd?: (id: string, text: string, providerMetadata?: unknown) => void;
   /** Called when a tool call starts */
   onToolCall?: (toolName: string, input: unknown) => void;
   /** Called when a tool call completes */
   onToolResult?: (toolName: string, result: unknown) => void;
+  /**
+   * Validate the completed run. Return a string to reject the run and reprompt,
+   * or return void to accept the result.
+   */
+  validateCompletion?: (result: IAgentRunResult) => Promise<string | void> | string | void;
+  /** Number of validation-triggered reprompts allowed. Default: 0 */
+  maxValidationRetries?: number;
   /**
    * Called when total token usage approaches the model's context limit.
    * Receives the full message history and must return a compacted replacement.
@@ -43,7 +82,15 @@ export interface IAgentRunResult {
   /** Finish reason from the final step */
   finishReason: string;
   /** Accumulated token usage across all steps */
-  usage: { inputTokens: number; outputTokens: number; totalTokens: number };
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+  };
+  /** Tool calls observed during the run, including inputs and outputs/errors when available */
+  toolCalls: IAgentToolCallRecord[];
 }
 
 export class ContextOverflowError extends Error {

ts_tools/index.ts

@@ -1,7 +1,24 @@
-export { filesystemTool } from './tool.filesystem.js';
-export type { IFilesystemToolOptions } from './tool.filesystem.js';
-export { shellTool } from './tool.shell.js';
-export type { IShellToolOptions } from './tool.shell.js';
+export { createBrowserTools } from './tool.browser.js';
+export type { ICreateBrowserToolsOptions } from './tool.browser.js';
+export { createFilesystemTools, filesystemTool } from './tool.filesystem.js';
+export type { ICreateFilesystemToolsOptions, IFilesystemToolOptions } from './tool.filesystem.js';
+export { createShellTools, shellTool } from './tool.shell.js';
+export type { ICreateShellToolsOptions, IShellToolOptions } from './tool.shell.js';
+export { createLocalToolExecutionContext, formatShellResult, formatToolOutput } from './tool.context.js';
+export type {
+  IBrowserToolInput,
+  ILocalToolExecutionContextOptions,
+  IToolBrowserContext,
+  IToolExecutionContext,
+  IToolFilesystemContext,
+  IToolFilesystemListOptions,
+  IToolFilesystemReadOptions,
+  IToolPermissionRequest,
+  IToolRunOptions,
+  IToolShellContext,
+  IToolShellResult,
+  TBrowserToolAction,
+} from './tool.context.js';
 export { httpTool } from './tool.http.js';
 export { jsonTool } from './tool.json.js';
 export { truncateOutput } from './plugins.js';

ts_tools/plugins.ts

@@ -1,8 +1,9 @@
 // node native
-import * as path from 'path';
-import * as fs from 'fs';
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
-export { path, fs };
+export { childProcess, fs, path };
 
 // zod
 import { z } from 'zod';

ts_tools/tool.browser.ts

@@ -0,0 +1,94 @@
+import * as plugins from './plugins.js';
+import {
+  formatToolOutput,
+  type IBrowserToolInput,
+  type IToolExecutionContext,
+  type TBrowserToolAction,
+} from './tool.context.js';
+
+export interface ICreateBrowserToolsOptions {
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
+}
+
+const browserActions = new Set<TBrowserToolAction>(['navigate', 'snapshot', 'screenshot', 'click', 'fill', 'press', 'evaluate', 'close']);
+
+export function createBrowserTools(context: IToolExecutionContext, options: ICreateBrowserToolsOptions = {}): plugins.ToolSet {
+  return {
+    browser: plugins.tool({
+      description: [
+        'Control a browser supplied by the host execution context for web UI inspection and interaction.',
+        'Actions: navigate, snapshot, screenshot, click, fill, press, evaluate, close.',
+        'Use snapshot after navigation or interaction to inspect page text and interactive selectors before choosing the next action.',
+        'Actions that navigate or modify page state require host permission when configured.',
+      ].join(' '),
+      inputSchema: plugins.z.object({
+        action: plugins.z.string().default('snapshot').describe('Action: navigate, snapshot, screenshot, click, fill, press, evaluate, or close'),
+        url: plugins.z.string().optional().describe('URL for navigate'),
+        selector: plugins.z.string().optional().describe('CSS or Playwright selector for click/fill'),
+        text: plugins.z.string().optional().describe('Text for fill, key name for press, or screenshot mode/full-page hint'),
+        script: plugins.z.string().optional().describe('JavaScript expression or function body for evaluate'),
+        timeoutMs: plugins.z.number().optional().describe('Optional action timeout in milliseconds'),
+      }),
+      execute: async (input: IBrowserToolInput) => {
+        if (!context.browser) {
+          throw new Error('Browser tool is not available in this execution context.');
+        }
+        const action = normalizeBrowserAction(input.action);
+        await requestBrowserPermission(context, { ...input, action });
+        const result = await context.browser.execute({ ...input, action }, {
+          timeoutMs: input.timeoutMs,
+          abortSignal: context.abortSignal,
+        });
+        return plugins.truncateOutput(formatToolOutput(result), {
+          maxLines: options.maxLines,
+          maxBytes: options.maxBytes,
+        }).content;
+      },
+    }),
+  };
+}
+
+const normalizeBrowserAction = (input: unknown): TBrowserToolAction => {
+  const action = typeof input === 'string' && input.trim()
+    ? input.trim().toLowerCase()
+    : 'snapshot';
+  if (browserActions.has(action as TBrowserToolAction)) {
+    return action as TBrowserToolAction;
+  }
+  throw new Error(`Unsupported browser action: ${String(input)}. Use one of: ${[...browserActions].join(', ')}.`);
+};
+
+const requestBrowserPermission = async (context: IToolExecutionContext, input: IBrowserToolInput & { action: TBrowserToolAction }): Promise<void> => {
+  if (!context.requestPermission) return;
+  if (input.action === 'snapshot' || input.action === 'screenshot') return;
+  const titleByAction: Record<TBrowserToolAction, string> = {
+    navigate: 'Navigate browser',
+    snapshot: 'Inspect browser',
+    screenshot: 'Capture browser screenshot',
+    click: 'Click browser element',
+    fill: 'Fill browser element',
+    press: 'Press browser key',
+    evaluate: 'Evaluate browser JavaScript',
+    close: 'Close browser session',
+  };
+  await context.requestPermission({
+    type: 'browser',
+    title: titleByAction[input.action],
+    metadata: {
+      action: input.action,
+      url: input.url,
+      selector: input.selector,
+      key: input.action === 'press' ? input.text : undefined,
+      textLength: input.action === 'fill' ? input.text?.length ?? 0 : undefined,
+      scriptPreview: input.action === 'evaluate' && input.script ? compactMetadataText(input.script) : undefined,
+    },
+  });
+};
+
+const compactMetadataText = (text: string): string => {
+  const compacted = text.replace(/\s+/g, ' ').trim();
+  return compacted.length > 160 ? `${compacted.slice(0, 157)}...` : compacted;
+};

ts_tools/tool.context.ts

@@ -0,0 +1,207 @@
+import * as plugins from './plugins.js';
+
+export interface IToolPermissionRequest {
+  type: string;
+  title: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IToolRunOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  abortSignal?: AbortSignal;
+}
+
+export interface IToolShellResult {
+  exitCode: number;
+  stdout: string;
+  stderr?: string;
+  signal?: string;
+}
+
+export interface IToolShellContext {
+  run(command: string, options?: IToolRunOptions): Promise<IToolShellResult | string>;
+}
+
+export interface IToolFilesystemReadOptions {
+  startLine?: number;
+  endLine?: number;
+}
+
+export interface IToolFilesystemListOptions {
+  recursive?: boolean;
+}
+
+export interface IToolFilesystemContext {
+  readFile(filePath: string, options?: IToolFilesystemReadOptions): Promise<string>;
+  writeFile(filePath: string, content: string): Promise<string | void>;
+  listDirectory(directoryPath: string, options?: IToolFilesystemListOptions): Promise<string[] | string>;
+  deletePath?(targetPath: string): Promise<string | void>;
+}
+
+export type TBrowserToolAction = 'navigate' | 'snapshot' | 'screenshot' | 'click' | 'fill' | 'press' | 'evaluate' | 'close';
+
+export interface IBrowserToolInput {
+  action?: TBrowserToolAction | string;
+  url?: string;
+  selector?: string;
+  text?: string;
+  script?: string;
+  timeoutMs?: number;
+}
+
+export interface IToolBrowserContext {
+  execute(input: IBrowserToolInput, options?: { timeoutMs?: number; abortSignal?: AbortSignal }): Promise<unknown>;
+}
+
+export interface IToolExecutionContext {
+  cwd?: string;
+  rootDir?: string;
+  abortSignal?: AbortSignal;
+  shell?: IToolShellContext;
+  fs?: IToolFilesystemContext;
+  browser?: IToolBrowserContext;
+  requestPermission?: (request: IToolPermissionRequest) => Promise<void>;
+}
+
+export interface ILocalToolExecutionContextOptions {
+  cwd?: string;
+  rootDir?: string;
+  abortSignal?: AbortSignal;
+  requestPermission?: (request: IToolPermissionRequest) => Promise<void>;
+}
+
+export const createLocalToolExecutionContext = (options: ILocalToolExecutionContextOptions = {}): IToolExecutionContext => {
+  const cwd = options.cwd ?? process.cwd();
+  const rootDir = options.rootDir;
+  return {
+    cwd,
+    rootDir,
+    abortSignal: options.abortSignal,
+    requestPermission: options.requestPermission,
+    shell: {
+      run: (command, runOptions) => runLocalShellCommand(command, {
+        cwd: resolveLocalPath(runOptions?.cwd ?? cwd, rootDir),
+        timeoutMs: runOptions?.timeoutMs,
+        abortSignal: runOptions?.abortSignal ?? options.abortSignal,
+      }),
+    },
+    fs: {
+      readFile: async (filePath, readOptions) => {
+        const resolved = resolveLocalPath(filePath, rootDir, cwd);
+        const content = await plugins.fs.promises.readFile(resolved, 'utf8');
+        if (readOptions?.startLine !== undefined || readOptions?.endLine !== undefined) {
+          const lines = content.split('\n');
+          const start = Math.max((readOptions.startLine ?? 1) - 1, 0);
+          const end = Math.max(readOptions.endLine ?? lines.length, start);
+          return lines.slice(start, end).join('\n');
+        }
+        return content;
+      },
+      writeFile: async (filePath, content) => {
+        const resolved = resolveLocalPath(filePath, rootDir, cwd);
+        await plugins.fs.promises.mkdir(plugins.path.dirname(resolved), { recursive: true });
+        await plugins.fs.promises.writeFile(resolved, content, 'utf8');
+        return `Written ${Buffer.byteLength(content, 'utf8')} bytes to ${filePath}`;
+      },
+      listDirectory: async (directoryPath, listOptions) => {
+        const resolved = resolveLocalPath(directoryPath, rootDir, cwd);
+        return listLocalDirectory(resolved, !!listOptions?.recursive);
+      },
+      deletePath: async (targetPath) => {
+        const resolved = resolveLocalPath(targetPath, rootDir, cwd);
+        await plugins.fs.promises.rm(resolved, { recursive: false, force: false });
+        return `Deleted ${targetPath}`;
+      },
+    },
+  };
+};
+
+export const formatShellResult = (result: IToolShellResult | string): string => {
+  if (typeof result === 'string') return result;
+  if (result.exitCode === 0) return result.stdout;
+  return [
+    `Exit code: ${result.exitCode}`,
+    result.signal ? `Signal: ${result.signal}` : '',
+    `stdout:\n${result.stdout}`,
+    `stderr:\n${result.stderr ?? ''}`,
+  ].filter(Boolean).join('\n');
+};
+
+export const formatToolOutput = (output: unknown): string => {
+  if (typeof output === 'string') return output;
+  try {
+    return JSON.stringify(output, undefined, 2);
+  } catch {
+    return String(output);
+  }
+};
+
+const resolveLocalPath = (targetPath: string, rootDir?: string, baseDir?: string): string => {
+  const base = rootDir ?? baseDir ?? process.cwd();
+  const resolved = plugins.path.isAbsolute(targetPath)
+    ? plugins.path.resolve(targetPath)
+    : plugins.path.resolve(base, targetPath);
+  if (rootDir) {
+    const resolvedRoot = plugins.path.resolve(rootDir);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + plugins.path.sep)) {
+      throw new Error(`Access denied: "${targetPath}" is outside allowed root "${rootDir}"`);
+    }
+  }
+  return resolved;
+};
+
+const listLocalDirectory = async (directoryPath: string, recursive: boolean): Promise<string[]> => {
+  const entries = await plugins.fs.promises.readdir(directoryPath, { withFileTypes: true });
+  const result: string[] = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const relativePath = entry.name + (entry.isDirectory() ? '/' : '');
+    result.push(relativePath);
+    if (recursive && entry.isDirectory()) {
+      const childEntries = await listLocalDirectory(plugins.path.join(directoryPath, entry.name), true);
+      result.push(...childEntries.map((childEntry) => `${entry.name}/${childEntry}`));
+    }
+  }
+  return result;
+};
+
+const runLocalShellCommand = async (command: string, options: IToolRunOptions): Promise<IToolShellResult> => {
+  return new Promise<IToolShellResult>((resolve) => {
+    const child = plugins.childProcess.spawn('bash', ['-lc', command], {
+      cwd: options.cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timeout = options.timeoutMs && options.timeoutMs > 0
+      ? setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGTERM');
+      }, options.timeoutMs)
+      : undefined;
+    const abort = () => child.kill('SIGTERM');
+    options.abortSignal?.addEventListener('abort', abort, { once: true });
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (error) => {
+      if (timeout) clearTimeout(timeout);
+      options.abortSignal?.removeEventListener('abort', abort);
+      resolve({ exitCode: 1, stdout, stderr: `${stderr}${error.message}` });
+    });
+    child.on('close', (code, signal) => {
+      if (timeout) clearTimeout(timeout);
+      options.abortSignal?.removeEventListener('abort', abort);
+      resolve({
+        exitCode: code ?? (timedOut ? 124 : 1),
+        stdout,
+        stderr: timedOut ? `${stderr}\nCommand timed out after ${options.timeoutMs}ms.`.trim() : stderr,
+        signal: signal ?? undefined,
+      });
+    });
+  });
+};

ts_tools/tool.filesystem.ts

@@ -1,30 +1,43 @@
 import * as plugins from './plugins.js';
+import {
+  createLocalToolExecutionContext,
+  formatToolOutput,
+  type IToolExecutionContext,
+} from './tool.context.js';
 
 export interface IFilesystemToolOptions {
   /** Restrict file access to this directory. Default: process.cwd() */
   rootDir?: string;
+  /** Execution context. Defaults to a local Node.js context. */
+  context?: IToolExecutionContext;
+  /** Include delete_file. Default: true for compatibility. */
+  includeDelete?: boolean;
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
 }
 
-function validatePath(filePath: string, rootDir?: string): string {
-  const resolved = plugins.path.resolve(filePath);
-  if (rootDir) {
-    const resolvedRoot = plugins.path.resolve(rootDir);
-    if (!resolved.startsWith(resolvedRoot + plugins.path.sep) && resolved !== resolvedRoot) {
-      throw new Error(`Access denied: "${filePath}" is outside allowed root "${rootDir}"`);
-    }
-  }
-  return resolved;
+export interface ICreateFilesystemToolsOptions {
+  /** Include delete_file. Default: true. */
+  includeDelete?: boolean;
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
 }
 
-export function filesystemTool(options?: IFilesystemToolOptions): plugins.ToolSet {
-  const rootDir = options?.rootDir;
-
-  return {
+export function createFilesystemTools(context: IToolExecutionContext, options: ICreateFilesystemToolsOptions = {}): plugins.ToolSet {
+  const truncate = (output: unknown) => plugins.truncateOutput(formatToolOutput(output), {
+    maxLines: options.maxLines,
+    maxBytes: options.maxBytes,
+  }).content;
+  const tools: plugins.ToolSet = {
     read_file: plugins.tool({
       description:
-        'Read file contents. Returns the full text or a specified line range.',
+        'Read a UTF-8 file in the active workspace. Paths may be absolute or relative to the workspace root.',
       inputSchema: plugins.z.object({
-        path: plugins.z.string().describe('Absolute path to the file'),
+        path: plugins.z.string().describe('File path'),
         startLine: plugins.z
           .number()
           .optional()
@@ -43,89 +56,78 @@ export function filesystemTool(options?: IFilesystemToolOptions): plugins.ToolSe
         startLine?: number;
         endLine?: number;
       }) => {
-        const resolved = validatePath(filePath, rootDir);
-        const content = plugins.fs.readFileSync(resolved, 'utf-8');
-
-        if (startLine !== undefined || endLine !== undefined) {
-          const lines = content.split('\n');
-          const start = (startLine ?? 1) - 1;
-          const end = endLine ?? lines.length;
-          const sliced = lines.slice(start, end).join('\n');
-          return plugins.truncateOutput(sliced).content;
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
         }
-
-        return plugins.truncateOutput(content).content;
+        return truncate(await context.fs.readFile(filePath, { startLine, endLine }));
       },
     }),
 
     write_file: plugins.tool({
       description:
-        'Write content to a file (creates parent dirs if needed, overwrites existing).',
+        'Write UTF-8 content to a file in the active workspace. Creates parent directories and overwrites existing content. Requires host permission when configured.',
       inputSchema: plugins.z.object({
-        path: plugins.z.string().describe('Absolute path to the file'),
-        content: plugins.z.string().describe('Content to write'),
+        path: plugins.z.string().describe('File path'),
+        content: plugins.z.string().describe('Complete file content to write'),
       }),
       execute: async ({ path: filePath, content }: { path: string; content: string }) => {
-        const resolved = validatePath(filePath, rootDir);
-        const dir = plugins.path.dirname(resolved);
-        plugins.fs.mkdirSync(dir, { recursive: true });
-        plugins.fs.writeFileSync(resolved, content, 'utf-8');
-        return `Written ${content.length} characters to ${filePath}`;
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
+        }
+        await context.requestPermission?.({
+          type: 'write',
+          title: 'Write file',
+          metadata: { path: filePath, bytes: Buffer.byteLength(content, 'utf8') },
+        });
+        const result = await context.fs.writeFile(filePath, content);
+        return truncate(result ?? `Written ${Buffer.byteLength(content, 'utf8')} bytes to ${filePath}`);
       },
     }),
 
     list_directory: plugins.tool({
-      description: 'List files and directories at the given path.',
+      description: 'List files and directories in the active workspace. Paths may be absolute or relative to the workspace root.',
       inputSchema: plugins.z.object({
-        path: plugins.z.string().describe('Directory path to list'),
+        path: plugins.z.string().default('.').describe('Directory path to list'),
         recursive: plugins.z
           .boolean()
           .optional()
-          .describe('List recursively (default: false)'),
+          .describe('List recursively. Default: false'),
       }),
-      execute: async ({
-        path: dirPath,
-        recursive,
-      }: {
-        path: string;
-        recursive?: boolean;
-      }) => {
-        const resolved = validatePath(dirPath, rootDir);
-
-        function listDir(dir: string, prefix: string = ''): string[] {
-          const entries = plugins.fs.readdirSync(dir, { withFileTypes: true });
-          const result: string[] = [];
-          for (const entry of entries) {
-            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-            const indicator = entry.isDirectory() ? '/' : '';
-            result.push(`${rel}${indicator}`);
-            if (recursive && entry.isDirectory()) {
-              result.push(...listDir(plugins.path.join(dir, entry.name), rel));
-            }
-          }
-          return result;
+      execute: async ({ path: directoryPath, recursive }: { path: string; recursive?: boolean }) => {
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
         }
-
-        const entries = listDir(resolved);
-        return plugins.truncateOutput(entries.join('\n')).content;
-      },
-    }),
-
-    delete_file: plugins.tool({
-      description: 'Delete a file or empty directory.',
-      inputSchema: plugins.z.object({
-        path: plugins.z.string().describe('Path to delete'),
-      }),
-      execute: async ({ path: filePath }: { path: string }) => {
-        const resolved = validatePath(filePath, rootDir);
-        const stat = plugins.fs.statSync(resolved);
-        if (stat.isDirectory()) {
-          plugins.fs.rmdirSync(resolved);
-        } else {
-          plugins.fs.unlinkSync(resolved);
-        }
-        return `Deleted ${filePath}`;
+        const result = await context.fs.listDirectory(directoryPath, { recursive });
+        return truncate(Array.isArray(result) ? result.join('\n') : result);
       },
     }),
   };
+
+  if (options.includeDelete !== false) {
+    tools.delete_file = plugins.tool({
+      description: 'Delete a file or empty directory in the active workspace. Requires host permission when configured.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('Path to delete'),
+      }),
+      execute: async ({ path: targetPath }: { path: string }) => {
+        if (!context.fs?.deletePath) {
+          throw new Error('Deleting files is not available in this execution context.');
+        }
+        await context.requestPermission?.({
+          type: 'delete',
+          title: 'Delete file',
+          metadata: { path: targetPath },
+        });
+        const result = await context.fs.deletePath(targetPath);
+        return truncate(result ?? `Deleted ${targetPath}`);
+      },
+    });
+  }
+
+  return tools;
+}
+
+export function filesystemTool(options?: IFilesystemToolOptions): plugins.ToolSet {
+  const context = options?.context ?? createLocalToolExecutionContext({ rootDir: options?.rootDir });
+  return createFilesystemTools(context, options);
 }

ts_tools/tool.http.ts

@@ -7,7 +7,7 @@ export function httpTool(): plugins.ToolSet {
       inputSchema: plugins.z.object({
         url: plugins.z.string().describe('URL to request'),
         headers: plugins.z
-          .record(plugins.z.string())
+          .record(plugins.z.string(), plugins.z.string())
           .optional()
           .describe('Request headers'),
       }),
@@ -39,11 +39,11 @@ export function httpTool(): plugins.ToolSet {
       inputSchema: plugins.z.object({
         url: plugins.z.string().describe('URL to request'),
         body: plugins.z
-          .record(plugins.z.unknown())
+          .record(plugins.z.string(), plugins.z.unknown())
           .optional()
           .describe('JSON body to send'),
         headers: plugins.z
-          .record(plugins.z.string())
+          .record(plugins.z.string(), plugins.z.string())
           .optional()
           .describe('Request headers'),
       }),

ts_tools/tool.shell.ts

@@ -1,19 +1,37 @@
 import * as plugins from './plugins.js';
+import {
+  createLocalToolExecutionContext,
+  formatShellResult,
+  type IToolExecutionContext,
+} from './tool.context.js';
 
 export interface IShellToolOptions {
   /** Allowed commands whitelist. If empty, all commands are allowed. */
   allowedCommands?: string[];
   /** Working directory for shell execution */
   cwd?: string;
+  /** Execution context. Defaults to a local Node.js context. */
+  context?: IToolExecutionContext;
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
 }
 
-export function shellTool(options?: IShellToolOptions): plugins.ToolSet {
-  const smartshell = new plugins.smartshell.Smartshell({ executor: 'bash' });
+export interface ICreateShellToolsOptions {
+  /** Allowed commands whitelist. If empty, all commands are allowed. */
+  allowedCommands?: string[];
+  /** Maximum output lines before truncating. */
+  maxLines?: number;
+  /** Maximum output bytes before truncating. */
+  maxBytes?: number;
+}
 
+export function createShellTools(context: IToolExecutionContext, options: ICreateShellToolsOptions = {}): plugins.ToolSet {
   return {
     run_command: plugins.tool({
       description:
-        'Execute a shell command. Provide the full command string. stdout and stderr are returned.',
+        'Execute a shell command in the active workspace. Provide the full command string. stdout and stderr are returned.',
       inputSchema: plugins.z.object({
         command: plugins.z.string().describe('The shell command to execute'),
         cwd: plugins.z
@@ -24,39 +42,55 @@ export function shellTool(options?: IShellToolOptions): plugins.ToolSet {
           .number()
           .optional()
           .describe('Timeout in milliseconds'),
+        timeoutMs: plugins.z
+          .number()
+          .optional()
+          .describe('Timeout in milliseconds'),
       }),
       execute: async ({
         command,
         cwd,
         timeout,
+        timeoutMs,
       }: {
         command: string;
         cwd?: string;
         timeout?: number;
+        timeoutMs?: number;
       }) => {
-        // Validate against allowed commands whitelist
-        if (options?.allowedCommands?.length) {
+        if (!context.shell) {
+          throw new Error('Shell tool is not available in this execution context.');
+        }
+
+        if (options.allowedCommands?.length) {
           const baseCommand = command.split(/\s+/)[0];
           if (!options.allowedCommands.includes(baseCommand)) {
             return `Command "${baseCommand}" is not in the allowed commands list: ${options.allowedCommands.join(', ')}`;
           }
         }
 
-        // Build full command string with cd prefix if cwd specified
-        const effectiveCwd = cwd ?? options?.cwd;
-        const fullCommand = effectiveCwd
-          ? `cd ${JSON.stringify(effectiveCwd)} && ${command}`
-          : command;
+        await context.requestPermission?.({
+          type: 'shell',
+          title: 'Run shell command',
+          metadata: { command, cwd: cwd ?? context.cwd },
+        });
 
-        const execResult = await smartshell.exec(fullCommand);
+        const execResult = await context.shell.run(command, {
+          cwd: cwd ?? context.cwd,
+          timeoutMs: timeoutMs ?? timeout,
+          abortSignal: context.abortSignal,
+        });
 
-        const output =
-          execResult.exitCode === 0
-            ? execResult.stdout
-            : `Exit code: ${execResult.exitCode}\nstdout:\n${execResult.stdout}\nstderr:\n${execResult.stderr ?? ''}`;
-
-        return plugins.truncateOutput(output).content;
+        return plugins.truncateOutput(formatShellResult(execResult), {
+          maxLines: options.maxLines,
+          maxBytes: options.maxBytes,
+        }).content;
       },
     }),
   };
 }
+
+export function shellTool(options?: IShellToolOptions): plugins.ToolSet {
+  const context = options?.context ?? createLocalToolExecutionContext({ cwd: options?.cwd });
+  return createShellTools(context, options);
+}

tsconfig.json

@@ -3,10 +3,10 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
+    "noImplicitAny": true,
     "esModuleInterop": true,
     "verbatimModuleSyntax": true,
-    "baseUrl": ".",
-    "paths": {}
+    "types": ["node"]
   },
   "exclude": ["dist_*/**/*.d.ts"]
 }