@push.rocks/smartagent 1.8.0 → 3.0.0

package/ts/smartagent.interfaces.ts

@@ -1,366 +1,54 @@
-import * as plugins from './plugins.js';
-
-// ================================
-// Tool Visibility & Registry Types
-// ================================
-
-/**
- * Tool visibility mode
- * - 'initial': Conveyed to model in system prompt AND discoverable via search
- * - 'on-demand': Only discoverable via search, must be activated before use
- */
-export type TToolVisibility = 'initial' | 'on-demand';
-
-/**
- * Tool metadata for discovery and management
- */
-export interface IToolMetadata {
-  name: string;
-  description: string;
-  actions: IToolAction[];
-  visibility: TToolVisibility;
-  isActivated: boolean;
-  isInitialized: boolean;
-  tags?: string[];
-  category?: string;
-}
-
-/**
- * Options when registering a tool
- */
-export interface IToolRegistrationOptions {
-  visibility?: TToolVisibility;
-  tags?: string[];
-  category?: string;
-}
-
-/**
- * Configuration for creating an Expert (SubAgent)
- */
-export interface IExpertConfig {
-  /** Unique name for the expert */
-  name: string;
-  /** Description of the expert's capabilities */
-  description: string;
-  /** System message defining expert behavior */
-  systemMessage: string;
-  /** Guardian policy for the expert's inner agent */
-  guardianPolicy: string;
-  /** AI provider (defaults to parent's provider) */
-  provider?: plugins.smartai.TProvider;
-  /** Tools available to this expert */
-  tools?: IAgentToolWrapper[];
-  /** Max iterations for expert tasks (default: 10) */
-  maxIterations?: number;
-  /** Visibility mode (default: 'initial') */
-  visibility?: TToolVisibility;
-  /** Searchable tags */
-  tags?: string[];
-  /** Category for grouping */
-  category?: string;
-}
-
-// ================================
-// 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';
+  }
 }

package/ts/smartagent.utils.truncation.ts

@@ -0,0 +1,39 @@
+// Truncation logic derived from opencode (MIT) — https://github.com/sst/opencode
+
+const MAX_LINES = 2000;
+const MAX_BYTES = 50 * 1024; // 50 KB
+
+export interface ITruncateResult {
+  content: string;
+  truncated: boolean;
+  /** Set when truncated: describes what was dropped */
+  notice?: string;
+}
+
+export function truncateOutput(
+  text: string,
+  options?: { maxLines?: number; maxBytes?: number },
+): ITruncateResult {
+  const maxLines = options?.maxLines ?? MAX_LINES;
+  const maxBytes = options?.maxBytes ?? MAX_BYTES;
+  const lines = text.split('\n');
+  const totalBytes = Buffer.byteLength(text, 'utf-8');
+
+  if (lines.length <= maxLines && totalBytes <= maxBytes) {
+    return { content: text, truncated: false };
+  }
+
+  const out: string[] = [];
+  let bytes = 0;
+  for (let i = 0; i < lines.length && i < maxLines; i++) {
+    const size = Buffer.byteLength(lines[i], 'utf-8') + (i > 0 ? 1 : 0);
+    if (bytes + size > maxBytes) break;
+    out.push(lines[i]);
+    bytes += size;
+  }
+
+  const kept = out.length;
+  const dropped = lines.length - kept;
+  const notice = `\n[Output truncated: showing ${kept}/${lines.length} lines. ${dropped} lines omitted.]`;
+  return { content: out.join('\n') + notice, truncated: true, notice };
+}

package/ts_compaction/index.ts

@@ -0,0 +1 @@
+export { compactMessages } from './smartagent.compaction.js';

package/ts_compaction/plugins.ts

@@ -0,0 +1,6 @@
+import { generateText } from 'ai';
+
+export { generateText };
+
+export type { ModelMessage } from 'ai';
+export type { LanguageModelV3 } from '@push.rocks/smartai';

package/ts_compaction/smartagent.compaction.ts

