@gugacoder/agentic-sdk 0.2.0

package/src/tools/web-search.ts

@@ -0,0 +1,75 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const MAX_OUTPUT = 50_000;
+
+/**
+ * A single search result returned by a WebSearch provider.
+ */
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+/**
+ * Callback type for pluggable web search providers.
+ * Implementors receive the query and desired number of results,
+ * and return an array of WebSearchResult.
+ */
+export type WebSearchProvider = (
+  query: string,
+  numResults: number
+) => Promise<WebSearchResult[]>;
+
+/**
+ * Factory that creates the WebSearch tool with an injected search provider.
+ * If no provider is given, returns a tool that explains no provider is configured.
+ */
+export function createWebSearchTool(searchProvider?: WebSearchProvider) {
+  return tool({
+    description:
+      "Search the web and return formatted results with title, URL, and snippet. Use this to find up-to-date information, documentation, or answers to questions.",
+    inputSchema: z.object({
+      query: z.string().describe("The search query"),
+      numResults: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .optional()
+        .default(5)
+        .describe("Number of results to return (default: 5)"),
+    }),
+    execute: async ({ query, numResults }) => {
+      if (!searchProvider) {
+        return "WebSearch provider not configured. The consuming application must provide an onWebSearch callback in AiAgentOptions to enable web search.";
+      }
+
+      try {
+        const results = await searchProvider(query, numResults);
+
+        if (results.length === 0) {
+          return `No results found for: "${query}"`;
+        }
+
+        let output = `# Search results for: "${query}"\n\n`;
+
+        for (let i = 0; i < results.length; i++) {
+          const r = results[i];
+          output += `## ${i + 1}. ${r.title}\n`;
+          output += `**URL:** ${r.url}\n`;
+          output += `${r.snippet}\n\n`;
+        }
+
+        if (output.length > MAX_OUTPUT) {
+          output = output.slice(0, MAX_OUTPUT) + "\n...[truncated at 50KB]";
+        }
+
+        return output.trim();
+      } catch (err: any) {
+        return `Error searching web: ${err.message}`;
+      }
+    },
+  });
+}

package/src/tools/write.ts

@@ -0,0 +1,34 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export function createWriteTool(opts?: { autoApprove?: boolean }) {
+  const baseTool = tool({
+    description:
+      "Writes content to a file. Creates parent directories if needed. Overwrites existing files.",
+    inputSchema: z.object({
+      file_path: z.string().describe("Absolute path to the file to write"),
+      content: z.string().describe("The content to write to the file"),
+    }),
+    execute: async ({ file_path, content }) => {
+      try {
+        await mkdir(dirname(file_path), { recursive: true });
+        await writeFile(file_path, content, "utf-8");
+        return `File written successfully: ${file_path}`;
+      } catch (err: any) {
+        return `Error writing file: ${err.message}`;
+      }
+    },
+  });
+
+  if (opts?.autoApprove === false) {
+    return Object.assign(baseTool, {
+      needsApproval: async () => true as const,
+    });
+  }
+
+  return baseTool;
+}
+
+export const writeTool = createWriteTool();

package/src/types.ts

