agentblit 0.0.1

package/dist/index.js

@@ -0,0 +1,720 @@
+// src/agent.ts
+import OpenAI from "openai";
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/memory.ts
+var ChatMemory = class {
+  messagesStore = [];
+  maxHistory;
+  summarizeFn;
+  constructor(options) {
+    const maxHistory = options?.maxHistory ?? 5;
+    if (maxHistory < 1) {
+      throw new Error("maxHistory must be at least 1");
+    }
+    this.maxHistory = maxHistory;
+    this.summarizeFn = options?.summarizeFn;
+  }
+  get messages() {
+    return [...this.messagesStore];
+  }
+  append(message) {
+    this.messagesStore.push(message);
+  }
+  extend(messages) {
+    this.messagesStore.push(...messages);
+  }
+  clear() {
+    this.messagesStore.length = 0;
+  }
+  async buildMessagesForLLM(systemPrompt) {
+    const out = [{ role: "system", content: systemPrompt }];
+    if (this.messagesStore.length <= this.maxHistory) {
+      out.push(...this.messagesStore);
+      return out;
+    }
+    const older = this.messagesStore.slice(0, -this.maxHistory);
+    const recent = this.messagesStore.slice(-this.maxHistory);
+    let summaryText;
+    if (!this.summarizeFn) {
+      summaryText = `[Earlier conversation truncated: ${older.length} message(s) not shown. Provide summarizeFn on Agent to compress older context with the LLM.]`;
+    } else {
+      summaryText = await this.summarizeFn(older);
+    }
+    out.push({
+      role: "system",
+      content: `Summary of earlier conversation:
+${summaryText}`
+    });
+    out.push(...recent);
+    return out;
+  }
+};
+
+// src/utils.ts
+import process from "process";
+import { randomUUID } from "crypto";
+var LOGGER_PREFIX = "[agentblit]";
+var DebugLogger = class {
+  constructor(enabled) {
+    this.enabled = enabled;
+  }
+  enabled;
+  log(message, ...args) {
+    if (!this.enabled) {
+      return;
+    }
+    console.debug(`${LOGGER_PREFIX} ${message}`, ...args);
+  }
+  logLLMRequest(model, messageCount, toolCount) {
+    this.log("LLM request model=%s messages=%s tools=%s", model, messageCount, toolCount);
+  }
+  logToolCalls(calls) {
+    this.log("Tool calls: %s", jsonDumpsSafe(calls));
+  }
+  logToolResult(toolCallId, ok, preview) {
+    this.log("Tool result id=%s ok=%s preview=%s", toolCallId, ok, preview.slice(0, 500));
+  }
+};
+function jsonDumpsSafe(obj) {
+  return JSON.stringify(obj, (_key, value) => {
+    if (value instanceof Error) {
+      return {
+        name: value.name,
+        message: value.message,
+        stack: value.stack
+      };
+    }
+    return value;
+  });
+}
+function extractParamNames(fn) {
+  const source = fn.toString();
+  const match = source.match(/\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  const rawParams = match[1] ?? "";
+  return rawParams.split(",").map((segment) => segment.trim()).filter(Boolean).map((segment) => segment.replace(/=[\s\S]*$/, "").trim()).map((segment) => segment.replace(/^\.{3}/, "")).filter((segment) => segment !== "this");
+}
+function functionToToolSchema(fn, explicitSchema) {
+  if (explicitSchema) {
+    return explicitSchema;
+  }
+  const properties = Object.fromEntries(
+    extractParamNames(fn).map((name) => [name, { type: "string" }])
+  );
+  const required = Object.keys(properties);
+  return {
+    type: "object",
+    properties,
+    ...required.length > 0 ? { required } : {}
+  };
+}
+var TOOL_META = /* @__PURE__ */ Symbol.for("agentblit.tool.meta");
+function setToolMetadata(fn, options) {
+  const metadata = {
+    name: options.name ?? fn.name,
+    description: options.description ?? "",
+    permissionMode: options.permissionMode ?? "always_allow",
+    inputSchema: options.inputSchema
+  };
+  fn[TOOL_META] = metadata;
+  return fn;
+}
+function getToolMetadata(fn) {
+  return fn[TOOL_META];
+}
+function nowIsoTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function randomId(prefix) {
+  return `${prefix}_${randomUUID().replace(/-/g, "")}`;
+}
+function readStdinLine(promptText) {
+  return new Promise((resolve) => {
+    process.stdout.write(promptText);
+    process.stdin.resume();
+    process.stdin.once("data", (chunk) => {
+      resolve(String(chunk).trim());
+    });
+  });
+}
+
+// src/tools.ts
+function tool(arg1, arg2) {
+  if (typeof arg1 === "function") {
+    return setToolMetadata(arg1, arg2 ?? {});
+  }
+  return (fn) => setToolMetadata(fn, arg1);
+}
+var ToolRegistry = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  remote = /* @__PURE__ */ new Map();
+  custom = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.timeout = options.timeout ?? 3e4;
+  }
+  register(fn) {
+    const metadata = getToolMetadata(fn);
+    const name = metadata?.name ?? fn.name;
+    const description = metadata?.description ?? "";
+    const permissionMode = metadata?.permissionMode ?? "always_allow";
+    const inputSchema = functionToToolSchema(fn, metadata?.inputSchema);
+    this.custom.set(name, {
+      name,
+      description,
+      inputSchema,
+      permissionMode,
+      handler: fn
+    });
+  }
+  async refreshRemote() {
+    const url = `${this.baseUrl}/api/tools/list`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { "X-API-Key": this.apiKey },
+      signal: AbortSignal.timeout(this.timeout)
+    });
+    if (!response.ok) {
+      throw new Error(
+        `AgentBlit request failed for GET '${url}': ${response.status} ${response.statusText}`
+      );
+    }
+    const data = await response.json();
+    if (!data.ok) {
+      throw new Error("tools/list returned ok=false");
+    }
+    this.remote.clear();
+    for (const toolItem of data.tools ?? []) {
+      const name = String(toolItem.name ?? "");
+      if (!name) {
+        continue;
+      }
+      this.remote.set(name, {
+        name,
+        description: String(toolItem.description ?? ""),
+        inputSchema: toolItem.inputSchema ?? {
+          type: "object",
+          properties: {}
+        },
+        permissionMode: String(toolItem.permissionMode ?? "always_allow") === "needs_approval" ? "needs_approval" : "always_allow",
+        outputSchema: toolItem.outputSchema
+      });
+    }
+  }
+  merged() {
+    const merged = new Map(this.remote);
+    for (const [name, def] of this.custom.entries()) {
+      merged.set(name, def);
+    }
+    return merged;
+  }
+  getDefinition(name) {
+    return this.merged().get(name);
+  }
+  toOpenAITools() {
+    return [...this.merged().values()].map((definition) => ({
+      type: "function",
+      function: {
+        name: definition.name,
+        description: definition.description,
+        parameters: definition.inputSchema
+      }
+    }));
+  }
+  async ensureApproval(definition, toolName, args, approvalCallback) {
+    if (definition.permissionMode !== "needs_approval") {
+      return true;
+    }
+    if (approvalCallback) {
+      return approvalCallback(toolName, args);
+    }
+    const answer = await readStdinLine(
+      `Approve tool "${toolName}" with args ${jsonDumpsSafe(args)}? [y/N]: `
+    );
+    return ["y", "yes"].includes(answer.toLowerCase());
+  }
+  async execute(toolCallId, toolName, argumentsJson, approvalCallback) {
+    const definition = this.getDefinition(toolName);
+    if (!definition) {
+      return jsonDumpsSafe({ error: `Unknown tool: ${toolName}` });
+    }
+    let args;
+    try {
+      args = argumentsJson ? JSON.parse(argumentsJson) : {};
+    } catch (error) {
+      return jsonDumpsSafe({ error: `Invalid JSON arguments: ${String(error)}` });
+    }
+    if (!await this.ensureApproval(definition, toolName, args, approvalCallback)) {
+      return jsonDumpsSafe({ error: "User denied approval for this tool call." });
+    }
+    if (definition.handler) {
+      try {
+        let result2;
+        try {
+          result2 = await definition.handler(...Object.values(args));
+        } catch {
+          result2 = await definition.handler(args);
+        }
+        return jsonDumpsSafe(result2);
+      } catch (error) {
+        return jsonDumpsSafe({ error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    const payload = {
+      tool_calls: [
+        {
+          id: toolCallId,
+          type: "function",
+          function: {
+            name: toolName,
+            arguments: jsonDumpsSafe(args)
+          }
+        }
+      ]
+    };
+    const url = `${this.baseUrl}/api/tools/call`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-API-Key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: jsonDumpsSafe(payload),
+      signal: AbortSignal.timeout(this.timeout)
+    });
+    if (!response.ok) {
+      throw new Error(
+        `AgentBlit request failed for POST '${url}': ${response.status} ${response.statusText}`
+      );
+    }
+    const data = await response.json();
+    if (!data.ok) {
+      return jsonDumpsSafe({ error: data });
+    }
+    const result = (data.results ?? []).find((item) => item.tool_call_id === toolCallId);
+    if (!result) {
+      return jsonDumpsSafe({ error: "No result for tool_call_id" });
+    }
+    const toolResult = result.result;
+    if (!toolResult) {
+      return jsonDumpsSafe({ error: "Missing tool result payload" });
+    }
+    if (toolResult.isError) {
+      const text2 = (toolResult.content ?? []).map((part) => part.text ?? "").join("");
+      return jsonDumpsSafe({ error: text2 || "Tool error" });
+    }
+    if (typeof toolResult.structuredContent !== "undefined") {
+      return jsonDumpsSafe(toolResult.structuredContent);
+    }
+    const text = (toolResult.content ?? []).map((part) => part.text ?? "").join("");
+    return jsonDumpsSafe({ result: text });
+  }
+};
+
+// src/agent.ts
+var VENDOR_BASE_URLS = {
+  openai: "https://api.openai.com/v1",
+  anthropic: "https://api.anthropic.com/v1",
+  gemini: "https://generativelanguage.googleapis.com/v1beta/openai",
+  openrouter: "https://openrouter.ai/api/v1"
+};
+var DEFAULT_TOOL_USAGE_INSTRUCTION = "Use tools when they help answer accurately.";
+function resolveVendorAndModel(modelInput) {
+  const model = modelInput.trim();
+  if (!model || !model.includes("/")) {
+    throw new Error(
+      "model must be in the format 'vendor/model', for example 'openai/gpt-4o-mini'."
+    );
+  }
+  const [vendorRaw, ...rest] = model.split("/");
+  const vendor = (vendorRaw ?? "").trim().toLowerCase();
+  const providerModel = rest.join("/").trim();
+  if (!vendor || !providerModel) {
+    throw new Error(
+      "model must be in the format 'vendor/model', for example 'openai/gpt-4o-mini'."
+    );
+  }
+  return { vendor, model: providerModel };
+}
+function resolveLlmUrl(vendor) {
+  const url = VENDOR_BASE_URLS[vendor];
+  if (!url) {
+    const supported = Object.keys(VENDOR_BASE_URLS).sort().join(", ");
+    throw new Error(`Unsupported model vendor '${vendor}'. Supported vendors: ${supported}.`);
+  }
+  return url;
+}
+function composeSystemPrompt(systemPrompt) {
+  const userPrompt = systemPrompt.trim();
+  if (userPrompt.toLowerCase().includes(DEFAULT_TOOL_USAGE_INSTRUCTION.toLowerCase())) {
+    return userPrompt;
+  }
+  if (!userPrompt) {
+    return DEFAULT_TOOL_USAGE_INSTRUCTION;
+  }
+  return `${userPrompt}
+
+${DEFAULT_TOOL_USAGE_INSTRUCTION}`;
+}
+function formatMessagesForSummary(messages) {
+  return messages.map((message, index) => {
+    if (message.role === "assistant" && message.tool_calls) {
+      return `[${index}] assistant (tool_calls): ${jsonDumpsSafe(message.tool_calls)}`;
+    }
+    return `[${index}] ${message.role}: ${message.content ?? ""}`;
+  }).join("\n");
+}
+var Agent = class {
+  vendor;
+  model;
+  llmUrl;
+  agentId;
+  sessionId;
+  config;
+  memory;
+  client;
+  tools;
+  systemPrompt;
+  timeout;
+  debug;
+  approvalCallback;
+  maxToolRounds;
+  eventBaseUrl;
+  eventApiKey;
+  pendingCustomEvents = [];
+  agentInitSent = false;
+  toolsSignature;
+  constructor(options) {
+    const agentblitApiKey = options.agentblitApiKey.trim();
+    if (!agentblitApiKey) {
+      throw new Error("agentblitApiKey is required");
+    }
+    const maxHistory = options.maxHistory ?? 5;
+    if (maxHistory < 1) {
+      throw new Error("maxHistory must be at least 1");
+    }
+    const maxToolRounds = options.maxToolRounds ?? 25;
+    if (maxToolRounds < 1) {
+      throw new Error("maxToolRounds must be at least 1");
+    }
+    const { vendor, model } = resolveVendorAndModel(options.model);
+    const llmUrl = resolveLlmUrl(vendor);
+    const timeoutSeconds = options.timeout ?? 30;
+    const timeoutMs = timeoutSeconds * 1e3;
+    const agentblitUrl = (options.agentblitUrl ?? "https://console.agentblit.com").replace(/\/$/, "");
+    const systemPrompt = composeSystemPrompt(options.systemPrompt ?? "");
+    this.vendor = vendor;
+    this.model = model;
+    this.llmUrl = llmUrl;
+    this.systemPrompt = systemPrompt;
+    this.timeout = timeoutMs;
+    this.approvalCallback = options.approvalCallback;
+    this.maxToolRounds = maxToolRounds;
+    this.agentId = randomUUID2();
+    this.sessionId = randomUUID2();
+    this.eventBaseUrl = agentblitUrl;
+    this.eventApiKey = agentblitApiKey;
+    this.debug = new DebugLogger(Boolean(options.debug));
+    this.client = new OpenAI({
+      apiKey: options.apiKey,
+      baseURL: llmUrl,
+      timeout: timeoutMs
+    });
+    this.tools = new ToolRegistry({
+      baseUrl: agentblitUrl,
+      apiKey: agentblitApiKey,
+      timeout: timeoutMs
+    });
+    for (const customTool of options.customTools ?? []) {
+      this.registerTool(customTool);
+    }
+    this.memory = new ChatMemory({
+      maxHistory,
+      summarizeFn: (older) => this.summarizeOlderMessages(older)
+    });
+    this.config = Object.freeze({
+      model: this.model,
+      vendor: this.vendor,
+      llmUrl: this.llmUrl,
+      agentblitUrl: this.eventBaseUrl,
+      systemPrompt: this.systemPrompt,
+      maxHistory,
+      debug: Boolean(options.debug),
+      timeout: timeoutSeconds,
+      agentId: this.agentId,
+      sessionId: this.sessionId
+    });
+  }
+  registerTool(fn) {
+    this.tools.register(fn);
+  }
+  track(eventType, properties) {
+    this.pendingCustomEvents.push(this.makeEvent({ eventType, data: properties }));
+  }
+  makeEvent(input) {
+    return {
+      id: randomId("evt"),
+      session_id: this.sessionId,
+      agent_id: this.agentId,
+      timestamp: nowIsoTimestamp(),
+      type: input.eventType,
+      data: input.data,
+      tokens: Math.max(0, Math.trunc(input.tokens ?? 0)),
+      latency_ms: Math.max(0, Math.trunc(input.latencyMs ?? 0))
+    };
+  }
+  async flushEvents(events) {
+    if (events.length === 0) {
+      return;
+    }
+    const url = `${this.eventBaseUrl}/api/events/batch`;
+    this.debug.log("Event batch send start url=%s count=%s", url, events.length);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "X-API-Key": this.eventApiKey,
+          "Content-Type": "application/json"
+        },
+        body: jsonDumpsSafe({ events }),
+        signal: AbortSignal.timeout(this.timeout)
+      });
+      if (!response.ok) {
+        const body = (await response.text()).slice(0, 1e3);
+        this.debug.log(
+          "Failed to send events batch status=%s body=%s",
+          response.status,
+          body
+        );
+        return;
+      }
+      this.debug.log("Event batch send success status=%s count=%s", response.status, events.length);
+    } catch (error) {
+      this.debug.log("Failed to send events batch: %s", String(error));
+    }
+  }
+  extractLlmEventMessages(messages) {
+    if (messages.length === 0) {
+      return [];
+    }
+    const summaryMessage = messages.find(
+      (message) => message.role === "system" && typeof message.content === "string" && message.content.startsWith("Summary of earlier conversation:")
+    );
+    const lastMessage = messages[messages.length - 1];
+    if (!lastMessage) {
+      return [];
+    }
+    if (!summaryMessage) {
+      return [lastMessage];
+    }
+    if (summaryMessage === lastMessage) {
+      return [summaryMessage];
+    }
+    return [summaryMessage, lastMessage];
+  }
+  async summarizeOlderMessages(older) {
+    const text = formatMessagesForSummary(older);
+    this.debug.log("Summarizing %s older messages", older.length);
+    const response = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [
+        {
+          role: "system",
+          content: "Summarize the conversation excerpt below for use as memory. Preserve key facts, decisions, and tool outcomes. Be concise."
+        },
+        { role: "user", content: text }
+      ],
+      temperature: 0.2
+    });
+    return response.choices[0]?.message?.content?.trim() ?? "";
+  }
+  async *run(userMessage) {
+    const events = [...this.pendingCustomEvents];
+    this.pendingCustomEvents.length = 0;
+    try {
+      this.memory.append({ role: "user", content: userMessage });
+      await this.tools.refreshRemote();
+      const openaiTools = this.tools.toOpenAITools();
+      const toolsSignature = jsonDumpsSafe(openaiTools);
+      if (!this.agentInitSent) {
+        events.push(
+          this.makeEvent({
+            eventType: "agent_init",
+            data: { system_prompt: this.systemPrompt, tools: openaiTools }
+          })
+        );
+        this.agentInitSent = true;
+        this.toolsSignature = toolsSignature;
+      } else if (toolsSignature !== this.toolsSignature) {
+        events.push(this.makeEvent({ eventType: "tools_updated", data: { tools: openaiTools } }));
+        this.toolsSignature = toolsSignature;
+      }
+      events.push(
+        this.makeEvent({
+          eventType: "user_prompt",
+          data: { request: { message: userMessage }, response: null }
+        })
+      );
+      let finishedNormally = false;
+      for (let round = 0; round < this.maxToolRounds; round += 1) {
+        const messages = await this.memory.buildMessagesForLLM(this.systemPrompt);
+        this.debug.logLLMRequest(this.model, messages.length, openaiTools.length);
+        const llmRequest = {
+          model: this.model,
+          messages,
+          stream: true,
+          ...openaiTools.length > 0 ? { tools: openaiTools } : {},
+          ...this.vendor === "openai" || this.vendor === "openrouter" ? { stream_options: { include_usage: true } } : {}
+        };
+        const llmEventRequestData = {
+          model: this.model,
+          messages: this.extractLlmEventMessages(messages),
+          stream: true
+        };
+        const startedAt = Date.now();
+        const stream = await this.client.chat.completions.create(
+          llmRequest
+        );
+        const contentParts = [];
+        const toolCallsMap = /* @__PURE__ */ new Map();
+        let finishReason = null;
+        let llmTotalTokens = 0;
+        for await (const chunk of stream) {
+          if (chunk.usage?.total_tokens) {
+            llmTotalTokens = chunk.usage.total_tokens;
+          }
+          const choice = chunk.choices?.[0];
+          if (!choice) {
+            continue;
+          }
+          if (choice.finish_reason) {
+            finishReason = choice.finish_reason;
+          }
+          const delta = choice.delta;
+          if (!delta) {
+            continue;
+          }
+          if (delta.content) {
+            contentParts.push(delta.content);
+            yield delta.content;
+          }
+          for (const toolCall of delta.tool_calls ?? []) {
+            const index = toolCall.index ?? 0;
+            const existing = toolCallsMap.get(index) ?? { id: "", name: "", arguments: "" };
+            if (toolCall.id) {
+              existing.id = toolCall.id;
+            }
+            if (toolCall.function?.name) {
+              existing.name = toolCall.function.name;
+            }
+            if (toolCall.function?.arguments) {
+              existing.arguments += toolCall.function.arguments;
+            }
+            toolCallsMap.set(index, existing);
+          }
+        }
+        const assistantContent = contentParts.join("") || null;
+        const llmLatencyMs = Date.now() - startedAt;
+        const toolCalls = [...toolCallsMap.entries()].sort(([a], [b]) => a - b).map(([, call]) => ({
+          id: call.id,
+          type: "function",
+          function: {
+            name: call.name,
+            arguments: call.arguments || "{}"
+          }
+        }));
+        events.push(
+          this.makeEvent({
+            eventType: "llm_call",
+            data: {
+              request: llmEventRequestData,
+              response: {
+                finish_reason: finishReason,
+                content: assistantContent,
+                tool_calls: toolCalls
+              }
+            },
+            tokens: llmTotalTokens,
+            latencyMs: llmLatencyMs
+          })
+        );
+        if (finishReason === "tool_calls" || toolCalls.length > 0) {
+          this.debug.logToolCalls(toolCalls);
+          this.memory.append({
+            role: "assistant",
+            content: assistantContent,
+            tool_calls: toolCalls
+          });
+          for (const toolCall of toolCalls) {
+            const toolStartedAt = Date.now();
+            const result = await this.tools.execute(
+              toolCall.id,
+              toolCall.function.name,
+              toolCall.function.arguments,
+              this.approvalCallback
+            );
+            const toolLatencyMs = Date.now() - toolStartedAt;
+            this.debug.logToolResult(toolCall.id, true, result);
+            let parsedResponse;
+            try {
+              parsedResponse = JSON.parse(result);
+            } catch {
+              parsedResponse = { raw: result };
+            }
+            events.push(
+              this.makeEvent({
+                eventType: "tool_call",
+                data: {
+                  request: toolCall,
+                  response: parsedResponse
+                },
+                latencyMs: toolLatencyMs
+              })
+            );
+            this.memory.append({
+              role: "tool",
+              tool_call_id: toolCall.id,
+              content: result
+            });
+          }
+          continue;
+        }
+        this.memory.append({
+          role: "assistant",
+          content: assistantContent ?? ""
+        });
+        finishedNormally = true;
+        break;
+      }
+      if (!finishedNormally) {
+        throw new Error(
+          `Exceeded maxToolRounds (${this.maxToolRounds}); increase maxToolRounds or simplify the task.`
+        );
+      }
+    } catch (error) {
+      events.push(
+        this.makeEvent({
+          eventType: "agent_loop_error",
+          data: { error: error instanceof Error ? error.message : String(error) }
+        })
+      );
+      throw error;
+    } finally {
+      this.debug.log("Queueing event flush count=%s", events.length);
+      await this.flushEvents(events);
+    }
+  }
+};
+export {
+  Agent,
+  ChatMemory,
+  ToolRegistry,
+  tool
+};
+//# sourceMappingURL=index.js.map