@execlave/sdk 1.0.2 → 1.1.2

package/dist/instrumentation/events.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * High-level event helpers used by framework adapters (mirror of the
+ * Python events module).
+ *
+ * Helpers run `exe.enforcePolicy(...)` pre-execution and open a span
+ * under the current span stack. Policy-block errors re-raise;
+ * transient enforcement errors are swallowed with a console.warn.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordLlmCall = recordLlmCall;
+exports.recordToolCall = recordToolCall;
+exports.recordAgentAction = recordAgentAction;
+exports.recordRetrieval = recordRetrieval;
+const errors_1 = require("../errors");
+const spans_1 = require("./spans");
+function isEnforcementError(err) {
+    return (err instanceof errors_1.PolicyBlockedError ||
+        err instanceof errors_1.PolicyDeniedError ||
+        err instanceof errors_1.ApprovalTimeoutError ||
+        err instanceof errors_1.EnforcementUnavailableError ||
+        err instanceof errors_1.AgentPausedError);
+}
+async function maybeEnforce(exe, opts) {
+    if (!opts.agentId || opts.input == null)
+        return null;
+    try {
+        return await exe.enforcePolicy({
+            agentId: opts.agentId,
+            input: opts.input,
+            tools: opts.tools,
+            metadata: opts.metadata,
+            estimatedCost: opts.estimatedCost,
+        });
+    }
+    catch (err) {
+        if (isEnforcementError(err))
+            throw err;
+        // eslint-disable-next-line no-console
+        console.warn('[execlave] enforcePolicy failed (non-fatal):', err);
+        return null;
+    }
+}
+function summariseDecision(decision) {
+    if (!decision || typeof decision !== 'object')
+        return {};
+    const out = {};
+    for (const k of ['allowed', 'mode', 'source', 'warnings', 'requiresApproval']) {
+        if (k in decision)
+            out[k] = decision[k];
+    }
+    return out;
+}
+async function recordLlmCall(exe, opts, fn) {
+    const decision = await maybeEnforce(exe, opts);
+    const tree = (0, spans_1.getSpanTree)(exe);
+    const span = tree.start({
+        kind: spans_1.SPAN_KIND_LLM,
+        name: opts.model ?? 'llm',
+        agentId: opts.agentId,
+    });
+    if (opts.input != null)
+        span.setInput(opts.input);
+    if (opts.model)
+        span.setModel(opts.model);
+    if (decision)
+        span.addMetadata({ enforcement: summariseDecision(decision) });
+    try {
+        const result = await fn(span);
+        span.finish('success');
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        span.finish('error', e?.message, e?.name);
+        throw err;
+    }
+}
+async function recordToolCall(exe, opts, fn) {
+    const decision = await maybeEnforce(exe, {
+        agentId: opts.agentId,
+        input: opts.input ?? `tool:${opts.toolName}`,
+        tools: [opts.toolName],
+        metadata: { ...(opts.metadata ?? {}), toolName: opts.toolName },
+    });
+    const tree = (0, spans_1.getSpanTree)(exe);
+    const span = tree.start({
+        kind: spans_1.SPAN_KIND_TOOL,
+        name: opts.toolName,
+        agentId: opts.agentId,
+    });
+    if (opts.input != null)
+        span.setInput(opts.input);
+    span.addMetadata({ toolName: opts.toolName });
+    if (decision)
+        span.addMetadata({ enforcement: summariseDecision(decision) });
+    try {
+        const result = await fn(span);
+        span.finish('success');
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        span.finish('error', e?.message, e?.name);
+        throw err;
+    }
+}
+function recordAgentAction(exe, opts) {
+    const tree = (0, spans_1.getSpanTree)(exe);
+    return tree.start({
+        kind: spans_1.SPAN_KIND_AGENT,
+        name: opts.action,
+        agentId: opts.agentId,
+        metadata: opts.metadata,
+    });
+}
+async function recordRetrieval(exe, opts, fn) {
+    const tree = (0, spans_1.getSpanTree)(exe);
+    const span = tree.start({
+        kind: spans_1.SPAN_KIND_RETRIEVER,
+        name: opts.retrieverName ?? 'retriever',
+        agentId: opts.agentId,
+        metadata: opts.metadata,
+    });
+    span.setInput(opts.query);
+    try {
+        const result = await fn(span);
+        span.finish('success');
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        span.finish('error', e?.message, e?.name);
+        throw err;
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/instrumentation/events.js.map

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

package/dist/instrumentation/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared internal instrumentation layer — JS mirror of
+ * `sdk-python/execlave/instrumentation/`.
+ *
+ * Provides nested span primitives + event helpers consumed by
+ * framework adapters (LangChain, etc.). Zero runtime deps beyond the
+ * base SDK.
+ */
+export { Span, SpanTree, getSpanTree, SPAN_KIND_AGENT, SPAN_KIND_CHAIN, SPAN_KIND_LLM, SPAN_KIND_TOOL, SPAN_KIND_RETRIEVER, SPAN_KIND_GUARDRAIL, SPAN_KIND_HANDOFF, type SpanKind, } from './spans';
+export { recordLlmCall, recordToolCall, recordAgentAction, recordRetrieval, } from './events';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/instrumentation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,eAAe,EACf,eAAe,EACf,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,QAAQ,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,UAAU,CAAC"}

package/dist/instrumentation/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Shared internal instrumentation layer — JS mirror of
+ * `sdk-python/execlave/instrumentation/`.
+ *
+ * Provides nested span primitives + event helpers consumed by
+ * framework adapters (LangChain, etc.). Zero runtime deps beyond the
+ * base SDK.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordRetrieval = exports.recordAgentAction = exports.recordToolCall = exports.recordLlmCall = exports.SPAN_KIND_HANDOFF = exports.SPAN_KIND_GUARDRAIL = exports.SPAN_KIND_RETRIEVER = exports.SPAN_KIND_TOOL = exports.SPAN_KIND_LLM = exports.SPAN_KIND_CHAIN = exports.SPAN_KIND_AGENT = exports.getSpanTree = exports.SpanTree = exports.Span = void 0;
+var spans_1 = require("./spans");
+Object.defineProperty(exports, "Span", { enumerable: true, get: function () { return spans_1.Span; } });
+Object.defineProperty(exports, "SpanTree", { enumerable: true, get: function () { return spans_1.SpanTree; } });
+Object.defineProperty(exports, "getSpanTree", { enumerable: true, get: function () { return spans_1.getSpanTree; } });
+Object.defineProperty(exports, "SPAN_KIND_AGENT", { enumerable: true, get: function () { return spans_1.SPAN_KIND_AGENT; } });
+Object.defineProperty(exports, "SPAN_KIND_CHAIN", { enumerable: true, get: function () { return spans_1.SPAN_KIND_CHAIN; } });
+Object.defineProperty(exports, "SPAN_KIND_LLM", { enumerable: true, get: function () { return spans_1.SPAN_KIND_LLM; } });
+Object.defineProperty(exports, "SPAN_KIND_TOOL", { enumerable: true, get: function () { return spans_1.SPAN_KIND_TOOL; } });
+Object.defineProperty(exports, "SPAN_KIND_RETRIEVER", { enumerable: true, get: function () { return spans_1.SPAN_KIND_RETRIEVER; } });
+Object.defineProperty(exports, "SPAN_KIND_GUARDRAIL", { enumerable: true, get: function () { return spans_1.SPAN_KIND_GUARDRAIL; } });
+Object.defineProperty(exports, "SPAN_KIND_HANDOFF", { enumerable: true, get: function () { return spans_1.SPAN_KIND_HANDOFF; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "recordLlmCall", { enumerable: true, get: function () { return events_1.recordLlmCall; } });
+Object.defineProperty(exports, "recordToolCall", { enumerable: true, get: function () { return events_1.recordToolCall; } });
+Object.defineProperty(exports, "recordAgentAction", { enumerable: true, get: function () { return events_1.recordAgentAction; } });
+Object.defineProperty(exports, "recordRetrieval", { enumerable: true, get: function () { return events_1.recordRetrieval; } });
+//# sourceMappingURL=index.js.map

package/dist/instrumentation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/instrumentation/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,iCAYiB;AAXf,6FAAA,IAAI,OAAA;AACJ,iGAAA,QAAQ,OAAA;AACR,oGAAA,WAAW,OAAA;AACX,wGAAA,eAAe,OAAA;AACf,wGAAA,eAAe,OAAA;AACf,sGAAA,aAAa,OAAA;AACb,uGAAA,cAAc,OAAA;AACd,4GAAA,mBAAmB,OAAA;AACnB,4GAAA,mBAAmB,OAAA;AACnB,0GAAA,iBAAiB,OAAA;AAGnB,mCAKkB;AAJhB,uGAAA,aAAa,OAAA;AACb,wGAAA,cAAc,OAAA;AACd,2GAAA,iBAAiB,OAAA;AACjB,yGAAA,eAAe,OAAA"}

package/dist/instrumentation/spans.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Nested span primitives. Each `Span` wraps the SDK's `Trace` and
+ * carries parent/child identity through the trace metadata so the
+ * backend can reconstruct the execution tree.
+ *
+ * Concurrency model: Node.js is single-threaded, but async tasks can
+ * interleave. We expose `withSpan(span, fn)` so async framework
+ * adapters can scope the "current span" to a specific async operation
+ * without relying on AsyncLocalStorage (keeps footprint zero-dep).
+ * The default stack is process-wide; framework adapters can pass
+ * `parent` explicitly to avoid relying on the implicit stack.
+ */
+import { Trace } from '../trace';
+import type { Execlave } from '../client';
+export declare const SPAN_KIND_AGENT = "agent";
+export declare const SPAN_KIND_CHAIN = "chain";
+export declare const SPAN_KIND_LLM = "llm";
+export declare const SPAN_KIND_TOOL = "tool";
+export declare const SPAN_KIND_RETRIEVER = "retriever";
+export declare const SPAN_KIND_GUARDRAIL = "guardrail";
+export declare const SPAN_KIND_HANDOFF = "handoff";
+export type SpanKind = typeof SPAN_KIND_AGENT | typeof SPAN_KIND_CHAIN | typeof SPAN_KIND_LLM | typeof SPAN_KIND_TOOL | typeof SPAN_KIND_RETRIEVER | typeof SPAN_KIND_GUARDRAIL | typeof SPAN_KIND_HANDOFF;
+export interface StartSpanOptions {
+    kind: SpanKind;
+    name: string;
+    parent?: Span | null;
+    agentId?: string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class Span {
+    readonly spanId: string;
+    readonly parentSpanId: string | null;
+    readonly kind: SpanKind;
+    readonly name: string;
+    private _trace;
+    private _tree;
+    private _finished;
+    constructor(trace: Trace, opts: {
+        spanId: string;
+        parentSpanId: string | null;
+        kind: SpanKind;
+        name: string;
+        tree: SpanTree;
+    });
+    /** Internal: exposed for nested spans to inherit trace id. */
+    get _innerTrace(): Trace;
+    /** Trace id that this span's metadata is attached to. */
+    get traceId(): string;
+    setInput(value: unknown): this;
+    setOutput(value: unknown): this;
+    setModel(model: string): this;
+    setTokens(prompt: number, completion: number): this;
+    setCost(costUsd: number): this;
+    addMetadata(meta: Record<string, unknown>): this;
+    child(opts: {
+        kind: SpanKind;
+        name: string;
+    }): Span;
+    finish(status?: 'success' | 'error' | 'timeout', errorMessage?: string, errorType?: string): void;
+}
+export declare class SpanTree {
+    private _exe;
+    private _stack;
+    constructor(_exe: Execlave);
+    current(): Span | null;
+    start(opts: StartSpanOptions): Span;
+    _pop(span: Span): void;
+}
+export declare function getSpanTree(exe: Execlave): SpanTree;
+//# sourceMappingURL=spans.d.ts.map

package/dist/instrumentation/spans.d.ts.map

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

package/dist/instrumentation/spans.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Nested span primitives. Each `Span` wraps the SDK's `Trace` and
+ * carries parent/child identity through the trace metadata so the
+ * backend can reconstruct the execution tree.
+ *
+ * Concurrency model: Node.js is single-threaded, but async tasks can
+ * interleave. We expose `withSpan(span, fn)` so async framework
+ * adapters can scope the "current span" to a specific async operation
+ * without relying on AsyncLocalStorage (keeps footprint zero-dep).
+ * The default stack is process-wide; framework adapters can pass
+ * `parent` explicitly to avoid relying on the implicit stack.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanTree = exports.Span = exports.SPAN_KIND_HANDOFF = exports.SPAN_KIND_GUARDRAIL = exports.SPAN_KIND_RETRIEVER = exports.SPAN_KIND_TOOL = exports.SPAN_KIND_LLM = exports.SPAN_KIND_CHAIN = exports.SPAN_KIND_AGENT = void 0;
+exports.getSpanTree = getSpanTree;
+const crypto_1 = require("crypto");
+exports.SPAN_KIND_AGENT = 'agent';
+exports.SPAN_KIND_CHAIN = 'chain';
+exports.SPAN_KIND_LLM = 'llm';
+exports.SPAN_KIND_TOOL = 'tool';
+exports.SPAN_KIND_RETRIEVER = 'retriever';
+exports.SPAN_KIND_GUARDRAIL = 'guardrail';
+exports.SPAN_KIND_HANDOFF = 'handoff';
+class Span {
+    constructor(trace, opts) {
+        this._finished = false;
+        this._trace = trace;
+        this.spanId = opts.spanId;
+        this.parentSpanId = opts.parentSpanId;
+        this.kind = opts.kind;
+        this.name = opts.name;
+        this._tree = opts.tree;
+        trace.addMetadata({
+            spanId: this.spanId,
+            parentSpanId: this.parentSpanId,
+            spanKind: this.kind,
+            spanName: this.name,
+        });
+    }
+    /** Internal: exposed for nested spans to inherit trace id. */
+    get _innerTrace() {
+        return this._trace;
+    }
+    /** Trace id that this span's metadata is attached to. */
+    get traceId() {
+        return this._trace.traceId;
+    }
+    setInput(value) {
+        this._trace.setInput(value);
+        return this;
+    }
+    setOutput(value) {
+        this._trace.setOutput(value);
+        return this;
+    }
+    setModel(model) {
+        this._trace.setModel(model);
+        return this;
+    }
+    setTokens(prompt, completion) {
+        this._trace.setTokens(prompt, completion);
+        return this;
+    }
+    setCost(costUsd) {
+        this._trace.setCost(costUsd);
+        return this;
+    }
+    addMetadata(meta) {
+        this._trace.addMetadata(meta);
+        return this;
+    }
+    child(opts) {
+        return this._tree.start({ ...opts, parent: this });
+    }
+    finish(status = 'success', errorMessage, errorType) {
+        if (this._finished)
+            return;
+        this._finished = true;
+        this._tree._pop(this);
+        try {
+            this._trace.finish(status, errorMessage, errorType);
+        }
+        catch {
+            // transport/buffer errors are never fatal for the host app.
+        }
+    }
+}
+exports.Span = Span;
+class SpanTree {
+    constructor(_exe) {
+        this._exe = _exe;
+        this._stack = [];
+    }
+    current() {
+        return this._stack.length > 0 ? this._stack[this._stack.length - 1] : null;
+    }
+    start(opts) {
+        const parent = opts.parent ?? this.current();
+        const parentId = parent ? parent.spanId : null;
+        const inherited = parent ? parent._innerTrace : null;
+        const trace = this._exe.startTrace({
+            traceId: inherited ? inherited.traceId : undefined,
+            agentId: opts.agentId ?? inherited?.agentId,
+            sessionId: opts.sessionId ?? inherited?.sessionId,
+            userId: opts.userId ?? inherited?.userId,
+            metadata: opts.metadata,
+        });
+        const spanId = `sp_${(0, crypto_1.randomBytes)(8).toString('hex')}`;
+        const span = new Span(trace, {
+            spanId,
+            parentSpanId: parentId,
+            kind: opts.kind,
+            name: opts.name,
+            tree: this,
+        });
+        this._stack.push(span);
+        return span;
+    }
+    _pop(span) {
+        const idx = this._stack.lastIndexOf(span);
+        if (idx >= 0)
+            this._stack.splice(idx, 1);
+    }
+}
+exports.SpanTree = SpanTree;
+const _treeCache = new WeakMap();
+function getSpanTree(exe) {
+    let tree = _treeCache.get(exe);
+    if (!tree) {
+        tree = new SpanTree(exe);
+        _treeCache.set(exe, tree);
+    }
+    return tree;
+}
+//# sourceMappingURL=spans.js.map

package/dist/instrumentation/spans.js.map

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

package/dist/integrations/crewai.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CrewAI auto-instrumentation.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { Crew } from 'crewai';
+ * import { Execlave } from '@execlave/sdk';
+ * import { instrumentCrew } from '@execlave/sdk/integrations/crewai';
+ *
+ * const exe = new Execlave({ apiKey: '...' });
+ * const crew = new Crew({ agents: [...], tasks: [...] });
+ * instrumentCrew(crew, exe, { agentId: 'my-crew' });
+ * await crew.kickoff();
+ * ```
+ *
+ * Implementation: CrewAI exposes `stepCallback` and `taskCallback` hooks
+ * on `Agent` and `Crew` objects. We chain our callbacks in front of any
+ * existing user callbacks so attaching the instrumentation never
+ * overrides user-supplied hooks.
+ *
+ * Idempotent — `_execlaveInstrumented` marker prevents double-wrapping.
+ *
+ * Note: CrewAI's first-class JS implementation is still emerging; this
+ * helper duck-types the callback shape so it works with both the
+ * official package and community ports. No compile-time dependency.
+ */
+import type { Execlave } from '../client';
+export interface InstrumentCrewOptions {
+    /** Agent id registered with Execlave. Required for enforcement. */
+    agentId: string;
+    /** Run `enforcePolicy` on tool steps. Default true. */
+    enforce?: boolean;
+    sessionId?: string;
+    userId?: string;
+}
+/**
+ * Attach Execlave instrumentation to a CrewAI `Crew` instance.
+ *
+ * Idempotent: calling twice on the same crew is a no-op. Returns the
+ * same crew for fluent chaining.
+ */
+export declare function instrumentCrew<T>(crew: T, exe: Execlave, opts: InstrumentCrewOptions): T;
+//# sourceMappingURL=crewai.d.ts.map

package/dist/integrations/crewai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crewai.d.ts","sourceRoot":"","sources":["../../src/integrations/crewai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AA2B1C,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,qBAAqB,GAAG,CAAC,CAqDxF"}