@gugacoder/agentic-sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,201 @@
+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/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gugacoder/agentic-sdk",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@ai-sdk/groq": "^3.0.31",
+    "@ai-sdk/mcp": "^1.0.22",
+    "@ai-sdk/openai-compatible": "^2",
+    "ai": "^6",
+    "fast-glob": "^3",
+    "js-tiktoken": "^1.0.21",
+    "zod": "^3"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:codrstudio/agentic-sdk.git"
+  },
+  "license": "MIT"
+}