@push.rocks/smartagent 1.7.0 → 3.0.0

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartagent',
-  version: '1.7.0',
-  description: 'an agentic framework built on top of @push.rocks/smartai'
+  version: '3.0.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.'
 }

package/ts/index.ts

@@ -1,31 +1,11 @@
-import * as plugins from './plugins.js';
-
-// Export the dual-agent orchestrator (main entry point)
-export { DualAgentOrchestrator } from './smartagent.classes.dualagent.js';
-
-// Export individual agents
-export { DriverAgent } from './smartagent.classes.driveragent.js';
-export { GuardianAgent } from './smartagent.classes.guardianagent.js';
-
-// Export base tool class for custom tool creation
-export { BaseToolWrapper } from './smartagent.tools.base.js';
-
-// Export standard tools
-export { FilesystemTool, type IFilesystemToolOptions } from './smartagent.tools.filesystem.js';
-export { HttpTool } from './smartagent.tools.http.js';
-export { ShellTool } from './smartagent.tools.shell.js';
-export { BrowserTool } from './smartagent.tools.browser.js';
-export { DenoTool, type TDenoPermission } from './smartagent.tools.deno.js';
-export { JsonValidatorTool } from './smartagent.tools.json.js';
-
-// Export all interfaces
-export * from './smartagent.interfaces.js';
-
-// Re-export useful types from smartai
-export {
-  type ISmartAiOptions,
-  type TProvider,
-  type ChatMessage,
-  type ChatOptions,
-  type ChatResponse,
-} from '@push.rocks/smartai';
+export { runAgent } from './smartagent.classes.agent.js';
+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';
+
+// Re-export tool() and z so consumers can define tools without extra imports
+export { tool, jsonSchema } from '@push.rocks/smartai';
+export { z } from 'zod';
+export { stepCountIs } from 'ai';

package/ts/plugins.ts

@@ -3,24 +3,25 @@ import * as path from 'path';
 
 export { path };
 
-// third party
-import { minimatch } from 'minimatch';
-
-export { minimatch };
-
-// @push.rocks scope
-import * as smartai from '@push.rocks/smartai';
-import * as smartdeno from '@push.rocks/smartdeno';
-import * as smartfs from '@push.rocks/smartfs';
-import * as smartrequest from '@push.rocks/smartrequest';
-import * as smartbrowser from '@push.rocks/smartbrowser';
-import * as smartshell from '@push.rocks/smartshell';
-
-export {
-  smartai,
-  smartdeno,
-  smartfs,
-  smartrequest,
-  smartbrowser,
-  smartshell,
-};
+// ai-sdk core
+import { streamText, generateText, stepCountIs } from 'ai';
+
+export { streamText, generateText, stepCountIs };
+
+export type {
+  ModelMessage,
+  ToolSet,
+  StreamTextResult,
+} from 'ai';
+
+// @push.rocks/smartai
+import { tool, jsonSchema } from '@push.rocks/smartai';
+
+export { tool, jsonSchema };
+
+export type { LanguageModelV3 } from '@push.rocks/smartai';
+
+// zod
+import { z } from 'zod';
+
+export { z };

package/ts/smartagent.classes.agent.ts

