v3.3.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,64 @@
 # Changelog
 
+## Pending
+
+
+
+
+## 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
+
+- Updated readme.md diagram: expanded 'Messages' box width and realigned 'streamText' and 'Tools' columns
+- Documentation-only change; no code or behavior affected
+
 ## 2026-03-06 - 3.0.0 - BREAKING CHANGE(api)
 Migrate public API to ai-sdk v6 and refactor core agent architecture: replace class-based DualAgent/Driver/Guardian with a single runAgent function; introduce ts_tools factories for tools, a compactMessages compaction subpath, and truncateOutput utility; simplify ToolRegistry to return ToolSet and remove legacy BaseToolWrapper/tool classes; update package exports and dependencies and bump major version.
 
@@ -160,4 +219,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.0",
+  "version": "3.3.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
@@ -58,10 +58,10 @@ console.log(result.usage);   // { promptTokens, completionTokens, totalTokens }
 ┌─────────────────────────────────────────────────┐
 │  runAgent({ model, prompt, tools, maxSteps })   │
 │                                                 │
-│  ┌───────────┐   ┌──────────┐   ┌───────────┐  │
-│  │ Messages   │──▶│ streamText│──▶│  Tools    │  │
-│  │ (history)  │◀──│ (AI SDK) │◀──│ (ToolSet) │  │
-│  └───────────┘   └──────────┘   └───────────┘  │
+│  ┌────────────┐   ┌───────────┐   ┌───────────┐ │
+│  │ Messages   │──▶│ streamText│──▶│  Tools    │ │
+│  │ (history)  │◀──│ (AI SDK)  │◀──│ (ToolSet) │ │
+│  └────────────┘   └───────────┘   └───────────┘ │
 │                                                 │
 │  stopWhen: stepCountIs(maxSteps)                │
 │  + retry with backoff on 429/529/503            │
@@ -91,11 +91,17 @@ 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 |
 | `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 +113,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:

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,56 @@
 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 { 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 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 +83,176 @@ 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 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
 // ============================================================

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartagent',
-  version: '3.0.0',
+  version: '3.3.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,15 @@ 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';
 
 // 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,109 @@ 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 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 +202,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,
@@ -137,20 +234,50 @@ export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResu
 
         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 +285,42 @@ 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[];
 
       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.
@@ -23,6 +49,13 @@ export interface IAgentRunOptions {
   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 +76,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/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'),
       }),

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"]
 }