feat(agent): add provider options passthrough, tool call records, and completion validation retries

ts/smartagent.interfaces.ts

@@ -1,4 +1,13 @@
-import type { ToolSet, ModelMessage, LanguageModelV3 } from './plugins.js';
+import type { ToolSet, ModelMessage, LanguageModelV3, ProviderOptions } from './plugins.js';
+
+export type { ProviderOptions };
+
+export interface IAgentToolCallRecord {
+  toolName: string;
+  input: unknown;
+  output?: unknown;
+  error?: string;
+}
 
 export interface IAgentRunOptions {
   /** The LanguageModelV3 to use — from smartai.getModel() */
@@ -9,6 +18,8 @@ export interface IAgentRunOptions {
   system?: string;
   /** Tools available to the agent */
   tools?: ToolSet;
+  /** Provider-specific AI SDK request options passed through to streamText() */
+  providerOptions?: ProviderOptions;
   /**
    * Maximum number of LLM↔tool round trips.
    * Each step may execute multiple tools in parallel.
@@ -23,6 +34,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.
@@ -44,6 +62,8 @@ export interface IAgentRunResult {
   finishReason: string;
   /** Accumulated token usage across all steps */
   usage: { inputTokens: number; outputTokens: number; totalTokens: number };
+  /** Tool calls observed during the run, including inputs and outputs/errors when available */
+  toolCalls: IAgentToolCallRecord[];
 }
 
 export class ContextOverflowError extends Error {