@gugacoder/agentic-sdk 0.2.0

package/src/session.ts

@@ -0,0 +1,110 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname, basename } from "node:path";
+import type { ModelMessage } from "ai";
+
+function sessionPath(dir: string): string {
+  return join(dir, "messages.jsonl");
+}
+
+export async function resolveRefs(
+  content: unknown[],
+  attachmentsDir: string
+): Promise<unknown[]> {
+  const resolved: unknown[] = [];
+  for (const part of content) {
+    if (typeof part !== "object" || part === null) {
+      resolved.push(part);
+      continue;
+    }
+    const p = part as Record<string, unknown>;
+    if (p._ref && (p.type === "image" || p.type === "file")) {
+      const filename = basename(p._ref as string);
+      const filePath = join(attachmentsDir, filename);
+      try {
+        const buffer = await readFile(filePath);
+        const base64 = buffer.toString("base64");
+        if (p.type === "image") {
+          resolved.push({ type: "image", image: base64, mimeType: p.mimeType, _ref: p._ref });
+        } else {
+          resolved.push({ type: "file", data: base64, mimeType: p.mimeType, _ref: p._ref });
+        }
+      } catch {
+        resolved.push({ type: "text", text: `[arquivo removido: ${filename}]` });
+      }
+    } else {
+      resolved.push(part);
+    }
+  }
+  return resolved;
+}
+
+export async function loadSession(dir: string): Promise<ModelMessage[]> {
+  try {
+    const content = await readFile(sessionPath(dir), "utf-8");
+    const messages = content
+      .split("\n")
+      .filter((line) => line.trim())
+      .map((line) => {
+        const { _meta, ...msg } = JSON.parse(line);
+        return msg as ModelMessage;
+      });
+
+    const attachmentsDir = join(dir, "attachments");
+    const result: ModelMessage[] = [];
+    for (const msg of messages) {
+      if (Array.isArray(msg.content)) {
+        const resolvedContent = await resolveRefs(msg.content, attachmentsDir);
+        result.push({ ...msg, content: resolvedContent } as ModelMessage);
+      } else {
+        result.push(msg as ModelMessage);
+      }
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+export function filterOldMedia(messages: ModelMessage[], lastUserIndex: number): ModelMessage[] {
+  return (messages as any[]).map((msg: any, i: number) => {
+    if (msg.role !== "user" || i === lastUserIndex) {
+      return msg;
+    }
+    if (!Array.isArray(msg.content)) {
+      return msg;
+    }
+    const filtered = (msg.content as unknown[]).map((part) => {
+      if (typeof part !== "object" || part === null) return part;
+      const p = part as Record<string, unknown>;
+      if (p.type === "image") {
+        const name = (p._ref as string | undefined) ?? "imagem";
+        return { type: "text", text: `[imagem enviada: ${name}]` };
+      }
+      if (p.type === "file" && p.data !== undefined) {
+        const name = (p._ref as string | undefined) ?? "arquivo";
+        return { type: "text", text: `[arquivo enviado: ${name}]` };
+      }
+      return part;
+    });
+    return { ...msg, content: filtered as ModelMessage["content"] };
+  });
+}
+
+export async function saveSession(
+  dir: string,
+  messages: (ModelMessage & { _meta?: Record<string, unknown> })[]
+): Promise<void> {
+  const filePath = sessionPath(dir);
+  await mkdir(dirname(filePath), { recursive: true });
+  const ts = new Date().toISOString();
+  const jsonl =
+    messages
+      .map((m) => {
+        if (!(m as any)._meta) {
+          return JSON.stringify({ ...m, _meta: { ts } });
+        }
+        return JSON.stringify(m);
+      })
+      .join("\n") + "\n";
+  await writeFile(filePath, jsonl, "utf-8");
+}

package/src/structured.ts

@@ -0,0 +1,65 @@
+import { generateText, streamObject, Output } from "ai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import type { z } from "zod";
+import type { createAiProviderRegistry } from "./providers.js";
+
+export interface AiObjectOptions<T extends z.ZodType> {
+  model: string;
+  apiKey: string;
+  /** Provider name (e.g. "openrouter", "groq"). Default: "openrouter" */
+  provider?: string;
+  /** Base URL override for the provider */
+  baseURL?: string;
+  schema: T;
+  system?: string;
+  prompt: string;
+  maxTokens?: number;
+  /** Provider registry para reuso. Se nao fornecido, cria um internamente (backward compat). */
+  providers?: ReturnType<typeof createAiProviderRegistry>;
+}
+
+export async function aiGenerateObject<T extends z.ZodType>(
+  options: AiObjectOptions<T>
+): Promise<z.infer<T>> {
+  const model = options.providers
+    ? options.providers.model(options.model, options.provider)
+    : createOpenAICompatible({
+        name: options.provider ?? "openrouter",
+        baseURL: options.baseURL ?? "https://openrouter.ai/api/v1",
+        apiKey: options.apiKey,
+      })(options.model);
+
+  const result = await generateText({
+    model,
+    output: Output.object({ schema: options.schema }),
+    system: options.system,
+    prompt: options.prompt,
+    maxOutputTokens: options.maxTokens,
+  });
+
+  return result.output!;
+}
+
+export async function* aiStreamObject<T extends z.ZodType>(
+  options: AiObjectOptions<T>
+): AsyncGenerator<Partial<z.infer<T>>> {
+  const model = options.providers
+    ? options.providers.model(options.model, options.provider)
+    : createOpenAICompatible({
+        name: options.provider ?? "openrouter",
+        baseURL: options.baseURL ?? "https://openrouter.ai/api/v1",
+        apiKey: options.apiKey,
+      })(options.model);
+
+  const result = streamObject({
+    model,
+    schema: options.schema,
+    system: options.system,
+    prompt: options.prompt,
+    maxOutputTokens: options.maxTokens,
+  });
+
+  for await (const partial of result.partialObjectStream) {
+    yield partial;
+  }
+}

package/src/tool-repair.ts

@@ -0,0 +1,92 @@
+import { generateText } from "ai";
+import type { LanguageModel } from "ai";
+import type { LanguageModelV3ToolCall } from "@ai-sdk/provider";
+
+export interface RepairContext {
+  model: LanguageModel;
+  maxAttempts: number;
+}
+
+/**
+ * Try to fix tool name by case-insensitive matching against available tools.
+ * Returns the correct name if found, or null.
+ */
+function fixToolName(toolName: string, tools: Record<string, unknown>): string | null {
+  if (toolName in tools) return toolName; // already correct
+  const lower = toolName.toLowerCase();
+  for (const name of Object.keys(tools)) {
+    if (name.toLowerCase() === lower) return name;
+  }
+  return null;
+}
+
+/**
+ * Cria um handler de reparo que pede ao modelo para corrigir a tool call.
+ * Primeiro tenta corrigir o nome da tool (case mismatch), depois os args.
+ * Tenta N vezes. Se todas falharem, retorna null (deixa o erro original propagar).
+ */
+export function createToolCallRepairHandler(ctx: RepairContext) {
+  const attempts = new Map<string, number>();
+
+  return async (options: {
+    toolCall: LanguageModelV3ToolCall;
+    tools: Record<string, unknown>;
+    inputSchema: (opts: { toolName: string }) => unknown;
+    error: Error;
+    system?: unknown;
+    messages?: unknown;
+  }): Promise<LanguageModelV3ToolCall | null> => {
+    const { toolCall, tools, inputSchema, error } = options;
+
+    // Fix tool name case mismatch (e.g. "Email_send" → "email_send")
+    const correctedName = fixToolName(toolCall.toolName, tools);
+    if (correctedName && correctedName !== toolCall.toolName) {
+      return {
+        type: "tool-call" as const,
+        toolCallId: toolCall.toolCallId,
+        toolName: correctedName,
+        input: toolCall.input,
+      };
+    }
+
+    const key = `${toolCall.toolName}:${toolCall.input}`;
+    const current = attempts.get(key) ?? 0;
+
+    if (current >= ctx.maxAttempts) {
+      return null; // desiste — erro original propaga
+    }
+    attempts.set(key, current + 1);
+
+    // If tool name is completely wrong, can't repair args
+    if (!correctedName) return null;
+
+    try {
+      const schema = await Promise.resolve(inputSchema({ toolName: toolCall.toolName }));
+
+      const result = await generateText({
+        model: ctx.model,
+        system: [
+          "You generated an invalid tool call. Fix the JSON arguments to match the schema.",
+          "Return ONLY the corrected JSON object — no explanation, no markdown.",
+        ].join("\n"),
+        prompt: [
+          `Tool: ${toolCall.toolName}`,
+          `Schema: ${JSON.stringify(schema)}`,
+          `Invalid args: ${toolCall.input}`,
+          `Error: ${error.message}`,
+        ].join("\n"),
+        maxOutputTokens: 1000,
+      });
+
+      const repaired = (result.text ?? toolCall.input).trim();
+      return {
+        type: "tool-call" as const,
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        input: repaired,
+      };
+    } catch {
+      return null; // reparo falhou — erro original propaga
+    }
+  };
+}

package/src/tools/api-spec.ts

@@ -0,0 +1,158 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const MAX_SPEC_SIZE = 512 * 1024; // 512KB
+
+interface EndpointInfo {
+  method: string;
+  path: string;
+  summary?: string;
+  parameters?: Array<{ name: string; in: string; required?: boolean; type?: string }>;
+  requestBody?: string;
+  responses?: Record<string, string>;
+}
+
+interface SpecSummary {
+  title: string;
+  version: string;
+  baseUrl: string;
+  auth: string[];
+  endpoints: EndpointInfo[];
+}
+
+function extractEndpoints(spec: any): EndpointInfo[] {
+  const endpoints: EndpointInfo[] = [];
+  const paths = spec.paths ?? {};
+
+  for (const [path, methods] of Object.entries(paths)) {
+    if (typeof methods !== "object" || methods === null) continue;
+
+    for (const [method, op] of Object.entries(methods as Record<string, any>)) {
+      if (["get", "post", "put", "patch", "delete", "head", "options"].indexOf(method) === -1) continue;
+
+      const endpoint: EndpointInfo = {
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary ?? op.description?.slice(0, 120),
+      };
+
+      // Parameters
+      if (Array.isArray(op.parameters) && op.parameters.length > 0) {
+        endpoint.parameters = op.parameters.map((p: any) => ({
+          name: p.name,
+          in: p.in,
+          required: p.required,
+          type: p.schema?.type ?? p.type,
+        }));
+      }
+
+      // Request body
+      if (op.requestBody) {
+        const content = op.requestBody.content;
+        if (content) {
+          const mediaType = Object.keys(content)[0];
+          endpoint.requestBody = mediaType;
+        }
+      }
+
+      // Responses
+      if (op.responses) {
+        endpoint.responses = {};
+        for (const [code, resp] of Object.entries(op.responses as Record<string, any>)) {
+          endpoint.responses[code] = resp.description?.slice(0, 80) ?? "";
+        }
+      }
+
+      endpoints.push(endpoint);
+    }
+  }
+
+  return endpoints;
+}
+
+function extractAuth(spec: any): string[] {
+  const auth: string[] = [];
+  const schemes = spec.components?.securitySchemes ?? spec.securityDefinitions ?? {};
+
+  for (const [name, scheme] of Object.entries(schemes as Record<string, any>)) {
+    const type = scheme.type ?? "unknown";
+    const loc = scheme.in ? ` (in ${scheme.in})` : "";
+    const flow = scheme.flows ? ` [${Object.keys(scheme.flows).join(", ")}]` : "";
+    auth.push(`${name}: ${type}${loc}${flow}`);
+  }
+
+  return auth;
+}
+
+function extractBaseUrl(spec: any): string {
+  // OpenAPI 3.x
+  if (Array.isArray(spec.servers) && spec.servers.length > 0) {
+    return spec.servers[0].url;
+  }
+  // Swagger 2.x
+  if (spec.host) {
+    const scheme = spec.schemes?.[0] ?? "https";
+    const basePath = spec.basePath ?? "";
+    return `${scheme}://${spec.host}${basePath}`;
+  }
+  return "unknown";
+}
+
+export const apiSpecTool = tool({
+  description:
+    "Fetches and parses an API specification (OpenAPI/Swagger JSON or YAML). Returns a structured summary of available endpoints, methods, parameters, and authentication requirements.",
+  inputSchema: z.object({
+    url: z
+      .string()
+      .describe("URL to the OpenAPI/Swagger spec (JSON or YAML)"),
+    format: z
+      .enum(["openapi", "auto"])
+      .optional()
+      .default("auto")
+      .describe("Spec format (default: auto-detect)"),
+  }),
+  execute: async ({ url }) => {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 30_000);
+
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers: { Accept: "application/json, application/yaml, text/yaml, */*" },
+      });
+      clearTimeout(timer);
+
+      if (!response.ok) {
+        return `Error: HTTP ${response.status} ${response.statusText}`;
+      }
+
+      const text = await response.text();
+      if (text.length > MAX_SPEC_SIZE) {
+        return `Error: Spec too large (${text.length} bytes, max ${MAX_SPEC_SIZE})`;
+      }
+
+      // Parse JSON (YAML support would require a dependency — JSON covers most use cases)
+      let spec: any;
+      try {
+        spec = JSON.parse(text);
+      } catch {
+        return "Error: Could not parse spec as JSON. Provide a JSON-format OpenAPI/Swagger spec URL.";
+      }
+
+      const summary: SpecSummary = {
+        title: spec.info?.title ?? "Untitled API",
+        version: spec.info?.version ?? "unknown",
+        baseUrl: extractBaseUrl(spec),
+        auth: extractAuth(spec),
+        endpoints: extractEndpoints(spec),
+      };
+
+      return JSON.stringify(summary, null, 2);
+    } catch (err: any) {
+      if (err.name === "AbortError") {
+        return "Error: Request timed out after 30s";
+      }
+      return `Error: ${err.message}`;
+    }
+  },
+});