@@ -0,0 +1,198 @@
+// 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 { ContextOverflowError } from './smartagent.interfaces.js';
+
+// Retry constants
+const RETRY_INITIAL_DELAY = 2000;
+const RETRY_BACKOFF_FACTOR = 2;
+const RETRY_MAX_DELAY = 30_000;
+const MAX_RETRY_ATTEMPTS = 8;
+
+function retryDelay(attempt: number, headers?: Record<string, string>): number {
+  if (headers) {
+    const ms = headers['retry-after-ms'];
+    if (ms) {
+      const n = parseFloat(ms);
+      if (!isNaN(n)) return n;
+    }
+    const after = headers['retry-after'];
+    if (after) {
+      const secs = parseFloat(after);
+      if (!isNaN(secs)) return Math.ceil(secs * 1000);
+      const date = Date.parse(after) - Date.now();
+      if (!isNaN(date) && date > 0) return Math.ceil(date);
+    }
+  }
+  return Math.min(
+    RETRY_INITIAL_DELAY * Math.pow(RETRY_BACKOFF_FACTOR, attempt - 1),
+    RETRY_MAX_DELAY,
+  );
+}
+
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(t);
+        reject(new DOMException('Aborted', 'AbortError'));
+      },
+      { once: true },
+    );
+  });
+}
+
+function isRetryableError(err: unknown): boolean {
+  const status = (err as any)?.status ?? (err as any)?.statusCode;
+  if (status === 429 || status === 529 || status === 503) return true;
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    if (msg.includes('rate limit') || msg.includes('overloaded') || msg.includes('too many requests')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isContextOverflow(err: unknown): boolean {
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    return (
+      msg.includes('context_length_exceeded') ||
+      msg.includes('context window') ||
+      msg.includes('maximum context length') ||
+      msg.includes('too many tokens') ||
+      msg.includes('input is too long') ||
+      (err as any)?.name === 'AI_ContextWindowExceededError'
+    );
+  }
+  return false;
+}
+
+export async function runAgent(options: IAgentRunOptions): Promise<IAgentRunResult> {
+  let stepCount = 0;
+  let attempt = 0;
+  let totalInput = 0;
+  let totalOutput = 0;
+
+  const tools = options.tools ?? {};
+
+  // Add a no-op sink for repaired-but-unrecognised tool calls
+  const allTools: plugins.ToolSet = {
+    ...tools,
+    invalid: plugins.tool({
+      description: 'Sink for unrecognised tool calls — returns an error message to the model',
+      inputSchema: plugins.z.object({
+        tool: plugins.z.string(),
+        error: plugins.z.string(),
+      }),
+      execute: async ({ tool, error }: { tool: string; error: string }) =>
+        `Unknown tool "${tool}": ${error}`,
+    }),
+  };
+
+  // Build messages — streamText requires either prompt OR messages, not both
+  let messages: plugins.ModelMessage[] = options.messages
+    ? [...options.messages, { role: 'user' as const, content: options.prompt }]
+    : [{ role: 'user' as const, content: options.prompt }];
+
+  while (true) {
+    try {
+      const result = plugins.streamText({
+        model: options.model,
+        system: options.system,
+        messages,
+        tools: allTools,
+        stopWhen: plugins.stepCountIs(options.maxSteps ?? 20),
+        maxRetries: 0, // handled manually below
+        abortSignal: options.abort,
+
+        experimental_repairToolCall: async ({ toolCall, tools: availableTools, error }) => {
+          const lower = toolCall.toolName.toLowerCase();
+          if (lower !== toolCall.toolName && (availableTools as any)[lower]) {
+            return { ...toolCall, toolName: lower };
+          }
+          return {
+            ...toolCall,
+            toolName: 'invalid',
+            args: JSON.stringify({
+              tool: toolCall.toolName,
+              error: String(error),
+            }),
+          };
+        },
+
+        onChunk: ({ chunk }) => {
+          if (chunk.type === 'text-delta' && options.onToken) {
+            options.onToken((chunk as any).textDelta ?? (chunk as any).text ?? '');
+          }
+        },
+
+        experimental_onToolCallStart: options.onToolCall
+          ? ({ toolCall }) => {
+              options.onToolCall!(toolCall.toolName, (toolCall as any).input ?? (toolCall as any).args);
+            }
+          : undefined,
+
+        experimental_onToolCallFinish: options.onToolResult
+          ? ({ toolCall }) => {
+              options.onToolResult!(toolCall.toolName, (toolCall as any).result);
+            }
+          : undefined,
+
+        onStepFinish: ({ usage }) => {
+          stepCount++;
+          totalInput += usage?.inputTokens ?? 0;
+          totalOutput += usage?.outputTokens ?? 0;
+        },
+      });
+
+      // Consume the stream and collect results
+      const text = await result.text;
+      const finishReason = await result.finishReason;
+      const responseData = await result.response;
+
+      attempt = 0; // reset on success
+
+      return {
+        text,
+        messages: responseData.messages as plugins.ModelMessage[],
+        steps: stepCount,
+        finishReason,
+        usage: {
+          inputTokens: totalInput,
+          outputTokens: totalOutput,
+          totalTokens: totalInput + totalOutput,
+        },
+      };
+    } catch (err: unknown) {
+      // Abort — don't retry
+      if (err instanceof DOMException && err.name === 'AbortError') throw err;
+
+      // Rate limit / overload — retry with backoff
+      if (isRetryableError(err) && attempt < MAX_RETRY_ATTEMPTS) {
+        attempt++;
+        const headers = (err as any)?.responseHeaders ?? (err as any)?.headers;
+        const delay = retryDelay(attempt, headers);
+        await sleep(delay, options.abort);
+        continue;
+      }
+
+      // Context overflow — compact and retry if handler provided
+      if (isContextOverflow(err)) {
+        if (!options.onContextOverflow) throw new ContextOverflowError();
+        messages = await options.onContextOverflow(messages);
+        continue;
+      }
+
+      throw err;
+    }
+  }
+}

package/ts/smartagent.classes.toolregistry.ts

@@ -0,0 +1,20 @@
+import type { ToolSet } from './plugins.js';
+
+export class ToolRegistry {
+  private tools: ToolSet = {};
+
+  /**
+   * Register a tool.
+   * @param name  Tool name (must be unique, snake_case recommended)
+   * @param def   Tool definition created with ai-sdk's tool() helper
+   */
+  public register(name: string, def: ToolSet[string]): this {
+    this.tools[name] = def;
+    return this;
+  }
+
+  /** Get the full ToolSet for passing to runAgent */
+  public getTools(): ToolSet {
+    return { ...this.tools };
+  }
+}

package/ts/smartagent.interfaces.ts

@@ -1,306 +1,54 @@
-import * as plugins from './plugins.js';
-
-// ================================
-// Task Run Options
-// ================================
-
-/**
- * Options for running a task with the DualAgentOrchestrator
- */
-export interface ITaskRunOptions {
-  /** Base64-encoded images to include with the task (for vision-capable models) */
-  images?: string[];
-}
-
-// ================================
-// Agent Configuration Interfaces
-// ================================
-
-/**
- * Configuration options for the DualAgentOrchestrator
- */
-export interface IDualAgentOptions extends plugins.smartai.ISmartAiOptions {
-  /** Existing SmartAi instance to reuse (avoids creating duplicate providers) */
-  smartAiInstance?: plugins.smartai.SmartAi;
-  /** Name of the agent system */
-  name?: string;
-  /** Default AI provider for both Driver and Guardian */
-  defaultProvider?: plugins.smartai.TProvider;
-  /** Optional separate provider for Guardian (for cost optimization) */
-  guardianProvider?: plugins.smartai.TProvider;
-  /** System message for the Driver agent */
-  driverSystemMessage?: string;
-  /** Policy prompt for the Guardian agent - REQUIRED */
-  guardianPolicyPrompt: string;
-  /** Maximum iterations for task completion (default: 20) */
-  maxIterations?: number;
-  /** Maximum consecutive rejections before aborting (default: 3) */
-  maxConsecutiveRejections?: number;
-  /** Enable verbose logging */
-  verbose?: boolean;
-  /** Maximum characters for tool result output before truncation (default: 15000). Set to 0 to disable. */
-  maxResultChars?: number;
-  /** Maximum history messages to pass to API (default: 20). Set to 0 for unlimited. */
-  maxHistoryMessages?: number;
-  /** Optional callback for live progress updates during execution */
-  onProgress?: (event: IProgressEvent) => void;
-  /** Prefix for log messages (e.g., "[README]", "[Commit]"). Default: empty */
-  logPrefix?: string;
-  /** Callback fired for each token during LLM generation (streaming mode) */
-  onToken?: (token: string, source: 'driver' | 'guardian') => void;
+import type { ToolSet, ModelMessage, LanguageModelV3 } from './plugins.js';
+
+export interface IAgentRunOptions {
+  /** The LanguageModelV3 to use — from smartai.getModel() */
+  model: LanguageModelV3;
+  /** Initial user message or task description */
+  prompt: string;
+  /** System prompt override */
+  system?: string;
+  /** Tools available to the agent */
+  tools?: ToolSet;
   /**
-   * Enable native tool calling mode (default: false)
-   * When enabled, uses Ollama's native tool calling API instead of XML parsing
-   * This is more efficient for models that support it (e.g., GPT-OSS with Harmony format)
+   * Maximum number of LLM↔tool round trips.
+   * Each step may execute multiple tools in parallel.
+   * Default: 20
    */
-  useNativeToolCalling?: boolean;
-}
-
-// ================================
-// Message Interfaces
-// ================================
-
-/**
- * Represents a message in the agent's conversation history
- */
-export interface IAgentMessage {
-  role: 'system' | 'user' | 'assistant' | 'tool' | 'guardian';
-  content: string;
-  toolName?: string;
-  toolResult?: unknown;
-  toolCall?: IToolCallProposal;
-  guardianDecision?: IGuardianDecision;
-  timestamp?: Date;
-}
-
-// ================================
-// Tool Interfaces
-// ================================
-
-/**
- * Represents an action that a tool can perform
- */
-export interface IToolAction {
-  /** Action name (e.g., 'read', 'write', 'delete') */
-  name: string;
-  /** Description of what this action does */
-  description: string;
-  /** JSON schema for action parameters */
-  parameters: Record<string, unknown>;
-}
-
-/**
- * Native tool call from provider (matches Ollama's tool calling format)
- * Format: function name is "toolName_actionName" (e.g., "json_validate")
- */
-export interface INativeToolCall {
-  function: {
-    name: string;  // Format: "toolName_actionName"
-    arguments: Record<string, unknown>;
-    index?: number;
-  };
-}
-
-/**
- * Proposed tool call from the Driver
- */
-export interface IToolCallProposal {
-  /** Unique ID for this proposal */
-  proposalId: string;
-  /** Name of the tool */
-  toolName: string;
-  /** Specific action to perform */
-  action: string;
-  /** Parameters for the action */
-  params: Record<string, unknown>;
-  /** Driver's reasoning for this call */
-  reasoning?: string;
-}
-
-/**
- * Result of tool execution
- */
-export interface IToolExecutionResult {
-  success: boolean;
-  result?: unknown;
-  error?: string;
-  /** Optional human-readable summary for history (if provided, used instead of full result) */
-  summary?: string;
-}
-
-/**
- * Base interface for wrapped tools
- */
-export interface IAgentToolWrapper {
-  /** Tool name */
-  name: string;
-  /** Tool description */
-  description: string;
-  /** Available actions */
-  actions: IToolAction[];
-  /** Initialize the tool */
-  initialize(): Promise<void>;
-  /** Cleanup resources */
-  cleanup(): Promise<void>;
-  /** Execute an action */
-  execute(action: string, params: Record<string, unknown>): Promise<IToolExecutionResult>;
-  /** Get a summary for Guardian review */
-  getCallSummary(action: string, params: Record<string, unknown>): string;
-}
-
-// ================================
-// Guardian Interfaces
-// ================================
-
-/**
- * Request for Guardian evaluation
- */
-export interface IGuardianEvaluationRequest {
-  /** The proposed tool call */
-  proposal: IToolCallProposal;
-  /** Current task context */
-  taskContext: string;
-  /** Recent conversation history (last N messages) */
-  recentHistory: IAgentMessage[];
-  /** Summary of what the tool call will do */
-  callSummary: string;
-}
-
-/**
- * Guardian's decision
- */
-export interface IGuardianDecision {
-  /** Approve or reject */
-  decision: 'approve' | 'reject';
-  /** Explanation of the decision */
-  reason: string;
-  /** Specific concerns if rejected */
-  concerns?: string[];
-  /** Suggestions for the Driver if rejected */
-  suggestions?: string;
-  /** Confidence level (0-1) */
-  confidence?: number;
-}
-
-// ================================
-// Result Interfaces
-// ================================
-
-/**
- * Log entry for tool executions
- */
-export interface IToolExecutionLog {
-  timestamp: Date;
-  toolName: string;
-  action: string;
-  params: Record<string, unknown>;
-  guardianDecision: 'approved' | 'rejected';
-  guardianReason: string;
-  executionResult?: unknown;
-  executionError?: string;
-}
-
-/**
- * Status of a dual-agent run
- */
-export type TDualAgentRunStatus =
-  | 'completed'
-  | 'in_progress'
-  | 'max_iterations_reached'
-  | 'max_rejections_reached'
-  | 'clarification_needed'
-  | 'error';
-
-/**
- * Result of a dual-agent run
- */
-export interface IDualAgentRunResult {
-  /** Whether the task was successful */
-  success: boolean;
-  /** Whether the task is completed */
-  completed: boolean;
-  /** Final result or response */
-  result: string;
-  /** Total iterations taken */
-  iterations: number;
-  /** Full conversation history */
-  history: IAgentMessage[];
-  /** Current status */
-  status: TDualAgentRunStatus;
-  /** Number of tool calls made */
-  toolCallCount?: number;
-  /** Number of Guardian rejections */
-  rejectionCount?: number;
-  /** Tool execution log */
-  toolLog?: IToolExecutionLog[];
-  /** Error message if status is 'error' */
-  error?: string;
-}
-
-// ================================
-// Progress Event Interfaces
-// ================================
-
-/**
- * Progress event types for live feedback during agent execution
- */
-export type TProgressEventType =
-  | 'task_started'
-  | 'iteration_started'
-  | 'tool_proposed'
-  | 'guardian_evaluating'
-  | 'tool_approved'
-  | 'tool_rejected'
-  | 'tool_executing'
-  | 'tool_completed'
-  | 'task_completed'
-  | 'clarification_needed'
-  | 'max_iterations'
-  | 'max_rejections';
-
-/**
- * Log level for progress events
- */
-export type TLogLevel = 'info' | 'warn' | 'error' | 'success';
-
-/**
- * Progress event for live feedback during agent execution
- */
-export interface IProgressEvent {
-  /** Type of progress event */
-  type: TProgressEventType;
-  /** Current iteration number */
-  iteration?: number;
-  /** Maximum iterations configured */
-  maxIterations?: number;
-  /** Name of the tool being used */
-  toolName?: string;
-  /** Action being performed */
-  action?: string;
-  /** Reason for rejection or other explanation */
-  reason?: string;
-  /** Human-readable message about the event */
-  message?: string;
-  /** Timestamp of the event */
-  timestamp: Date;
-  /** Log level for this event (info, warn, error, success) */
-  logLevel: TLogLevel;
-  /** Pre-formatted log message ready for output */
-  logMessage: string;
-}
-
-// ================================
-// Utility Types
-// ================================
-
-/**
- * Available tool names
- */
-export type TToolName = 'filesystem' | 'http' | 'browser' | 'shell';
-
-/**
- * Generate a unique proposal ID
- */
-export function generateProposalId(): string {
-  return `proposal_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  maxSteps?: number;
+  /** Prior conversation messages to include */
+  messages?: ModelMessage[];
+  /** Called for each streamed text delta */
+  onToken?: (delta: string) => 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;
+  /**
+   * Called when total token usage approaches the model's context limit.
+   * Receives the full message history and must return a compacted replacement.
+   * If not provided, runAgent throws a ContextOverflowError instead.
+   */
+  onContextOverflow?: (messages: ModelMessage[]) => Promise<ModelMessage[]>;
+  /** AbortSignal to cancel the run mid-flight */
+  abort?: AbortSignal;
+}
+
+export interface IAgentRunResult {
+  /** Final text output from the model */
+  text: string;
+  /** All messages in the completed conversation */
+  messages: ModelMessage[];
+  /** Total steps taken */
+  steps: number;
+  /** Finish reason from the final step */
+  finishReason: string;
+  /** Accumulated token usage across all steps */
+  usage: { inputTokens: number; outputTokens: number; totalTokens: number };
+}
+
+export class ContextOverflowError extends Error {
+  constructor(message = 'Agent context limit reached and no onContextOverflow handler provided') {
+    super(message);
+    this.name = 'ContextOverflowError';
+  }
 }