@agentic-eng/agent 0.1.0-alpha.0 → 0.1.0-beta.2

package/README.md

@@ -2,6 +2,8 @@
 
 > Core agent primitives and runtime for EASA — Easy Agent System Architecture.
 
+[PLEASE NOTE: This package is not yet ready for production use. It is currently in beta and may change significantly before the first stable release.]
+
 ## Installation
 
 ```bash

package/dist/index.cjs

@@ -1,18 +1,640 @@
 'use strict';
 
+var fs = require('fs');
+var path = require('path');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
+
+// src/errors.ts
+var EasaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EasaError";
+  }
+};
+var ProviderError = class extends EasaError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ProviderError";
+  }
+};
+var AgentConfigError = class extends EasaError {
+  constructor(message) {
+    super(message);
+    this.name = "AgentConfigError";
+  }
+};
+var MaxIterationsError = class extends EasaError {
+  constructor(maxIterations, iterationsCompleted) {
+    super(
+      `Agent reasoning loop exceeded maximum of ${maxIterations} iterations (completed ${iterationsCompleted}). The goal could not be achieved.`
+    );
+    this.maxIterations = maxIterations;
+    this.iterationsCompleted = iterationsCompleted;
+    this.name = "MaxIterationsError";
+  }
+};
+var ReasoningParseError = class extends EasaError {
+  constructor(message, rawContent) {
+    super(message);
+    this.rawContent = rawContent;
+    this.name = "ReasoningParseError";
+  }
+};
+var ToolExecutionError = class extends EasaError {
+  constructor(toolName, message, cause) {
+    super(`Tool "${toolName}" failed: ${message}`);
+    this.toolName = toolName;
+    this.cause = cause;
+    this.name = "ToolExecutionError";
+  }
+};
+
+// src/events.ts
+var ConsoleEventEmitter = class {
+  prefix;
+  constructor(options) {
+    this.prefix = options?.prefix ?? "[EASA]";
+  }
+  emit(event) {
+    const ts = event.timestamp.split("T")[1] ?? event.timestamp;
+    const tag = this.formatType(event.type);
+    const detail = this.formatData(event);
+    console.log(`${this.prefix} ${ts} ${tag} ${detail}`);
+  }
+  formatType(type) {
+    const icons = {
+      "agent.invoke.start": "\u25B6 INVOKE",
+      "agent.invoke.end": "\u25A0 INVOKE",
+      "agent.invoke_stream.start": "\u25B6 STREAM",
+      "agent.invoke_stream.end": "\u25A0 STREAM",
+      "agent.iteration.start": "\u21BB ITER",
+      "agent.iteration.end": "\u2713 ITER",
+      "llm.call.start": "\u2192 LLM",
+      "llm.call.end": "\u2190 LLM",
+      "tool.call.start": "\u2699 TOOL",
+      "tool.call.end": "\u2699 TOOL\u2713",
+      "tool.schema.inject": "\u{1F4CB} SCHEMA",
+      "tool.not_found": "\u26A0 TOOL?",
+      "memory.store": "\u{1F4BE} MEMORY",
+      "agent.error": "\u2717 ERROR"
+    };
+    return icons[type] ?? type;
+  }
+  formatData(event) {
+    const d = event.data;
+    switch (event.type) {
+      case "agent.invoke.start":
+        return `agent="${event.agentName}" prompt="${this.truncate(d["prompt"])}"`;
+      case "agent.invoke.end":
+        return `agent="${event.agentName}" iterations=${d["totalIterations"]} completed=${d["completed"]}`;
+      case "agent.invoke_stream.start":
+        return `agent="${event.agentName}" prompt="${this.truncate(d["prompt"])}"`;
+      case "agent.invoke_stream.end":
+        return `agent="${event.agentName}" length=${d["contentLength"]}`;
+      case "agent.iteration.start":
+        return `iteration=${d["iteration"]}/${d["maxIterations"]}`;
+      case "agent.iteration.end":
+        return `iteration=${d["iteration"]} action="${d["action"]}"`;
+      case "llm.call.start":
+        return `messages=${d["messageCount"]}`;
+      case "llm.call.end":
+        return `tokens=${d["totalTokens"] ?? "n/a"}`;
+      case "tool.call.start":
+        return `tool="${d["toolName"]}"`;
+      case "tool.call.end":
+        return `tool="${d["toolName"]}" success=${d["success"]}`;
+      case "tool.schema.inject":
+        return `tool="${d["toolName"]}"`;
+      case "tool.not_found":
+        return `tool="${d["toolName"]}" available=${d["availableTools"]}`;
+      case "memory.store":
+        return `label="${d["label"]}"`;
+      case "agent.error":
+        return `error="${d["message"]}"`;
+      default:
+        return JSON.stringify(d);
+    }
+  }
+  truncate(str, max = 80) {
+    if (!str) return "";
+    return str.length > max ? str.substring(0, max) + "\u2026" : str;
+  }
+};
+var NoopEventEmitter = class {
+  emit(_event) {
+  }
+};
+
 // src/agent.ts
+var DEFAULT_MAX_ITERATIONS = 5;
+function buildReasoningSystemPrompt(toolIndex) {
+  const toolSection = toolIndex ? `
+
+You have access to the following tools:
+${toolIndex}
+
+When you need to use a tool, set action to "tool_call" and provide the tool_call field.
+When you set action to "tool_call", the system will inject the tool's full input schema
+so you can construct the input accurately in the next step.` : "";
+  const toolCallFormat = toolIndex ? `,
+  "tool_call": null | { "name": "<tool_name>", "input": { ... } }` : "";
+  const toolRules = toolIndex ? `
+- If you need to use a tool, set action to "tool_call" and specify the tool name and input in tool_call.
+- After a tool executes, you will receive its result and can continue reasoning.` : "";
+  return `You are an AI agent. You MUST respond with valid JSON in the following format and nothing else:
+
+{
+  "action": "done" | "continue"${toolIndex ? ' | "tool_call"' : ""},
+  "reasoning": "<your internal chain-of-thought for this step>",
+  "content": "<the output for the user (final answer when done, intermediate when continue)>"${toolCallFormat},
+  "memory": null | { "label": "<short title>", "content": "<knowledge to remember>", "tags": ["optional", "tags"] }
+}${toolSection}
+
+Rules:
+- If you can answer directly, set action to "done" and provide the final answer in content.
+- If you need more thinking, research, or steps, set action to "continue" and explain in reasoning what you still need.${toolRules}
+- Only set memory when you discover knowledge worth persisting for future conversations.
+- Always respond with valid JSON. No markdown, no code fences, no extra text.`;
+}
 var Agent = class {
   name;
   description;
+  provider;
+  systemPrompt;
+  defaultOptions;
+  maxIterations;
+  memory;
+  tools;
+  emitter;
+  messages = [];
   constructor(config) {
     if (!config.name || config.name.trim().length === 0) {
-      throw new Error("Agent name is required and cannot be empty.");
+      throw new AgentConfigError("Agent name is required and cannot be empty.");
+    }
+    if (!config.provider) {
+      throw new AgentConfigError("Agent requires an LLM provider.");
     }
     this.name = config.name;
     this.description = config.description;
+    this.provider = config.provider;
+    this.systemPrompt = config.systemPrompt;
+    this.defaultOptions = config.defaultOptions;
+    this.maxIterations = config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    this.memory = config.memory;
+    this.tools = config.tools;
+    this.emitter = config.emitter ?? new NoopEventEmitter();
+  }
+  /**
+   * Send a prompt to the agent and run the reasoning loop until the agent
+   * produces a final answer or exhausts max iterations.
+   *
+   * The loop handles three actions:
+   * - `done` → return final answer
+   * - `continue` → feed intermediate output back, next iteration
+   * - `tool_call` → inject full tool schema, LLM constructs input, execute tool, feed result back
+   */
+  async invoke(prompt, options) {
+    this.emit("agent.invoke.start", { prompt });
+    this.messages.push({ role: "user", content: prompt });
+    const maxIter = options?.maxIterations ?? this.maxIterations;
+    const iterations = [];
+    let pendingToolSchema;
+    for (let i = 1; i <= maxIter; i++) {
+      this.emit("agent.iteration.start", { iteration: i, maxIterations: maxIter });
+      const messagesToSend = this.buildMessages(pendingToolSchema);
+      const mergedOptions = this.mergeOptions(options);
+      pendingToolSchema = void 0;
+      this.emit("llm.call.start", { messageCount: messagesToSend.length });
+      let rawResponse;
+      try {
+        rawResponse = await this.provider.chat(messagesToSend, mergedOptions);
+      } catch (error) {
+        this.emit("agent.error", { message: "LLM provider chat call failed.", error: String(error) });
+        throw new ProviderError("LLM provider chat call failed.", error);
+      }
+      this.emit("llm.call.end", { totalTokens: rawResponse.usage?.totalTokens });
+      const parsed = this.parseReasoningResponse(rawResponse.message.content);
+      const iterationResult = {
+        iteration: i,
+        response: parsed,
+        rawResponse
+      };
+      iterations.push(iterationResult);
+      if (parsed.memory && this.memory) {
+        this.emit("memory.store", { label: parsed.memory.label });
+        await this.memory.store(this.name, parsed.memory);
+      }
+      this.emit("agent.iteration.end", { iteration: i, action: parsed.action });
+      if (parsed.action === "done") {
+        this.messages.push({ role: "assistant", content: parsed.content });
+        this.emit("agent.invoke.end", { totalIterations: i, completed: true });
+        return {
+          content: parsed.content,
+          trace: { iterations, completed: true, totalIterations: i }
+        };
+      }
+      if (parsed.action === "tool_call" && parsed.tool_call) {
+        const toolCall = parsed.tool_call;
+        if (!this.tools || !this.tools.has(toolCall.name)) {
+          this.emit("tool.not_found", {
+            toolName: toolCall.name,
+            availableTools: this.tools?.getCompactIndex() ?? "none"
+          });
+          this.messages.push({ role: "assistant", content: rawResponse.message.content });
+          this.messages.push({
+            role: "user",
+            content: `Tool "${toolCall.name}" is not available. Available tools: ${this.tools?.getCompactIndex() ?? "none"}. Please choose a different approach.`
+          });
+          continue;
+        }
+        if (toolCall.input && Object.keys(toolCall.input).length > 0) {
+          this.emit("tool.call.start", { toolName: toolCall.name, input: toolCall.input });
+          const toolResult = await this.executeTool(toolCall);
+          this.emit("tool.call.end", { toolName: toolCall.name, success: toolResult.success });
+          this.messages.push({ role: "assistant", content: rawResponse.message.content });
+          this.messages.push({
+            role: "user",
+            content: `Tool "${toolCall.name}" result:
+${JSON.stringify(toolResult, null, 2)}`
+          });
+          continue;
+        }
+        this.emit("tool.schema.inject", { toolName: toolCall.name });
+        const schema = this.tools.getFullSchema(toolCall.name);
+        pendingToolSchema = schema;
+        this.messages.push({ role: "assistant", content: rawResponse.message.content });
+        this.messages.push({
+          role: "user",
+          content: `Here is the full schema for tool "${toolCall.name}":
+${schema}
+
+Please provide the tool_call with the correct input.`
+        });
+        continue;
+      }
+      this.messages.push({ role: "assistant", content: rawResponse.message.content });
+      this.messages.push({
+        role: "user",
+        content: `Continue. Iteration ${i} of ${maxIter}. Previous reasoning: ${parsed.reasoning}`
+      });
+    }
+    const lastIteration = iterations[iterations.length - 1];
+    const lastContent = lastIteration?.response.content ?? "Unable to complete the task.";
+    this.messages.push({ role: "assistant", content: lastContent });
+    this.emit("agent.invoke.end", { totalIterations: iterations.length, completed: false });
+    this.emit("agent.error", { message: `Max iterations (${maxIter}) exceeded.` });
+    throw new MaxIterationsError(maxIter, iterations.length);
+  }
+  /**
+   * Send a prompt to the agent and receive a streaming response.
+   * This is a single-pass stream (no reasoning loop) — useful for
+   * conversational responses where iteration is not needed.
+   *
+   * The assistant's full message is appended to conversation history
+   * once the stream completes.
+   */
+  async *invokeStream(prompt, options) {
+    this.emit("agent.invoke_stream.start", { prompt });
+    this.messages.push({ role: "user", content: prompt });
+    const messagesToSend = this.buildMessages();
+    const mergedOptions = this.mergeOptions(options);
+    let fullContent = "";
+    try {
+      for await (const chunk of this.provider.chatStream(messagesToSend, mergedOptions)) {
+        fullContent += chunk.delta;
+        yield chunk;
+      }
+    } catch (error) {
+      this.emit("agent.error", { message: "LLM provider stream call failed.", error: String(error) });
+      throw new ProviderError("LLM provider stream call failed.", error);
+    }
+    this.messages.push({ role: "assistant", content: fullContent });
+    this.emit("agent.invoke_stream.end", { contentLength: fullContent.length });
+  }
+  /**
+   * Returns a copy of the current conversation history.
+   */
+  getMessages() {
+    return [...this.messages];
+  }
+  /**
+   * Clears the conversation history.
+   */
+  clearHistory() {
+    this.messages = [];
+  }
+  /**
+   * Emits a lifecycle event via the configured emitter.
+   */
+  emit(type, data) {
+    this.emitter.emit({
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      agentName: this.name,
+      data
+    });
+  }
+  /**
+   * Executes a tool and returns the result. Catches errors gracefully
+   * so the agent can recover.
+   */
+  async executeTool(toolCall) {
+    const tool = this.tools.get(toolCall.name);
+    try {
+      return await tool.execute(toolCall.input);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        toolName: toolCall.name,
+        success: false,
+        output: "",
+        error: message
+      };
+    }
+  }
+  /**
+   * Parses the LLM's raw text response into a structured `LLMReasoningResponse`.
+   * Attempts to extract JSON from the response, handling common LLM quirks
+   * like wrapping in code fences.
+   */
+  parseReasoningResponse(raw) {
+    const cleaned = raw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+    let parsed;
+    try {
+      parsed = JSON.parse(cleaned);
+    } catch {
+      throw new ReasoningParseError(
+        `Failed to parse LLM response as JSON: ${raw.substring(0, 200)}`,
+        raw
+      );
+    }
+    if (typeof parsed !== "object" || parsed === null || !("action" in parsed) || !("content" in parsed)) {
+      throw new ReasoningParseError(
+        "LLM response JSON is missing required fields (action, content).",
+        raw
+      );
+    }
+    const obj = parsed;
+    if (obj["action"] !== "done" && obj["action"] !== "continue" && obj["action"] !== "tool_call") {
+      throw new ReasoningParseError(
+        `Invalid action "${String(obj["action"])}". Must be "done", "continue", or "tool_call".`,
+        raw
+      );
+    }
+    return {
+      action: obj["action"],
+      reasoning: typeof obj["reasoning"] === "string" ? obj["reasoning"] : "",
+      content: typeof obj["content"] === "string" ? obj["content"] : "",
+      tool_call: this.parseToolCall(obj["tool_call"]),
+      memory: this.parseMemoryEntry(obj["memory"])
+    };
+  }
+  /**
+   * Parses a tool_call field from the LLM response.
+   */
+  parseToolCall(raw) {
+    if (!raw || typeof raw !== "object") return void 0;
+    const obj = raw;
+    if (typeof obj["name"] !== "string") return void 0;
+    return {
+      name: obj["name"],
+      input: typeof obj["input"] === "object" && obj["input"] !== null ? obj["input"] : {}
+    };
+  }
+  /**
+   * Parses an optional memory entry from the LLM response.
+   */
+  parseMemoryEntry(raw) {
+    if (!raw || typeof raw !== "object") return void 0;
+    const obj = raw;
+    if (typeof obj["label"] !== "string" || typeof obj["content"] !== "string") {
+      return void 0;
+    }
+    return {
+      label: obj["label"],
+      content: obj["content"],
+      tags: Array.isArray(obj["tags"]) ? obj["tags"].filter((t) => typeof t === "string") : void 0
+    };
+  }
+  /**
+   * Builds the full message array to send to the provider.
+   * Includes: reasoning system prompt (with compact tool index) → custom system prompt → conversation.
+   * Optionally appends the full schema for a pending tool call.
+   */
+  buildMessages(pendingToolSchema) {
+    const messages = [];
+    const toolIndex = this.tools?.getCompactIndex() ?? "";
+    messages.push({ role: "system", content: buildReasoningSystemPrompt(toolIndex) });
+    if (this.systemPrompt) {
+      messages.push({ role: "system", content: this.systemPrompt });
+    }
+    messages.push(...this.messages);
+    if (pendingToolSchema) {
+      messages.push({
+        role: "system",
+        content: `Full tool schema for your tool_call:
+${pendingToolSchema}`
+      });
+    }
+    return messages;
+  }
+  /**
+   * Merges per-call options with default options. Per-call options take precedence.
+   */
+  mergeOptions(options) {
+    if (!this.defaultOptions && !options) return void 0;
+    return { ...this.defaultOptions, ...options };
+  }
+};
+var FlatFileMemoryProvider = class {
+  constructor(directory) {
+    this.directory = directory;
+  }
+  async store(agentName, entry) {
+    await fs__namespace.promises.mkdir(this.directory, { recursive: true });
+    const filePath = this.getFilePath(agentName);
+    const knlBlock = this.toKnlBlock(agentName, entry);
+    await fs__namespace.promises.appendFile(filePath, knlBlock + "\n", "utf-8");
+  }
+  async retrieve(agentName) {
+    const filePath = this.getFilePath(agentName);
+    let content;
+    try {
+      content = await fs__namespace.promises.readFile(filePath, "utf-8");
+    } catch {
+      return [];
+    }
+    return this.parseKnlBlocks(content);
+  }
+  getFilePath(agentName) {
+    const safeName = agentName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path__namespace.join(this.directory, `${safeName}.memory.knl`);
+  }
+  /**
+   * Converts a MemoryEntry into a KNL DATA block.
+   *
+   * Format:
+   * ```
+   * <<<
+   * KNL[DATA][1.0]:::
+   * ID[knl:data:easa.memory:{agentName}:{timestamp}:v1.0]:::
+   * NS[easa.memory]:::
+   * LABEL["{label}"]:::
+   * TAGS[{tags}]:::
+   * ITEM["{content}"] [DESC:"{label}"]
+   * >>>
+   * ```
+   */
+  toKnlBlock(agentName, entry) {
+    const timestamp = Date.now();
+    const safeName = agentName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const escapedLabel = this.escapeKnl(entry.label);
+    const escapedContent = this.escapeKnl(entry.content);
+    const tags = entry.tags?.join(",") ?? "";
+    const lines = [
+      "<<<",
+      "KNL[DATA][1.0]:::",
+      `ID[knl:data:easa.memory:${safeName}:${timestamp}:v1.0]:::`,
+      "NS[easa.memory]:::",
+      `LABEL["${escapedLabel}"]:::`
+    ];
+    if (tags) {
+      lines.push(`TAGS[${tags}]:::`);
+    }
+    lines.push(`ITEM["${escapedContent}"] [DESC:"${escapedLabel}"]`);
+    lines.push(">>>");
+    return lines.join("\n");
+  }
+  /**
+   * Parses KNL DATA blocks back into MemoryEntry objects.
+   */
+  parseKnlBlocks(content) {
+    const entries = [];
+    const blockPattern = /<<<([\s\S]*?)>>>/g;
+    let match;
+    while ((match = blockPattern.exec(content)) !== null) {
+      const block = match[1] ?? "";
+      const labelMatch = /LABEL\["([^"]*)"\]/.exec(block);
+      const itemMatch = /ITEM\["([^"]*)"\]/.exec(block);
+      const tagsMatch = /TAGS\[([^\]]*)\]/.exec(block);
+      if (labelMatch?.[1] && itemMatch?.[1]) {
+        const entry = {
+          label: this.unescapeKnl(labelMatch[1]),
+          content: this.unescapeKnl(itemMatch[1])
+        };
+        if (tagsMatch?.[1]) {
+          entry.tags = tagsMatch[1].split(",").map((t) => t.trim()).filter(Boolean);
+        }
+        entries.push(entry);
+      }
+    }
+    return entries;
+  }
+  escapeKnl(str) {
+    return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  }
+  unescapeKnl(str) {
+    return str.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+};
+
+// src/tool.ts
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  /**
+   * Register one or more tools.
+   */
+  register(...tools) {
+    for (const tool of tools) {
+      this.tools.set(tool.definition.name, tool);
+    }
+  }
+  /**
+   * Get a tool by name. Returns undefined if not found.
+   */
+  get(name) {
+    return this.tools.get(name);
+  }
+  /**
+   * Returns all registered tool definitions.
+   */
+  getDefinitions() {
+    return Array.from(this.tools.values()).map((t) => t.definition);
+  }
+  /**
+   * Returns a compact index of tools: just names and descriptions.
+   * This is what gets sent to the LLM on every call (token-efficient).
+   */
+  getCompactIndex() {
+    if (this.tools.size === 0) return "";
+    const lines = Array.from(this.tools.values()).map(
+      (t) => `- ${t.definition.name}: ${t.definition.description}`
+    );
+    return lines.join("\n");
+  }
+  /**
+   * Returns the full schema for a specific tool (name, description, inputSchema).
+   * Used when the LLM requests a tool call — injected into the next iteration
+   * so the LLM can construct the input accurately.
+   */
+  getFullSchema(name) {
+    const tool = this.tools.get(name);
+    if (!tool) return void 0;
+    return JSON.stringify(
+      {
+        name: tool.definition.name,
+        description: tool.definition.description,
+        inputSchema: tool.definition.inputSchema
+      },
+      null,
+      2
+    );
+  }
+  /**
+   * Returns the number of registered tools.
+   */
+  get size() {
+    return this.tools.size;
+  }
+  /**
+   * Check if a tool with the given name is registered.
+   */
+  has(name) {
+    return this.tools.has(name);
   }
 };
 
 exports.Agent = Agent;
+exports.AgentConfigError = AgentConfigError;
+exports.ConsoleEventEmitter = ConsoleEventEmitter;
+exports.EasaError = EasaError;
+exports.FlatFileMemoryProvider = FlatFileMemoryProvider;
+exports.MaxIterationsError = MaxIterationsError;
+exports.NoopEventEmitter = NoopEventEmitter;
+exports.ProviderError = ProviderError;
+exports.ReasoningParseError = ReasoningParseError;
+exports.ToolExecutionError = ToolExecutionError;
+exports.ToolRegistry = ToolRegistry;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map