@cuylabs/agent-core 0.3.0 → 0.5.0

package/dist/chunk-OTUGSCED.js

@@ -0,0 +1,691 @@
+// src/middleware/runner.ts
+var MiddlewareRunner = class {
+  stack;
+  constructor(middleware = []) {
+    this.stack = Object.freeze([...middleware]);
+  }
+  /** Number of registered middleware */
+  get count() {
+    return this.stack.length;
+  }
+  /** Whether any middleware is registered */
+  get hasMiddleware() {
+    return this.stack.length > 0;
+  }
+  /** Get the middleware list (for fork inheritance) */
+  getMiddleware() {
+    return this.stack;
+  }
+  // --------------------------------------------------------------------------
+  // beforeToolCall — array order, first "deny" wins
+  // --------------------------------------------------------------------------
+  /**
+   * Run all `beforeToolCall` hooks in order.
+   *
+   * Returns `{ action: "allow" }` if all middleware allow (or have no hook).
+   * Returns `{ action: "deny", reason }` on first denial — remaining
+   * middleware are skipped.
+   */
+  async runBeforeToolCall(tool, args, ctx) {
+    for (const mw of this.stack) {
+      if (!mw.beforeToolCall) continue;
+      try {
+        const decision = await mw.beforeToolCall(tool, args, ctx);
+        if (decision.action === "deny") {
+          return decision;
+        }
+      } catch (err) {
+        return {
+          action: "deny",
+          reason: `Middleware "${mw.name}" error: ${err instanceof Error ? err.message : String(err)}`
+        };
+      }
+    }
+    return { action: "allow" };
+  }
+  // --------------------------------------------------------------------------
+  // afterToolCall — reverse order (innermost first)
+  // --------------------------------------------------------------------------
+  /**
+   * Run all `afterToolCall` hooks in reverse order.
+   *
+   * Each hook receives the result from the previous hook (or the
+   * original tool result for the first hook). Errors are caught
+   * and logged — the original result passes through.
+   */
+  async runAfterToolCall(tool, args, result, ctx) {
+    let current = result;
+    for (let i = this.stack.length - 1; i >= 0; i--) {
+      const mw = this.stack[i];
+      if (!mw.afterToolCall) continue;
+      try {
+        current = await mw.afterToolCall(tool, args, current, ctx);
+      } catch (err) {
+        console.warn(
+          `[middleware] "${mw.name}" afterToolCall error:`,
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
+    return current;
+  }
+  // --------------------------------------------------------------------------
+  // promptSections — all run, results merged
+  // --------------------------------------------------------------------------
+  /**
+   * Collect prompt sections from all middleware.
+   *
+   * Returns a flat array of sections. Each middleware can return a single
+   * section, an array of sections, or undefined/empty.
+   */
+  collectPromptSections(ctx) {
+    const sections = [];
+    for (const mw of this.stack) {
+      if (!mw.promptSections) continue;
+      try {
+        const result = mw.promptSections(ctx);
+        if (!result) continue;
+        if (Array.isArray(result)) {
+          sections.push(...result);
+        } else {
+          sections.push(result);
+        }
+      } catch (err) {
+        console.warn(
+          `[middleware] "${mw.name}" promptSections error:`,
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
+    return sections;
+  }
+  // --------------------------------------------------------------------------
+  // onEvent — fire-and-forget, all run
+  // --------------------------------------------------------------------------
+  /**
+   * Broadcast an event to all middleware observers.
+   *
+   * Non-blocking — errors are caught and logged. This never
+   * slows down the streaming pipeline.
+   */
+  emitEvent(event) {
+    for (const mw of this.stack) {
+      if (!mw.onEvent) continue;
+      try {
+        mw.onEvent(event);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Get the OTel context for a session from the telemetry middleware.
+   * Returns undefined if no telemetry middleware is registered.
+   */
+  getOtelContext(sessionId) {
+    for (const mw of this.stack) {
+      if (mw.getOtelContext) {
+        const ctx = mw.getOtelContext(sessionId);
+        if (ctx) return ctx;
+      }
+    }
+    return void 0;
+  }
+  // --------------------------------------------------------------------------
+  // onChatStart — array order, sequential
+  // --------------------------------------------------------------------------
+  /**
+   * Run all `onChatStart` hooks in order.
+   *
+   * Errors are caught and logged — a broken logger should not
+   * prevent the chat from starting.
+   */
+  async runChatStart(sessionId, message) {
+    for (const mw of this.stack) {
+      if (!mw.onChatStart) continue;
+      try {
+        await mw.onChatStart(sessionId, message);
+      } catch (err) {
+        console.warn(
+          `[middleware] "${mw.name}" onChatStart error:`,
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
+  }
+  // --------------------------------------------------------------------------
+  // onChatEnd — array order, sequential
+  // --------------------------------------------------------------------------
+  /**
+   * Run all `onChatEnd` hooks in order.
+   *
+   * Always called, even when the stream errored. Errors in handlers
+   * are caught and logged.
+   */
+  async runChatEnd(sessionId, result) {
+    for (const mw of this.stack) {
+      if (!mw.onChatEnd) continue;
+      try {
+        await mw.onChatEnd(sessionId, result);
+      } catch (err) {
+        console.warn(
+          `[middleware] "${mw.name}" onChatEnd error:`,
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
+  }
+};
+
+// src/safety/approval/risk.ts
+var DEFAULT_TOOL_RISKS = {
+  read: "safe",
+  read_file: "safe",
+  grep: "safe",
+  glob: "safe",
+  list_dir: "safe",
+  invoke_agent: "safe",
+  wait_agent: "safe",
+  close_agent: "safe",
+  skill: "safe",
+  skill_resource: "safe",
+  write: "moderate",
+  write_file: "moderate",
+  edit: "moderate",
+  edit_file: "moderate",
+  create_file: "moderate",
+  bash: "dangerous",
+  shell: "dangerous",
+  delete_file: "dangerous",
+  remove: "dangerous"
+};
+function getToolRisk(tool, customRisks) {
+  if (customRisks?.[tool]) {
+    return customRisks[tool];
+  }
+  if (DEFAULT_TOOL_RISKS[tool]) {
+    return DEFAULT_TOOL_RISKS[tool];
+  }
+  return "moderate";
+}
+
+// src/safety/approval/errors.ts
+var ApprovalDeniedError = class extends Error {
+  constructor(tool, args, message) {
+    super(message || `Operation denied: ${tool}`);
+    this.tool = tool;
+    this.args = args;
+    this.name = "ApprovalDeniedError";
+  }
+};
+var ApprovalTimeoutError = class extends Error {
+  constructor(tool, timeoutMs) {
+    super(`Approval timeout after ${timeoutMs}ms for: ${tool}`);
+    this.tool = tool;
+    this.timeoutMs = timeoutMs;
+    this.name = "ApprovalTimeoutError";
+  }
+};
+
+// src/safety/approval/patterns.ts
+function matchApprovalPattern(pattern, value) {
+  const regex = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${regex}$`, "i").test(value);
+}
+function extractApprovalPatterns(tool, args) {
+  if (!args || typeof args !== "object") {
+    return [tool];
+  }
+  const record = args;
+  if ("path" in record && typeof record.path === "string" || "filePath" in record && typeof record.filePath === "string") {
+    const path = record.path ?? record.filePath;
+    const dir = path.substring(0, path.lastIndexOf("/") + 1);
+    return [dir ? `${dir}*` : path];
+  }
+  if ("command" in record && typeof record.command === "string") {
+    const command = record.command.split(/\s+/)[0];
+    return [command];
+  }
+  if ("pattern" in record && typeof record.pattern === "string") {
+    return [record.pattern];
+  }
+  return [tool];
+}
+function describeApprovalOperation(tool, args) {
+  if (!args || typeof args !== "object") {
+    return `Execute ${tool}`;
+  }
+  const record = args;
+  switch (tool) {
+    case "read":
+    case "read_file":
+      return `Read file: ${record.path ?? record.filePath}`;
+    case "write":
+    case "write_file":
+    case "create_file":
+      return `Write file: ${record.path ?? record.filePath}`;
+    case "edit":
+    case "edit_file":
+      return `Edit file: ${record.path ?? record.filePath}`;
+    case "delete_file":
+    case "remove":
+      return `Delete: ${record.path}`;
+    case "bash":
+    case "shell": {
+      const command = String(record.command);
+      return `Run command: ${command.slice(0, 100)}${command.length > 100 ? "..." : ""}`;
+    }
+    case "grep":
+      return `Search for: ${record.pattern}`;
+    case "glob":
+      return `Find files: ${record.pattern}`;
+    default:
+      return `${tool}(${JSON.stringify(args).slice(0, 50)}...)`;
+  }
+}
+
+// src/safety/approval/handler.ts
+var requestCounter = 0;
+function findMatchingRule(rules, tool, patterns) {
+  for (let index = rules.length - 1; index >= 0; index--) {
+    const rule = rules[index];
+    const toolMatches = rule.tool === "*" || matchApprovalPattern(rule.tool, tool);
+    const patternMatches = patterns.some(
+      (pattern) => matchApprovalPattern(rule.pattern, pattern)
+    );
+    if (toolMatches && patternMatches) {
+      return rule;
+    }
+  }
+  return void 0;
+}
+function createApprovalHandler(config = {}) {
+  const {
+    defaultAction = "ask",
+    timeout = 5 * 60 * 1e3,
+    onRequest
+  } = config;
+  const rules = [...config.rules ?? []];
+  const pending = /* @__PURE__ */ new Map();
+  async function request(sessionId, tool, args, customRisks) {
+    const risk = getToolRisk(tool, customRisks);
+    const patterns = extractApprovalPatterns(tool, args);
+    const matchingRule = findMatchingRule(rules, tool, patterns);
+    if (matchingRule) {
+      if (matchingRule.action === "allow") {
+        return;
+      }
+      throw new ApprovalDeniedError(
+        tool,
+        args,
+        `Denied by rule: ${matchingRule.pattern}`
+      );
+    }
+    if (risk === "safe" && defaultAction !== "deny") {
+      return;
+    }
+    if (!onRequest) {
+      if (defaultAction === "allow") {
+        return;
+      }
+      if (defaultAction === "deny") {
+        throw new ApprovalDeniedError(tool, args);
+      }
+      throw new ApprovalDeniedError(tool, args, "No approval handler configured");
+    }
+    const id = `approval-${++requestCounter}-${Date.now()}`;
+    const requestData = {
+      id,
+      sessionId,
+      tool,
+      args,
+      description: describeApprovalOperation(tool, args),
+      risk,
+      patterns,
+      timestamp: Date.now()
+    };
+    const action = await Promise.race([
+      new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        onRequest(requestData).then(resolve).catch(reject).finally(() => pending.delete(id));
+      }),
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          pending.delete(id);
+          reject(new ApprovalTimeoutError(tool, timeout));
+        }, timeout);
+      })
+    ]);
+    switch (action) {
+      case "allow":
+        return;
+      case "deny":
+        throw new ApprovalDeniedError(tool, args);
+      case "remember":
+        for (const pattern of patterns) {
+          rules.push({ pattern, tool, action: "allow" });
+        }
+        return;
+    }
+  }
+  function cancelAll(reason) {
+    for (const [id, { reject }] of pending) {
+      reject(new Error(reason ?? "Cancelled"));
+      pending.delete(id);
+    }
+  }
+  function addRule(rule) {
+    rules.push(rule);
+  }
+  function getRules() {
+    return rules;
+  }
+  function clearSessionRules() {
+    rules.length = config.rules?.length ?? 0;
+  }
+  return {
+    request,
+    cancelAll,
+    addRule,
+    getRules,
+    clearSessionRules
+  };
+}
+
+// src/middleware/approval.ts
+function approvalMiddleware(config = {}) {
+  const handler = createApprovalHandler(config);
+  return {
+    name: "approval",
+    async beforeToolCall(tool, args, ctx) {
+      try {
+        await handler.request(ctx.sessionID, tool, args, config.customRisks);
+        return { action: "allow" };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : `Approval denied: ${tool}`;
+        return { action: "deny", reason };
+      }
+    }
+  };
+}
+
+// src/middleware/telemetry/otel.ts
+var otelModulePromise;
+function getInputMimeType(value) {
+  const trimmed = value.trimStart();
+  return trimmed.startsWith("{") || trimmed.startsWith("[") ? "application/json" : "text/plain";
+}
+async function getOtelModule() {
+  if (!otelModulePromise) {
+    otelModulePromise = import("@opentelemetry/api").then((module) => module).catch(() => null);
+  }
+  return await otelModulePromise;
+}
+function scheduleSpanTimeout(options) {
+  const { spans, key, otel, timeoutMs } = options;
+  return setTimeout(() => {
+    const entry = spans.get(key);
+    if (!entry) {
+      return;
+    }
+    entry.span.setStatus({
+      code: otel.SpanStatusCode.ERROR,
+      message: "Span timed out (possible leak \u2014 onChatEnd never called)"
+    });
+    entry.span.end();
+    spans.delete(key);
+  }, timeoutMs);
+}
+function otelMiddleware(config = {}) {
+  const recordInputs = config.recordInputs ?? true;
+  const recordOutputs = config.recordOutputs ?? true;
+  const agentName = config.agentName ?? "agent";
+  const emitToolSpans = config.emitToolSpans ?? true;
+  const spanTimeoutMs = config.spanTimeoutMs ?? 5 * 60 * 1e3;
+  const chatSpans = /* @__PURE__ */ new Map();
+  const toolSpans = /* @__PURE__ */ new Map();
+  let otel = null;
+  let tracer = null;
+  async function ensureTracer() {
+    if (tracer) {
+      return tracer;
+    }
+    otel = await getOtelModule();
+    if (!otel) {
+      return null;
+    }
+    tracer = otel.trace.getTracer("@cuylabs/agent-core");
+    return tracer;
+  }
+  return {
+    name: "opentelemetry",
+    getOtelContext(sessionId) {
+      return chatSpans.get(sessionId)?.ctx;
+    },
+    async onChatStart(sessionId, message) {
+      const activeTracer = await ensureTracer();
+      if (!activeTracer || !otel) {
+        return;
+      }
+      const attributes = {
+        "openinference.span.kind": "AGENT",
+        "gen_ai.operation.name": "invoke_agent",
+        "gen_ai.agent.name": agentName,
+        "gen_ai.agent.session_id": sessionId
+      };
+      if (config.agentDescription) {
+        attributes["gen_ai.agent.description"] = config.agentDescription;
+      }
+      if (recordInputs) {
+        const inputValue = message.slice(0, 4096);
+        attributes["input.value"] = inputValue;
+        attributes["input.mime_type"] = getInputMimeType(inputValue);
+      }
+      const span = activeTracer.startSpan(`invoke_agent ${agentName}`, {
+        attributes
+      });
+      const ctx = otel.trace.setSpan(otel.context.active(), span);
+      chatSpans.set(sessionId, {
+        span,
+        ctx,
+        timer: scheduleSpanTimeout({
+          spans: chatSpans,
+          key: sessionId,
+          otel,
+          timeoutMs: spanTimeoutMs
+        })
+      });
+    },
+    async beforeToolCall(tool, args, ctx) {
+      if (!emitToolSpans) {
+        return { action: "allow" };
+      }
+      const activeTracer = await ensureTracer();
+      if (!activeTracer || !otel) {
+        return { action: "allow" };
+      }
+      const sessionId = ctx?.sessionID;
+      const parent = sessionId ? chatSpans.get(sessionId) : void 0;
+      const parentCtx = parent?.ctx ?? otel.context.active();
+      const span = activeTracer.startSpan(
+        `execute_tool ${tool}`,
+        {
+          attributes: {
+            "openinference.span.kind": "TOOL",
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": tool,
+            ...recordInputs && args != null ? (() => {
+              const argsString = JSON.stringify(args).slice(0, 4096);
+              return {
+                "gen_ai.tool.call.arguments": argsString,
+                "input.value": argsString,
+                "input.mime_type": getInputMimeType(argsString),
+                "tool.parameters": argsString
+              };
+            })() : {}
+          }
+        },
+        parentCtx
+      );
+      const callId = ctx?.messageID ?? JSON.stringify(args);
+      const key = `${tool}:${callId}`;
+      const toolCtx = otel.trace.setSpan(parentCtx, span);
+      toolSpans.set(key, {
+        span,
+        ctx: toolCtx,
+        timer: scheduleSpanTimeout({
+          spans: toolSpans,
+          key,
+          otel,
+          timeoutMs: spanTimeoutMs
+        })
+      });
+      return { action: "allow" };
+    },
+    async afterToolCall(tool, args, result, ctx) {
+      const callId = ctx?.messageID ?? JSON.stringify(args);
+      const keyPrefix = `${tool}:`;
+      const key = `${tool}:${callId}`;
+      const entry = toolSpans.get(key) ?? Array.from(toolSpans.entries()).find(
+        ([candidate]) => candidate.startsWith(keyPrefix)
+      )?.[1];
+      if (entry) {
+        if (entry.timer) {
+          clearTimeout(entry.timer);
+        }
+        if (recordOutputs && result.output) {
+          const outputValue = (typeof result.output === "string" ? result.output : JSON.stringify(result.output)).slice(0, 4096);
+          entry.span.setAttribute("gen_ai.tool.call.result", outputValue);
+          entry.span.setAttribute("output.value", outputValue);
+          entry.span.setAttribute("output.mime_type", getInputMimeType(outputValue));
+        }
+        entry.span.setStatus({ code: otel?.SpanStatusCode.OK ?? 1 });
+        entry.span.end();
+        for (const [candidateKey, candidateEntry] of toolSpans) {
+          if (candidateEntry === entry) {
+            toolSpans.delete(candidateKey);
+            break;
+          }
+        }
+      }
+      return result;
+    },
+    onEvent(event) {
+      if (event.type !== "tool-error") {
+        return;
+      }
+      for (const [key, entry] of toolSpans) {
+        if (!key.startsWith(`${event.toolName}:`)) {
+          continue;
+        }
+        if (entry.timer) {
+          clearTimeout(entry.timer);
+        }
+        entry.span.setStatus({
+          code: otel?.SpanStatusCode.ERROR ?? 2,
+          message: event.error
+        });
+        entry.span.recordException({
+          name: "ToolError",
+          message: event.error
+        });
+        entry.span.end();
+        toolSpans.delete(key);
+        break;
+      }
+    },
+    async onChatEnd(sessionId, result) {
+      const entry = chatSpans.get(sessionId);
+      if (!entry) {
+        return;
+      }
+      if (entry.timer) {
+        clearTimeout(entry.timer);
+      }
+      if (result.usage) {
+        entry.span.setAttributes({
+          "gen_ai.usage.input_tokens": result.usage.inputTokens ?? 0,
+          "gen_ai.usage.output_tokens": result.usage.outputTokens ?? 0
+        });
+      }
+      if (recordOutputs && result.output) {
+        const outputValue = result.output.slice(0, 4096);
+        entry.span.setAttribute("gen_ai.output.text", outputValue);
+        entry.span.setAttribute("output.value", outputValue);
+        entry.span.setAttribute("output.mime_type", getInputMimeType(outputValue));
+      }
+      if (result.error) {
+        entry.span.setStatus({
+          code: otel?.SpanStatusCode.ERROR ?? 2,
+          message: result.error.message
+        });
+        entry.span.recordException(result.error);
+      } else {
+        entry.span.setStatus({ code: otel?.SpanStatusCode.OK ?? 1 });
+      }
+      entry.span.end();
+      chatSpans.delete(sessionId);
+    }
+  };
+}
+
+// src/middleware/telemetry/provider.ts
+function createTelemetryConfig(config) {
+  const middleware = otelMiddleware({
+    agentName: config.agentName,
+    agentDescription: config.agentDescription,
+    recordInputs: config.recordInputs,
+    recordOutputs: config.recordOutputs,
+    emitToolSpans: config.emitToolSpans,
+    spanTimeoutMs: config.spanTimeoutMs
+  });
+  const telemetry = {
+    isEnabled: true,
+    functionId: config.agentName,
+    recordInputs: config.recordInputs,
+    recordOutputs: config.recordOutputs
+  };
+  let providerPromise;
+  if (config.spanProcessor) {
+    providerPromise = createAndRegisterProvider(
+      config.spanProcessor,
+      config.serviceName ?? config.agentName
+    );
+  }
+  return {
+    middleware,
+    telemetry,
+    shutdown: async () => {
+      if (!providerPromise) {
+        return;
+      }
+      const provider = await providerPromise;
+      await provider.forceFlush();
+      await provider.shutdown();
+    }
+  };
+}
+async function createAndRegisterProvider(spanProcessor, serviceName) {
+  const [{ NodeTracerProvider }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] = await Promise.all([
+    import("@opentelemetry/sdk-trace-node"),
+    import("@opentelemetry/resources"),
+    import("@opentelemetry/semantic-conventions")
+  ]);
+  const provider = new NodeTracerProvider({
+    resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: serviceName }),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    spanProcessors: [spanProcessor]
+  });
+  provider.register();
+  return provider;
+}
+
+export {
+  MiddlewareRunner,
+  otelMiddleware,
+  createTelemetryConfig,
+  getToolRisk,
+  ApprovalDeniedError,
+  ApprovalTimeoutError,
+  createApprovalHandler,
+  approvalMiddleware
+};