@lleverage-ai/agent-sdk 0.0.1

package/dist/observability/tracing.js

@@ -0,0 +1,539 @@
+/**
+ * Distributed Tracing System.
+ *
+ * Provides OpenTelemetry-compatible tracing for:
+ * - Agent request tracing
+ * - Tool execution spans
+ * - Subagent spans
+ * - Cross-service correlation
+ *
+ * The implementation is framework-agnostic and can be used with
+ * actual OpenTelemetry or any compatible tracing system.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Utilities
+// =============================================================================
+/**
+ * Generate a random 128-bit trace ID (32 hex chars).
+ */
+function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Generate a random 64-bit span ID (16 hex chars).
+ */
+function generateSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// =============================================================================
+// No-op Implementation
+// =============================================================================
+/**
+ * A no-op span that does nothing.
+ * Used when tracing is disabled.
+ */
+const NOOP_SPAN = {
+    traceId: "00000000000000000000000000000000",
+    spanId: "0000000000000000",
+    name: "noop",
+    setAttribute: () => NOOP_SPAN,
+    setAttributes: () => NOOP_SPAN,
+    addEvent: () => NOOP_SPAN,
+    addLink: () => NOOP_SPAN,
+    setStatus: () => NOOP_SPAN,
+    recordException: () => NOOP_SPAN,
+    end: () => { },
+    getData: () => null,
+    isRecording: () => false,
+};
+// =============================================================================
+// Implementation
+// =============================================================================
+/**
+ * Creates a span implementation.
+ *
+ * @internal
+ */
+function createSpan(name, traceId, spanId, parentSpanId, kind, defaultAttributes, onEnd) {
+    const startTime = new Date();
+    const attributes = { ...defaultAttributes };
+    const events = [];
+    const links = [];
+    let status = { code: "unset" };
+    let ended = false;
+    let spanData = null;
+    return {
+        traceId,
+        spanId,
+        name,
+        setAttribute(key, value) {
+            if (!ended) {
+                attributes[key] = value;
+            }
+            return this;
+        },
+        setAttributes(attrs) {
+            if (!ended) {
+                Object.assign(attributes, attrs);
+            }
+            return this;
+        },
+        addEvent(eventName, attrs) {
+            if (!ended) {
+                events.push({
+                    name: eventName,
+                    timestamp: new Date().toISOString(),
+                    attributes: attrs,
+                });
+            }
+            return this;
+        },
+        addLink(linkTraceId, linkSpanId, attrs) {
+            if (!ended) {
+                links.push({
+                    traceId: linkTraceId,
+                    spanId: linkSpanId,
+                    attributes: attrs,
+                });
+            }
+            return this;
+        },
+        setStatus(code, message) {
+            if (!ended) {
+                status = { code, message };
+            }
+            return this;
+        },
+        recordException(error, attrs) {
+            if (!ended) {
+                events.push({
+                    name: "exception",
+                    timestamp: new Date().toISOString(),
+                    attributes: {
+                        "exception.type": error.name,
+                        "exception.message": error.message,
+                        "exception.stacktrace": error.stack ?? "",
+                        ...attrs,
+                    },
+                });
+                if (status.code === "unset") {
+                    status = { code: "error", message: error.message };
+                }
+            }
+            return this;
+        },
+        end() {
+            if (!ended) {
+                ended = true;
+                const endTime = new Date();
+                spanData = {
+                    traceId,
+                    spanId,
+                    parentSpanId,
+                    name,
+                    kind,
+                    startTime: startTime.toISOString(),
+                    endTime: endTime.toISOString(),
+                    durationMs: endTime.getTime() - startTime.getTime(),
+                    attributes,
+                    events,
+                    links,
+                    status,
+                };
+                onEnd(spanData);
+            }
+        },
+        getData() {
+            return spanData;
+        },
+        isRecording() {
+            return !ended;
+        },
+    };
+}
+/**
+ * Creates a tracer for distributed tracing.
+ *
+ * @param options - Tracer options
+ * @returns A tracer instance
+ *
+ * @example
+ * ```typescript
+ * const tracer = createTracer({
+ *   name: "my-agent",
+ *   exporters: [createConsoleSpanExporter()],
+ * });
+ *
+ * const span = tracer.startSpan("generate");
+ * try {
+ *   const result = await agent.generate({ prompt: "Hello" });
+ *   span.setAttribute("tokens", result.usage?.totalTokens ?? 0);
+ *   span.setStatus("ok");
+ * } catch (error) {
+ *   span.recordException(error as Error);
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ *
+ * @category Observability
+ */
+export function createTracer(options = {}) {
+    const { name = "agent", version = "1.0.0", defaultAttributes = {}, exporters = [], enabled = true, samplingRate = 1.0, } = options;
+    const pendingSpans = [];
+    let activeSpan = null;
+    /**
+     * Decide whether to sample this trace.
+     */
+    function shouldSample() {
+        return enabled && Math.random() < samplingRate;
+    }
+    /**
+     * Handle span end.
+     */
+    function onSpanEnd(data) {
+        pendingSpans.push(data);
+        if (activeSpan?.spanId === data.spanId) {
+            activeSpan = null;
+        }
+    }
+    const tracer = {
+        name,
+        enabled,
+        startSpan(spanName, opts = {}) {
+            if (!shouldSample()) {
+                return NOOP_SPAN;
+            }
+            const traceId = opts.parent?.traceId ?? generateTraceId();
+            const spanId = generateSpanId();
+            const parentSpanId = opts.parent?.spanId;
+            const kind = opts.kind ?? "internal";
+            const span = createSpan(spanName, traceId, spanId, parentSpanId, kind, {
+                ...defaultAttributes,
+                "service.name": name,
+                "service.version": version,
+                ...opts.attributes,
+            }, onSpanEnd);
+            // Add initial links
+            if (opts.links) {
+                for (const link of opts.links) {
+                    span.addLink(link.traceId, link.spanId, link.attributes);
+                }
+            }
+            activeSpan = span;
+            return span;
+        },
+        async withSpan(spanName, fn, opts) {
+            const span = this.startSpan(spanName, opts);
+            try {
+                const result = await fn(span);
+                // Set status to ok before ending if not already set
+                if (span.isRecording()) {
+                    span.setStatus("ok");
+                }
+                return result;
+            }
+            catch (error) {
+                span.recordException(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        },
+        getActiveSpan() {
+            return activeSpan;
+        },
+        async flush() {
+            if (pendingSpans.length === 0) {
+                return;
+            }
+            const spansToExport = [...pendingSpans];
+            pendingSpans.length = 0;
+            await Promise.all(exporters.map((e) => Promise.resolve(e.export(spansToExport)).catch(() => {
+                // Silently ignore export errors
+            })));
+        },
+        async shutdown() {
+            await this.flush();
+            await Promise.all(exporters.map((e) => e.shutdown ? Promise.resolve(e.shutdown()).catch(() => { }) : Promise.resolve()));
+        },
+    };
+    return tracer;
+}
+// =============================================================================
+// Exporters
+// =============================================================================
+/**
+ * Creates a console exporter for debugging.
+ *
+ * @returns A console span exporter
+ *
+ * @example
+ * ```typescript
+ * const tracer = createTracer({
+ *   exporters: [createConsoleSpanExporter()],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export function createConsoleSpanExporter() {
+    return {
+        name: "console",
+        export(spans) {
+            for (const span of spans) {
+                const statusIcon = span.status.code === "ok" ? "✓" : span.status.code === "error" ? "✗" : "?";
+                console.log(`[Trace] ${statusIcon} ${span.name} (${span.durationMs}ms)`, `trace=${span.traceId.slice(0, 8)} span=${span.spanId.slice(0, 8)}`, Object.keys(span.attributes).length > 0 ? JSON.stringify(span.attributes) : "");
+            }
+        },
+    };
+}
+/**
+ * Creates a memory exporter that stores spans.
+ *
+ * @returns A memory span exporter with access to stored spans
+ *
+ * @example
+ * ```typescript
+ * const exporter = createMemorySpanExporter();
+ * const tracer = createTracer({ exporters: [exporter] });
+ *
+ * tracer.startSpan("test").end();
+ * await tracer.flush();
+ *
+ * console.log(exporter.spans);
+ * ```
+ *
+ * @category Observability
+ */
+export function createMemorySpanExporter() {
+    const spans = [];
+    return {
+        name: "memory",
+        spans,
+        export(newSpans) {
+            spans.push(...newSpans);
+        },
+        clear() {
+            spans.length = 0;
+        },
+    };
+}
+/**
+ * Creates a callback exporter that invokes a function for each batch.
+ *
+ * @param callback - Function to call with spans
+ * @returns A callback span exporter
+ *
+ * @example
+ * ```typescript
+ * const exporter = createCallbackSpanExporter((spans) => {
+ *   sendToJaeger(spans);
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export function createCallbackSpanExporter(callback) {
+    return {
+        name: "callback",
+        export: callback,
+    };
+}
+/**
+ * Creates an OTLP-compatible exporter (OpenTelemetry Protocol).
+ *
+ * This exporter formats spans for OTLP collectors but does not
+ * include HTTP transport. Use with a custom callback for actual sending.
+ *
+ * @param options - Exporter options
+ * @returns An OTLP-compatible exporter
+ *
+ * @example
+ * ```typescript
+ * const exporter = createOTLPSpanExporter({
+ *   onExport: async (payload) => {
+ *     await fetch("http://collector:4318/v1/traces", {
+ *       method: "POST",
+ *       headers: { "Content-Type": "application/json" },
+ *       body: JSON.stringify(payload),
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export function createOTLPSpanExporter(options) {
+    const { serviceName = "agent", onExport } = options;
+    return {
+        name: "otlp",
+        async export(spans) {
+            // Convert to OTLP format
+            const payload = {
+                resourceSpans: [
+                    {
+                        resource: {
+                            attributes: [{ key: "service.name", value: { stringValue: serviceName } }],
+                        },
+                        scopeSpans: [
+                            {
+                                scope: { name: serviceName },
+                                spans: spans.map((span) => ({
+                                    traceId: span.traceId,
+                                    spanId: span.spanId,
+                                    parentSpanId: span.parentSpanId,
+                                    name: span.name,
+                                    kind: spanKindToOTLP(span.kind),
+                                    startTimeUnixNano: new Date(span.startTime).getTime() * 1_000_000,
+                                    endTimeUnixNano: new Date(span.endTime).getTime() * 1_000_000,
+                                    attributes: Object.entries(span.attributes).map(([k, v]) => ({
+                                        key: k,
+                                        value: attributeValueToOTLP(v),
+                                    })),
+                                    events: span.events.map((e) => ({
+                                        name: e.name,
+                                        timeUnixNano: new Date(e.timestamp).getTime() * 1_000_000,
+                                        attributes: e.attributes
+                                            ? Object.entries(e.attributes).map(([k, v]) => ({
+                                                key: k,
+                                                value: attributeValueToOTLP(v),
+                                            }))
+                                            : [],
+                                    })),
+                                    status: {
+                                        code: statusCodeToOTLP(span.status.code),
+                                        message: span.status.message,
+                                    },
+                                })),
+                            },
+                        ],
+                    },
+                ],
+            };
+            await onExport(payload);
+        },
+    };
+}
+/**
+ * Convert span kind to OTLP value.
+ * @internal
+ */
+function spanKindToOTLP(kind) {
+    const mapping = {
+        internal: 1,
+        server: 2,
+        client: 3,
+        producer: 4,
+        consumer: 5,
+    };
+    return mapping[kind];
+}
+/**
+ * Convert status code to OTLP value.
+ * @internal
+ */
+function statusCodeToOTLP(code) {
+    const mapping = {
+        unset: 0,
+        ok: 1,
+        error: 2,
+    };
+    return mapping[code];
+}
+/**
+ * Convert attribute value to OTLP format.
+ * @internal
+ */
+function attributeValueToOTLP(value) {
+    if (typeof value === "string") {
+        return { stringValue: value };
+    }
+    else if (typeof value === "number") {
+        return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+    }
+    else if (typeof value === "boolean") {
+        return { boolValue: value };
+    }
+    else if (Array.isArray(value)) {
+        return {
+            arrayValue: {
+                values: value.map((v) => attributeValueToOTLP(v)),
+            },
+        };
+    }
+    return { stringValue: String(value) };
+}
+// =============================================================================
+// Default Tracer
+// =============================================================================
+/**
+ * The default global tracer instance.
+ *
+ * @category Observability
+ */
+export let defaultTracer = createTracer({ name: "agent-sdk", enabled: false });
+/**
+ * Sets the default global tracer.
+ *
+ * @param tracer - The tracer to use as default
+ *
+ * @category Observability
+ */
+export function setDefaultTracer(tracer) {
+    defaultTracer = tracer;
+}
+// =============================================================================
+// Semantic Conventions
+// =============================================================================
+/**
+ * Semantic attribute keys for AI/LLM operations.
+ *
+ * Based on emerging OpenTelemetry semantic conventions for GenAI.
+ *
+ * @category Observability
+ */
+export const SemanticAttributes = {
+    // General
+    SERVICE_NAME: "service.name",
+    SERVICE_VERSION: "service.version",
+    // LLM/GenAI
+    GEN_AI_SYSTEM: "gen_ai.system",
+    GEN_AI_REQUEST_MODEL: "gen_ai.request.model",
+    GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens",
+    GEN_AI_REQUEST_TEMPERATURE: "gen_ai.request.temperature",
+    GEN_AI_RESPONSE_MODEL: "gen_ai.response.model",
+    GEN_AI_RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons",
+    GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
+    GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+    GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens",
+    // Agent-specific
+    AGENT_ID: "agent.id",
+    AGENT_NAME: "agent.name",
+    AGENT_TOOLS: "agent.tools",
+    AGENT_STEP: "agent.step",
+    // Tool
+    TOOL_NAME: "tool.name",
+    TOOL_INPUT: "tool.input",
+    TOOL_OUTPUT: "tool.output",
+    // Subagent
+    SUBAGENT_ID: "subagent.id",
+    SUBAGENT_TYPE: "subagent.type",
+    SUBAGENT_PROMPT: "subagent.prompt",
+    // Error
+    EXCEPTION_TYPE: "exception.type",
+    EXCEPTION_MESSAGE: "exception.message",
+    EXCEPTION_STACKTRACE: "exception.stacktrace",
+};
+//# sourceMappingURL=tracing.js.map

package/dist/observability/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/observability/tracing.ts"],"names":[],"mappings":"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"}

package/dist/plugins.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Plugin definition helpers.
+ *
+ * @packageDocumentation
+ */
+import type { AgentPlugin, PluginOptions } from "./types.js";
+/**
+ * Creates a plugin that extends agent functionality.
+ *
+ * Plugins bundle related tools and skills together for easy reuse
+ * across multiple agents. They can also include setup logic that runs when
+ * the plugin is loaded into an agent.
+ *
+ * @param options - Configuration options for the plugin
+ * @returns A plugin definition object
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from "@lleverage-ai/agent-sdk";
+ * import { tool } from "ai";
+ * import { z } from "zod";
+ *
+ * const gitPlugin = definePlugin({
+ *   name: "git",
+ *   description: "Git operations for version control",
+ *   tools: {
+ *     gitStatus: tool({
+ *       description: "Get the current git status",
+ *       inputSchema: z.object({}),
+ *       execute: async () => {
+ *         // Run git status...
+ *         return "On branch main, nothing to commit";
+ *       },
+ *     }),
+ *     gitCommit: tool({
+ *       description: "Create a git commit",
+ *       inputSchema: z.object({
+ *         message: z.string().describe("Commit message"),
+ *       }),
+ *       execute: async ({ message }) => {
+ *         // Run git commit...
+ *         return `Committed with message: ${message}`;
+ *       },
+ *     }),
+ *   },
+ *   setup: async (agent) => {
+ *     console.log(`Git plugin loaded into agent ${agent.id}`);
+ *   },
+ * });
+ * ```
+ *
+ * @category Plugins
+ */
+export declare function definePlugin(options: PluginOptions): AgentPlugin;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAShE"}

package/dist/plugins.js

@@ -0,0 +1,63 @@
+/**
+ * Plugin definition helpers.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Creates a plugin that extends agent functionality.
+ *
+ * Plugins bundle related tools and skills together for easy reuse
+ * across multiple agents. They can also include setup logic that runs when
+ * the plugin is loaded into an agent.
+ *
+ * @param options - Configuration options for the plugin
+ * @returns A plugin definition object
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from "@lleverage-ai/agent-sdk";
+ * import { tool } from "ai";
+ * import { z } from "zod";
+ *
+ * const gitPlugin = definePlugin({
+ *   name: "git",
+ *   description: "Git operations for version control",
+ *   tools: {
+ *     gitStatus: tool({
+ *       description: "Get the current git status",
+ *       inputSchema: z.object({}),
+ *       execute: async () => {
+ *         // Run git status...
+ *         return "On branch main, nothing to commit";
+ *       },
+ *     }),
+ *     gitCommit: tool({
+ *       description: "Create a git commit",
+ *       inputSchema: z.object({
+ *         message: z.string().describe("Commit message"),
+ *       }),
+ *       execute: async ({ message }) => {
+ *         // Run git commit...
+ *         return `Committed with message: ${message}`;
+ *       },
+ *     }),
+ *   },
+ *   setup: async (agent) => {
+ *     console.log(`Git plugin loaded into agent ${agent.id}`);
+ *   },
+ * });
+ * ```
+ *
+ * @category Plugins
+ */
+export function definePlugin(options) {
+    return {
+        name: options.name,
+        description: options.description,
+        setup: options.setup,
+        tools: options.tools,
+        mcpServer: options.mcpServer,
+        skills: options.skills,
+    };
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC"}

package/dist/presets/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Preset bundles for quick agent setup.
+ *
+ * @packageDocumentation
+ */
+export { createProductionAgent, createSecureProductionAgent, DEFAULT_BLOCKED_INPUT_PATTERNS, DEFAULT_BLOCKED_OUTPUT_PATTERNS, type ProductionAgentOptions, type ProductionAgentResult, type SecureProductionAgentOptions, } from "./production.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/presets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presets/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,8BAA8B,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,GAClC,MAAM,iBAAiB,CAAC"}