@execlave/sdk 1.0.2

package/README.md

@@ -0,0 +1,131 @@
+# @execlave/sdk
+
+Official JavaScript/TypeScript SDK for the [Execlave](https://github.com/Execlave) AI agent governance platform.
+
+## Installation
+
+```bash
+npm install @execlave/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Execlave } from '@execlave/sdk';
+
+// Initialize the SDK
+const ag = new Execlave({
+  apiKey: 'exe_prod_xxx', // or set EXECLAVE_API_KEY env var
+  environment: 'production',
+});
+
+// Register your agent (idempotent — call on startup)
+const agent = await ag.registerAgent({
+  agentId: 'my-chatbot',
+  name: 'Customer Support Bot',
+  type: 'chatbot',
+  platform: 'custom',
+});
+
+// Trace an LLM call
+const trace = ag.startTrace({ agentId: 'my-chatbot', sessionId: 'sess_123' });
+trace.setInput(userQuestion);
+
+const answer = await llm.call(userQuestion);
+
+trace.setOutput(answer).setModel('gpt-4-turbo').setTokens(150, 300).setCost(0.012);
+trace.finish(); // submits to buffer; flushed in background
+
+// Or use the wrap() helper for automatic tracing
+const tracedCall = ag.wrap(
+  async (question: string) => {
+    return await llm.call(question);
+  },
+  { agentId: 'my-chatbot' },
+);
+
+const result = await tracedCall('Hello!');
+
+// Prompt management
+const version = await agent.deployPrompt({
+  promptTemplate: 'You are a helpful assistant. Answer: {question}',
+  systemMessage: 'Be concise.',
+  modelName: 'gpt-4-turbo',
+  changeSummary: 'Improved conciseness',
+});
+
+// Kill-switch aware
+try {
+  const trace = ag.startTrace();
+  // ...
+} catch (err) {
+  if (err instanceof AgentPausedError) {
+    return 'Service temporarily unavailable.';
+  }
+  throw err;
+}
+
+// Graceful shutdown (flushes remaining traces)
+await ag.shutdown();
+```
+
+## Configuration
+
+| Option                 | Type      | Default                    | Description                        |
+| ---------------------- | --------- | -------------------------- | ---------------------------------- |
+| `apiKey`               | `string`  | `EXECLAVE_API_KEY` env     | API key (`ag_xxx`)                 |
+| `baseUrl`              | `string`  | `https://api.execlave.com` | Execlave API URL                   |
+| `environment`          | `string`  | `production`               | Deployment environment             |
+| `asyncMode`            | `boolean` | `true`                     | Buffer traces for background flush |
+| `batchSize`            | `number`  | `100`                      | Max traces per flush batch         |
+| `flushIntervalMs`      | `number`  | `10000`                    | Background flush interval          |
+| `debug`                | `boolean` | `false`                    | Enable debug logging               |
+| `enableControlChannel` | `boolean` | `true`                     | Poll agent status for kill-switch  |
+| `pollIntervalMs`       | `number`  | `15000`                    | Status poll interval               |
+
+## API Reference
+
+### `Execlave`
+
+- `ping()` — Check API connectivity
+- `registerAgent(opts)` — Register an AI agent
+- `startTrace(opts)` — Start a manual trace
+- `wrap(fn, opts)` — Wrap a function with automatic tracing
+- `checkAgentStatus(agentId?)` — Get agent status
+- `flush()` — Flush buffered traces
+- `shutdown()` — Flush and shut down
+
+### `Agent`
+
+- `deployPrompt(opts)` — Deploy a new prompt version
+- `getCurrentPrompt()` — Get the deployed prompt
+- `listPromptVersions()` — List all versions
+- `refreshStatus()` — Refresh agent status
+- `isPaused` — Whether agent is kill-switched
+
+### `Trace`
+
+- `setInput(data)` — Set input data (chainable)
+- `setOutput(data)` — Set output data (chainable)
+- `setModel(name)` — Set model name (chainable)
+- `setTokens(prompt, completion)` — Set token counts (chainable)
+- `setCost(usd)` — Set cost (chainable)
+- `addMetadata(meta)` — Add metadata (chainable)
+- `finish(status?, error?, errorType?)` — Submit the trace
+
+## Zero Dependencies
+
+This SDK has **zero runtime dependencies**. It uses Node.js built-in `http`/`https` modules for network requests.
+
+## Legal
+
+By using this SDK, you agree to the [Execlave Terms of Service](https://execlave.com/terms).
+
+- [Privacy Policy](https://execlave.com/privacy)
+- [Acceptable Use Policy](https://execlave.com/acceptable-use)
+- [Responsible AI](https://execlave.com/responsible-ai)
+- [Security](https://execlave.com/security)
+
+## License
+
+MIT — see [LICENSE](../LICENSE) for details.

package/dist/agent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent object returned from `ag.registerAgent()`.
+ *
+ * Provides prompt management methods and exposes agent metadata.
+ */
+import type { AgentData, DeployPromptOptions, PromptVersionData } from './types';
+/** Back-reference interface — avoids circular imports. */
+interface ClientRef {
+    _request(method: string, path: string, body?: unknown): Promise<any>;
+    _apiPath(path: string): string;
+}
+export declare class Agent {
+    readonly id: string;
+    readonly agentId: string;
+    readonly name: string;
+    readonly environment: string;
+    status: string;
+    private _client;
+    private _data;
+    constructor(client: ClientRef, data: AgentData);
+    /** Whether this agent is currently paused via the kill switch. */
+    get isPaused(): boolean;
+    /**
+     * Deploy a new prompt version for this agent.
+     *
+     * @returns The created PromptVersion metadata.
+     */
+    deployPrompt(opts: DeployPromptOptions): Promise<PromptVersionData>;
+    /**
+     * Get the currently deployed prompt version for this agent.
+     *
+     * @returns PromptVersionData or null if no version is deployed.
+     */
+    getCurrentPrompt(): Promise<PromptVersionData | null>;
+    /**
+     * List all prompt versions for this agent.
+     */
+    listPromptVersions(): Promise<PromptVersionData[]>;
+    /** Refresh agent status from the API. */
+    refreshStatus(): Promise<string>;
+    /**
+     * Rollback to a specific prompt version.
+     *
+     * @param versionNumber - The version number to rollback to.
+     * @param reason        - Required reason for the rollback.
+     * @returns The activated PromptVersionData.
+     */
+    rollbackToVersion(versionNumber: number, reason: string): Promise<PromptVersionData>;
+    /**
+     * Promote a staging prompt version to production.
+     *
+     * @param versionId       - The version ID to promote.
+     * @param requireApproval - Whether to require admin approval.
+     * @param deploymentNotes - Notes for the deployment.
+     * @returns The promoted PromptVersionData.
+     */
+    promoteToProduction(versionId: string, opts?: {
+        requireApproval?: boolean;
+        deploymentNotes?: string;
+    }): Promise<PromptVersionData>;
+    /** Return raw agent data. */
+    toJSON(): AgentData;
+}
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAe,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE9F,0DAA0D;AAC1D,UAAU,SAAS;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,OAAO,CAAY;IAC3B,OAAO,CAAC,KAAK,CAAY;gBAEb,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS;IAU9C,kEAAkE;IAClE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmBzE;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAS3D;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAQxD,yCAAyC;IACnC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAMtC;;;;;;OAMG;IACG,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAY1F;;;;;;;OAOG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,OAAO,CAAC,iBAAiB,CAAC;IAS7B,6BAA6B;IAC7B,MAAM,IAAI,SAAS;CAGpB"}

package/dist/agent.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Agent object returned from `ag.registerAgent()`.
+ *
+ * Provides prompt management methods and exposes agent metadata.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+class Agent {
+    constructor(client, data) {
+        this._client = client;
+        this._data = data;
+        this.id = data.id;
+        this.agentId = data.agentId;
+        this.name = data.name;
+        this.environment = data.environment;
+        this.status = data.status;
+    }
+    /** Whether this agent is currently paused via the kill switch. */
+    get isPaused() {
+        return this.status === 'paused';
+    }
+    /**
+     * Deploy a new prompt version for this agent.
+     *
+     * @returns The created PromptVersion metadata.
+     */
+    async deployPrompt(opts) {
+        const params = opts.modelParameters ?? {};
+        const payload = {
+            agentId: this.id,
+            promptTemplate: opts.promptTemplate,
+            systemMessage: opts.systemMessage ?? null,
+            modelName: opts.modelName ?? null,
+            temperature: params.temperature ?? null,
+            maxTokens: params.max_tokens ?? params.maxTokens ?? null,
+            // Backend schema uses 'changeSummary' not 'changeType'
+            changeSummary: opts.changeDescription ?? opts.changeType ?? null,
+            versionTag: opts.versionTag ?? null,
+            notes: opts.changeDescription ?? null,
+        };
+        const resp = await this._client._request('POST', this._client._apiPath('/prompt-versions'), payload);
+        return resp.data;
+    }
+    /**
+     * Get the currently deployed prompt version for this agent.
+     *
+     * @returns PromptVersionData or null if no version is deployed.
+     */
+    async getCurrentPrompt() {
+        const resp = await this._client._request('GET', `${this._client._apiPath('/prompt-versions')}?agentId=${encodeURIComponent(this.id)}&deployed=true`);
+        const versions = resp.data;
+        return versions.find((v) => v.isDeployed) ?? null;
+    }
+    /**
+     * List all prompt versions for this agent.
+     */
+    async listPromptVersions() {
+        const resp = await this._client._request('GET', `${this._client._apiPath('/prompt-versions')}?agentId=${encodeURIComponent(this.id)}`);
+        return resp.data;
+    }
+    /** Refresh agent status from the API. */
+    async refreshStatus() {
+        const resp = await this._client._request('GET', this._client._apiPath(`/agents/${this.id}/status-poll`));
+        this.status = resp.data?.status ?? this.status;
+        return this.status;
+    }
+    /**
+     * Rollback to a specific prompt version.
+     *
+     * @param versionNumber - The version number to rollback to.
+     * @param reason        - Required reason for the rollback.
+     * @returns The activated PromptVersionData.
+     */
+    async rollbackToVersion(versionNumber, reason) {
+        const versions = await this.listPromptVersions();
+        const target = versions.find((v) => v.versionNumber === versionNumber);
+        if (!target) {
+            throw new Error(`Prompt version ${versionNumber} not found for agent ${this.agentId}`);
+        }
+        const resp = await this._client._request('POST', this._client._apiPath(`/prompt-versions/${target.id}/rollback`), {
+            reason,
+        });
+        return resp.data;
+    }
+    /**
+     * Promote a staging prompt version to production.
+     *
+     * @param versionId       - The version ID to promote.
+     * @param requireApproval - Whether to require admin approval.
+     * @param deploymentNotes - Notes for the deployment.
+     * @returns The promoted PromptVersionData.
+     */
+    async promoteToProduction(versionId, opts) {
+        const resp = await this._client._request('POST', this._client._apiPath(`/prompt-versions/${versionId}/deploy`), {
+            environment: 'production',
+            requireApproval: opts?.requireApproval ?? true,
+            deploymentNotes: opts?.deploymentNotes ?? null,
+        });
+        return resp.data;
+    }
+    /** Return raw agent data. */
+    toJSON() {
+        return { ...this._data, status: this.status };
+    }
+}
+exports.Agent = Agent;
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Execlave SDK — Main client.
+ *
+ * Provides the Execlave class for agent registration, tracing, and governance.
+ * Implements non-blocking trace ingestion with an in-memory circular buffer
+ * and a background flush interval.
+ */
+import { Agent } from './agent';
+import { Trace } from './trace';
+import type { ExeclaveConfig, RegisterAgentOptions, TraceOptions, TracePayload, EnforcePolicyOptions, EnforceResult, AuthorizeCallOptions, AuthorizeResult, DiscoveredAgent, UsageStatus } from './types';
+/**
+ * Main entry point for the Execlave JavaScript SDK.
+ *
+ * @example
+ * ```ts
+ * const ag = new Execlave({ apiKey: 'exe_prod_xxx', environment: 'production' });
+ * const agent = await exe.registerAgent({ agentId: 'my-bot', name: 'My Bot' });
+ *
+ * const trace = exe.startTrace({ agentId: 'my-bot' });
+ * trace.setInput(question);
+ * const answer = await llm.call(question);
+ * trace.setOutput(answer).setModel('gpt-4').setTokens(100, 200);
+ * trace.finish();
+ *
+ * // Before process exit
+ * await exe.shutdown();
+ * ```
+ */
+export declare class Execlave {
+    private _apiKey;
+    private _baseUrl;
+    private _apiVersion;
+    private _environment;
+    private _asyncMode;
+    private _batchSize;
+    private _flushIntervalMs;
+    private _debug;
+    private _enableControlChannel;
+    private _pollIntervalMs;
+    private _privacy;
+    private _enableInjectionScan;
+    private _mode;
+    private _otlpEndpoint?;
+    private _otelExporter;
+    private _otelReady;
+    private _state;
+    private _buffer;
+    private _agents;
+    private _flushTimer;
+    private _pollTimer;
+    private _heartbeatTimer;
+    private _socket;
+    private _cbFailures;
+    private _cbThreshold;
+    private _cbOpen;
+    private _cbOpenAt;
+    private _cbResetAfterMs;
+    private _cbLastError?;
+    private _policyCache;
+    private _policyCacheTtlMs;
+    private _quotaExceeded;
+    private _quotaCacheTtlMs;
+    private _enforcementOnOutage;
+    private _planLimitBehavior;
+    private _heartbeatIntervalMs;
+    constructor(config?: ExeclaveConfig);
+    /**
+     * Build a versioned API path.
+     *
+     * If `apiVersion` is set (e.g. `'v1'`), returns `/api/v1${path}`.
+     * Otherwise falls back to the legacy `/api${path}` format.
+     */
+    private apiPath;
+    /** Check if the Execlave API is reachable. */
+    ping(): Promise<boolean>;
+    /**
+     * Register (or re-register) an AI agent. Idempotent — call on startup.
+     *
+     * @returns An Agent object with prompt management methods.
+     */
+    registerAgent(opts: RegisterAgentOptions): Promise<Agent>;
+    /**
+     * Start a manual trace. Call `trace.finish()` when done.
+     *
+     * @returns A Trace handle with chainable setters.
+     */
+    startTrace(opts?: TraceOptions): Trace;
+    /**
+     * Wrap an async function with automatic tracing.
+     *
+     * @example
+     * ```ts
+     * const tracedAnswer = exe.wrap(async (question: string) => {
+     *   return await llm.call(question);
+     * }, { agentId: 'my-bot' });
+     *
+     * const answer = await tracedAnswer('Hello?');
+     * ```
+     */
+    wrap<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, opts?: TraceOptions): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * Check the current status of a registered agent.
+     *
+     * @returns 'active', 'paused', or 'error'.
+     */
+    checkAgentStatus(agentId?: string): Promise<string>;
+    /** Flush all buffered traces to the API. */
+    flush(): Promise<void>;
+    /**
+     * Pre-execution policy enforcement.
+     *
+     * Call this **before** running the LLM to check whether policies allow execution.
+     * Throws `PolicyBlockedError` if any policy with `enforcement_mode='block'` is violated.
+     * Returns warnings for `warn`-mode violations.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const result = await exe.enforcePolicy({
+     *     agentId: agent.id,
+     *     input: userQuestion,
+     *     tools: ['web_search'],
+     *   });
+     *   if (result.warnings?.length) console.warn('Policy warnings:', result.warnings);
+     *   // Safe to proceed
+     *   const answer = await llm.call(userQuestion);
+     * } catch (err) {
+     *   if (err instanceof PolicyBlockedError) {
+     *     return 'Sorry, I cannot process that request.';
+     *   }
+     * }
+     * ```
+     */
+    enforcePolicy(opts: EnforcePolicyOptions): Promise<EnforceResult>;
+    private _cbRecordSuccess;
+    private _cbRecordFailure;
+    private _cbIsOpen;
+    private _policyCacheKey;
+    private _policyCacheGet;
+    private _policyCacheSet;
+    private _toInt;
+    private _quotaErrorFromBody;
+    private _setQuotaExceeded;
+    private _getCachedQuotaExceeded;
+    private _throwIfQuotaExceeded;
+    private _sendHeartbeats;
+    private _pollApprovalDecision;
+    /**
+     * Check if one agent is authorized to call another.
+     *
+     * @returns Authorization result. Throws `ExeclaveAuthError` on 403.
+     */
+    authorizeAgentCall(opts: AuthorizeCallOptions): Promise<AuthorizeResult>;
+    /**
+     * Discover agents by capability.
+     *
+     * @param capability Optional capability to filter by (e.g. 'send_email').
+     *                   If omitted, returns all agents with capabilities.
+     */
+    discoverAgents(capability?: string): Promise<DiscoveredAgent[]>;
+    /**
+     * Return current plan usage and limits.
+     */
+    checkUsage(): Promise<UsageStatus>;
+    /** Flush remaining traces and shut down the SDK. */
+    shutdown(): Promise<void>;
+    /** @internal */
+    _bufferTrace(payload: TracePayload): void;
+    /** @internal */
+    _apiPath(path: string): string;
+    /** @internal */
+    _request(method: string, path: string, body?: unknown): Promise<any>;
+    private _requestRaw;
+    /**
+     * Resolve an external agentId string to the internal UUID.
+     * The API endpoints like /policies/enforce expect the internal UUID,
+     * but users naturally pass the external agentId (e.g. "my-bot").
+     * This looks up the cached Agent and returns its UUID (.id).
+     * If no match is found, returns the original value unchanged.
+     */
+    private _resolveAgentId;
+    private _doFlush;
+    private _statusPoll;
+    private _hashPii;
+    private _toText;
+    private _scrubText;
+    private _applyPrivacy;
+    private _scanInjection;
+    private _firstAgentId;
+    private _firstAgent;
+    private _ensureNotShutdown;
+    private _sleep;
+    /**
+     * Connect to the Socket.IO /sdk namespace for real-time control channel.
+     * Falls back silently to HTTP polling if socket.io-client is not installed.
+     */
+    private _connectWebSocket;
+    private _log;
+    private _logError;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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