@@ -0,0 +1,145 @@
+import type { LanguageModelMiddleware } from "ai";
+
+export interface McpServerConfig {
+  name: string;
+  transport:
+    | { type: "http"; url: string; headers?: Record<string, string> }
+    | { type: "stdio"; command: string; args?: string[] };
+}
+
+export type AiAgentEvent =
+  | { type: "init"; sessionId: string }
+  | { type: "mcp_connected"; servers: string[] }
+  | { type: "text"; content: string }
+  | { type: "reasoning"; content: string }
+  | { type: "tool-call"; toolCallId: string; toolName: string; args: Record<string, unknown> }
+  | { type: "tool-result"; toolCallId: string; toolName: string; result: unknown }
+  | { type: "result"; content: string }
+  | { type: "usage"; usage: AiUsageData }
+  | { type: "ask_user"; question: string; options?: string[] }
+  | { type: "todo_update"; todos: AiTodoItem[] }
+  | { type: "context_status"; context: ContextUsage & { compacted: boolean } }
+  | { type: "step_finish"; step: number; toolCalls: string[]; finishReason: string }
+  | { type: "mcp_error"; server: string; error: string };
+
+export interface AiTodoItem {
+  id: string;
+  content: string;
+  status: "pending" | "in_progress" | "completed";
+  priority: "high" | "medium" | "low";
+}
+
+export interface AiUsageData {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadInputTokens: number;
+  cacheCreationInputTokens: number;
+  totalCostUsd: number;
+  numTurns: number;
+  durationMs: number;
+  durationApiMs: number;
+  stopReason: string;
+  /** Latencia ate o primeiro token (ms). Disponivel apenas com telemetria. */
+  timeToFirstTokenMs?: number;
+  /** Breakdown de uso por step. Disponivel apenas com telemetria. */
+  steps?: Array<{
+    stepNumber: number;
+    toolCalls: string[];
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
+  }>;
+}
+
+export interface ContextUsage {
+  model: string;
+  contextWindow: number;
+  systemPrompt: number;
+  toolDefinitions: number;
+  messages: number;
+  used: number;
+  free: number;
+  usagePercent: number;
+  compactThreshold: number;
+  willCompact: boolean;
+}
+
+export interface PrepareStepContext {
+  /** Current step number (0-indexed) */
+  stepNumber: number;
+  /** Total number of steps executed so far */
+  stepCount: number;
+  /** Tool calls from the previous step (empty on first step) */
+  previousToolCalls: string[];
+}
+
+export interface PrepareStepResult {
+  /** Switch model for this step */
+  model?: string;
+  /** Filter available tools for this step (tool names) */
+  activeTools?: string[];
+  /** Force tool choice: "auto" | "required" | "none" | specific tool */
+  toolChoice?: "auto" | "required" | "none" | { type: "tool"; toolName: string };
+}
+
+export interface AiTelemetryOptions {
+  /** Habilita tracing OpenTelemetry. Default: false */
+  enabled: boolean;
+  /** Identificador da funcao nos spans (ex: "ai-agent", "heartbeat") */
+  functionId?: string;
+  /** Metadata adicional propagada nos spans */
+  metadata?: Record<string, string>;
+}
+
+export interface AiAgentOptions {
+  model: string;
+  apiKey: string;
+  /** Provider name (e.g. "openrouter", "groq"). Default: "openrouter" */
+  provider?: string;
+  /** Additional provider configs by name (e.g. { groq: { baseURL, apiKey } }) */
+  providers?: Record<string, { baseURL: string; apiKey: string }>;
+  sessionId?: string;
+  sessionDir?: string;
+  maxSteps?: number;
+  system?: string | { append: string };
+  /** Working directory for project context discovery (AGENTS.md/CLAUDE.md). Defaults to process.cwd(). */
+  cwd?: string;
+  /** Callback invoked when the agent uses the AskUser tool. Return the user's answer. */
+  onAskUser?: (question: string, options?: string[]) => Promise<string>;
+  /** Callback invoked when the agent uses the WebSearch tool. Return search results. */
+  onWebSearch?: (query: string, numResults: number) => Promise<Array<{ title: string; url: string; snippet: string }>>;
+  /** Callback invoked when the agent uses the CodeSearch tool. Return code examples and documentation. */
+  onCodeSearch?: (query: string) => Promise<Array<{ title: string; url: string; content: string }>>;
+  /** MCP servers to connect to. Tools from these servers are merged with codingTools. */
+  mcpServers?: McpServerConfig[];
+  /** Extra Vercel AI SDK tools to merge. Useful for in-process tools that aren't MCP servers. */
+  tools?: Record<string, any>;
+  /** Override context window size (tokens) for the model. Takes precedence over the built-in model map. */
+  contextWindow?: number;
+  /** Usage percentage (0-1) at which automatic compaction triggers. Default: 0.65 */
+  compactThreshold?: number;
+  /** Disable automatic context compaction. Default: false */
+  disableCompaction?: boolean;
+  /** Custom stop condition. Complements maxSteps — whichever triggers first. */
+  stopWhen?: (event: { type: "step_finish"; step: number; toolCalls: string[]; finishReason: string }) => boolean;
+  /** Callback executed before each step. Returns overrides for model, tools, toolChoice. */
+  prepareStep?: (context: PrepareStepContext) => PrepareStepResult | undefined;
+  /** Middleware pipeline applied to the model. Executed in array order. */
+  middleware?: LanguageModelMiddleware[];
+  /** Configuracao de telemetria OpenTelemetry */
+  telemetry?: AiTelemetryOptions;
+  /** Aliases de modelo customizados: nome amigavel → model ID completo (ex: { fast: "anthropic/claude-haiku-4.5" }) */
+  modelAliases?: Record<string, string>;
+  /** Habilita reparo automatico de tool calls malformadas. Default: true */
+  repairToolCalls?: boolean;
+  /** Maximo de tentativas de reparo por tool call. Default: 1 */
+  maxRepairAttempts?: number;
+  /** Habilita reasoning (extended thinking) do modelo. true usa budget de 5000 tokens; objeto permite especificar budgetTokens. */
+  reasoning?: boolean | { budgetTokens: number };
+  /** Metadados do backbone anexados como _meta na user message */
+  messageMeta?: Record<string, unknown>;
+  /** Content parts para user message (substitui prompt como content quando presente) */
+  contentParts?: unknown[];
+  /** Desabilita display tools. Default: false (display tools habilitadas) */
+  disableDisplayTools?: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}