package/src/tools/apply-patch.ts

@@ -0,0 +1,188 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFile, writeFile, unlink, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+interface PatchOperation {
+  type: "add" | "update" | "delete";
+  path: string;
+  lines: string[];
+}
+
+function parsePatch(patch: string): PatchOperation[] {
+  const lines = patch.split("\n");
+  const operations: PatchOperation[] = [];
+  let current: PatchOperation | null = null;
+  let started = false;
+
+  for (const line of lines) {
+    if (line.trim() === "*** Begin Patch") {
+      started = true;
+      continue;
+    }
+
+    if (line.trim() === "*** End Patch") {
+      if (current) operations.push(current);
+      break;
+    }
+
+    if (!started) continue;
+
+    if (line.startsWith("*** Add File: ")) {
+      if (current) operations.push(current);
+      current = { type: "add", path: line.slice("*** Add File: ".length).trim(), lines: [] };
+      continue;
+    }
+
+    if (line.startsWith("*** Update File: ")) {
+      if (current) operations.push(current);
+      current = { type: "update", path: line.slice("*** Update File: ".length).trim(), lines: [] };
+      continue;
+    }
+
+    if (line.startsWith("*** Delete File: ")) {
+      if (current) operations.push(current);
+      current = { type: "delete", path: line.slice("*** Delete File: ".length).trim(), lines: [] };
+      continue;
+    }
+
+    if (current) {
+      current.lines.push(line);
+    }
+  }
+
+  // Handle case where End Patch is missing but we have a pending operation
+  if (current && !operations.includes(current)) {
+    operations.push(current);
+  }
+
+  return operations;
+}
+
+function applyUpdate(original: string, patchLines: string[]): string {
+  const originalLines = original.split("\n");
+  const result: string[] = [];
+  let originalIdx = 0;
+
+  let i = 0;
+  while (i < patchLines.length) {
+    const line = patchLines[i];
+
+    if (line.startsWith("@@")) {
+      // Context marker — find the context line in the original to sync position
+      const contextText = line.slice(3); // skip "@@ "
+      // Advance in original until we find a line matching the context
+      while (originalIdx < originalLines.length) {
+        if (originalLines[originalIdx] === contextText) {
+          break;
+        }
+        result.push(originalLines[originalIdx]);
+        originalIdx++;
+      }
+      // Push the context line itself
+      if (originalIdx < originalLines.length) {
+        result.push(originalLines[originalIdx]);
+        originalIdx++;
+      }
+      i++;
+      continue;
+    }
+
+    if (line.startsWith("-")) {
+      // Remove line — skip it in original
+      originalIdx++;
+      i++;
+      continue;
+    }
+
+    if (line.startsWith("+")) {
+      // Add line
+      result.push(line.slice(1));
+      i++;
+      continue;
+    }
+
+    // Unrecognized line in patch — treat as context (copy from original)
+    if (line.startsWith(" ")) {
+      result.push(originalLines[originalIdx] ?? line.slice(1));
+      originalIdx++;
+    }
+    i++;
+  }
+
+  // Copy remaining original lines
+  while (originalIdx < originalLines.length) {
+    result.push(originalLines[originalIdx]);
+    originalIdx++;
+  }
+
+  return result.join("\n");
+}
+
+export function createApplyPatchTool(opts?: { autoApprove?: boolean }) {
+  const baseTool = tool({
+    description:
+      "Applies a multi-file patch in envelope format (Begin Patch / End Patch). Supports Add File (create new), Update File (apply diff with @@ context and +/- lines), and Delete File operations.",
+    inputSchema: z.object({
+      patch: z
+        .string()
+        .describe(
+          'The patch text in envelope format: "*** Begin Patch" / "*** End Patch" with "*** Add File: path", "*** Update File: path", "*** Delete File: path" sections'
+        ),
+    }),
+    execute: async ({ patch }) => {
+      try {
+        const operations = parsePatch(patch);
+
+        if (operations.length === 0) {
+          return "Error: no valid operations found in patch. Ensure the patch uses the *** Begin Patch / *** End Patch envelope format.";
+        }
+
+        const results: string[] = [];
+
+        for (const op of operations) {
+          switch (op.type) {
+            case "add": {
+              const content = op.lines
+                .filter((l) => l.startsWith("+"))
+                .map((l) => l.slice(1))
+                .join("\n");
+              await mkdir(dirname(op.path), { recursive: true });
+              await writeFile(op.path, content, "utf-8");
+              results.push(`Added: ${op.path}`);
+              break;
+            }
+
+            case "update": {
+              const original = await readFile(op.path, "utf-8");
+              const updated = applyUpdate(original, op.lines);
+              await writeFile(op.path, updated, "utf-8");
+              results.push(`Updated: ${op.path}`);
+              break;
+            }
+
+            case "delete": {
+              await unlink(op.path);
+              results.push(`Deleted: ${op.path}`);
+              break;
+            }
+          }
+        }
+
+        return `Patch applied successfully:\n${results.join("\n")}`;
+      } catch (err: any) {
+        return `Error applying patch: ${err.message}`;
+      }
+    },
+  });
+
+  if (opts?.autoApprove === false) {
+    return Object.assign(baseTool, {
+      needsApproval: async () => true as const,
+    });
+  }
+
+  return baseTool;
+}
+
+export const applyPatchTool = createApplyPatchTool();