@@ -0,0 +1,51 @@
+import * as plugins from './plugins.js';
+
+const COMPACTION_PROMPT = `Provide a detailed prompt for continuing our conversation above.
+Focus on information that would be helpful for continuing the conversation, including what we did, what we're doing, which files we're working on, and what we're going to do next.
+The summary that you construct will be used so that another agent can read it and continue the work.
+
+When constructing the summary, try to stick to this template:
+---
+## Goal
+[What goal(s) is the user trying to accomplish?]
+
+## Instructions
+- [What important instructions did the user give you that are relevant]
+
+## Discoveries
+[What notable things were learned during this conversation that would be useful for the next agent to know]
+
+## Accomplished
+[What work has been completed, what work is still in progress, and what work is left?]
+
+## Relevant files / directories
+[A structured list of relevant files that have been read, edited, or created]
+---`;
+
+/**
+ * Compacts a message history into a summary.
+ * Pass this as the onContextOverflow handler in IAgentRunOptions.
+ *
+ * @param model    The same model used by runAgent, or a cheaper small model
+ * @param messages The full message history that overflowed
+ * @returns A minimal ModelMessage[] containing the summary as context
+ */
+export async function compactMessages(
+  model: plugins.LanguageModelV3,
+  messages: plugins.ModelMessage[],
+): Promise<plugins.ModelMessage[]> {
+  const result = await plugins.generateText({
+    model,
+    messages: [
+      ...messages,
+      { role: 'user', content: COMPACTION_PROMPT },
+    ],
+  });
+
+  return [
+    {
+      role: 'user',
+      content: `[Previous conversation summary]\n\n${result.text}\n\n[End of summary. Continue from here.]`,
+    },
+  ];
+}

package/ts_tools/index.ts

@@ -0,0 +1,8 @@
+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 { httpTool } from './tool.http.js';
+export { jsonTool } from './tool.json.js';
+export { truncateOutput } from './plugins.js';
+export type { ITruncateResult } from './plugins.js';

package/ts_tools/plugins.ts

@@ -0,0 +1,30 @@
+// node native
+import * as path from 'path';
+import * as fs from 'fs';
+
+export { path, fs };
+
+// zod
+import { z } from 'zod';
+
+export { z };
+
+// ai-sdk
+import { tool } from '@push.rocks/smartai';
+
+export { tool };
+
+export type { ToolSet } from 'ai';
+
+// @push.rocks scope
+import * as smartfs from '@push.rocks/smartfs';
+import * as smartshell from '@push.rocks/smartshell';
+import * as smartrequest from '@push.rocks/smartrequest';
+
+export { smartfs, smartshell, smartrequest };
+
+// cross-folder import
+import { truncateOutput } from '../ts/smartagent.utils.truncation.js';
+
+export { truncateOutput };
+export type { ITruncateResult } from '../ts/smartagent.utils.truncation.js';

package/ts_tools/tool.filesystem.ts

@@ -0,0 +1,131 @@
+import * as plugins from './plugins.js';
+
+export interface IFilesystemToolOptions {
+  /** Restrict file access to this directory. Default: process.cwd() */
+  rootDir?: string;
+}
+
+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 function filesystemTool(options?: IFilesystemToolOptions): plugins.ToolSet {
+  const rootDir = options?.rootDir;
+
+  return {
+    read_file: plugins.tool({
+      description:
+        'Read file contents. Returns the full text or a specified line range.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('Absolute path to the file'),
+        startLine: plugins.z
+          .number()
+          .optional()
+          .describe('First line (1-indexed, inclusive)'),
+        endLine: plugins.z
+          .number()
+          .optional()
+          .describe('Last line (1-indexed, inclusive)'),
+      }),
+      execute: async ({
+        path: filePath,
+        startLine,
+        endLine,
+      }: {
+        path: string;
+        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;
+        }
+
+        return plugins.truncateOutput(content).content;
+      },
+    }),
+
+    write_file: plugins.tool({
+      description:
+        'Write content to a file (creates parent dirs if needed, overwrites existing).',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('Absolute path to the file'),
+        content: plugins.z.string().describe('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}`;
+      },
+    }),
+
+    list_directory: plugins.tool({
+      description: 'List files and directories at the given path.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('Directory path to list'),
+        recursive: plugins.z
+          .boolean()
+          .optional()
+          .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;
+        }
+
+        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}`;
+      },
+    }),
+  };
+}