package/src/tools/ask-user.ts

@@ -0,0 +1,40 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Callback type for the AskUser tool.
+ * The consumer (CLI, API, UI) implements this to present the question
+ * to the user and return their answer.
+ */
+export type AskUserCallback = (
+  question: string,
+  options?: string[]
+) => Promise<string>;
+
+/**
+ * Factory that creates the AskUser tool with an injected callback.
+ * If no callback is provided, returns a tool that explains no handler is configured.
+ */
+export function createAskUserTool(onAskUser?: AskUserCallback) {
+  return tool({
+    description:
+      "Ask the user a question during execution. Use this to request clarifications, preferences, or decisions before proceeding. The user will see the question and can respond.",
+    inputSchema: z.object({
+      question: z
+        .string()
+        .describe("The question to ask the user"),
+      options: z
+        .array(z.string())
+        .optional()
+        .describe("Optional list of answer choices to present to the user"),
+    }),
+    execute: async ({ question, options }) => {
+      if (!onAskUser) {
+        return "AskUser handler not configured. The consuming application must provide an onAskUser callback in AiAgentOptions to enable user interaction.";
+      }
+
+      const answer = await onAskUser(question, options);
+      return answer;
+    },
+  });
+}

package/src/tools/bash.ts

@@ -0,0 +1,51 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { exec } from "node:child_process";
+
+const MAX_OUTPUT = 30_000;
+const DEFAULT_TIMEOUT = 120_000;
+
+export function createBashTool(opts?: { autoApprove?: boolean }) {
+  const baseTool = tool({
+    description:
+      "Executes a bash command and returns stdout/stderr. Timeout defaults to 120s.",
+    inputSchema: z.object({
+      command: z.string().describe("The bash command to execute"),
+      timeout: z
+        .number()
+        .optional()
+        .describe("Timeout in milliseconds (max 600000)"),
+    }),
+    execute: async ({ command, timeout }) => {
+      const ms = Math.min(timeout ?? DEFAULT_TIMEOUT, 600_000);
+
+      return new Promise<string>((resolve) => {
+        exec(command, { timeout: ms, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+          let output = "";
+
+          if (stdout) output += stdout;
+          if (stderr) output += (output ? "\n" : "") + stderr;
+          if (err && !stdout && !stderr) {
+            output = `Error: ${err.message}`;
+          }
+
+          if (output.length > MAX_OUTPUT) {
+            output = output.slice(0, MAX_OUTPUT) + "\n...[truncated]";
+          }
+
+          resolve(output || "(no output)");
+        });
+      });
+    },
+  });
+
+  if (opts?.autoApprove === false) {
+    return Object.assign(baseTool, {
+      needsApproval: async () => true as const,
+    });
+  }
+
+  return baseTool;
+}
+
+export const bashTool = createBashTool();