@pentatonic-ai/ai-agent-sdk 0.3.0-beta.3

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pentatonic-ai/ai-agent-sdk",
+  "version": "0.3.0-beta.3",
+  "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "ai-agent-sdk": "./bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "build.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepare": "node build.js",
+    "build": "node build.js",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --config jest.config.cjs",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --config jest.config.cjs --watch",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "tes",
+    "thing-event-system",
+    "pentatonic",
+    "llm",
+    "observability",
+    "ai",
+    "openai",
+    "anthropic",
+    "product-lifecycle",
+    "event-sourcing",
+    "circular-commerce",
+    "agentic-commerce",
+    "vector-search",
+    "graphql",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "homepage": "https://thingeventsystem.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Pentatonic-Ltd/ai-agent-sdk.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "esbuild": "^0.20.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "jest": "^29.7.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,60 @@
+import { Session } from "./session.js";
+import { wrapClient } from "./wrapper.js";
+
+export class TESClient {
+  constructor({ clientId, apiKey, endpoint, headers, userId, captureContent = true, maxContentLength = 4096 }) {
+    if (!clientId) throw new Error("clientId is required");
+    if (!apiKey) throw new Error("apiKey is required");
+    if (!endpoint) throw new Error("endpoint is required");
+
+    const cleanEndpoint = endpoint.replace(/\/$/, "");
+    const isLocalDev =
+      /^http:\/\/localhost(:\d+)?(\/|$)/.test(cleanEndpoint) ||
+      /^http:\/\/127\.0\.0\.1(:\d+)?(\/|$)/.test(cleanEndpoint);
+    if (!cleanEndpoint.startsWith("https://") && !isLocalDev) {
+      throw new Error(
+        "endpoint must use https:// (http:// is only allowed for localhost)"
+      );
+    }
+
+    this.clientId = clientId;
+    this.endpoint = cleanEndpoint;
+    this.userId = userId || null;
+    this.captureContent = captureContent;
+    this.maxContentLength = maxContentLength;
+
+    // Store apiKey and headers as non-enumerable so they won't appear in
+    // JSON.stringify, console.log, or error reporter serialization.
+    Object.defineProperty(this, "_apiKey", {
+      value: apiKey,
+      enumerable: false,
+      writable: false,
+    });
+    Object.defineProperty(this, "_headers", {
+      value: headers || {},
+      enumerable: false,
+      writable: false,
+    });
+  }
+
+  get _config() {
+    return {
+      clientId: this.clientId,
+      apiKey: this._apiKey,
+      endpoint: this.endpoint,
+      headers: this._headers,
+      userId: this.userId,
+      captureContent: this.captureContent,
+      maxContentLength: this.maxContentLength,
+    };
+  }
+
+  session(opts) {
+    return new Session(this._config, opts);
+  }
+
+  wrap(client, { sessionId, userId, metadata, autoEmit = true, waitUntil } = {}) {
+    const config = userId ? { ...this._config, userId } : this._config;
+    return wrapClient(config, client, { sessionId, metadata, autoEmit, waitUntil });
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { TESClient } from "./client.js";
+export { Session } from "./session.js";
+export { normalizeResponse } from "./normalizer.js";
+export { signPayload, verifyPayload, buildTrackUrl, rewriteUrls } from "./tracking.js";

package/src/normalizer.js

@@ -0,0 +1,111 @@
+/**
+ * Normalize an LLM response from any supported provider into a common shape.
+ * Detects format by duck-typing: OpenAI (choices), Anthropic (content array), Workers AI (response string).
+ */
+export function normalizeResponse(raw) {
+  if (!raw || typeof raw !== "object") {
+    return empty();
+  }
+
+  // OpenAI SDK format: { choices, usage, model }
+  if (Array.isArray(raw.choices)) {
+    return normalizeOpenAI(raw);
+  }
+
+  // Anthropic SDK format: { content: [{ type: "text"|"tool_use", ... }], usage: { input_tokens, output_tokens } }
+  if (Array.isArray(raw.content) && raw.content[0]?.type) {
+    return normalizeAnthropic(raw);
+  }
+
+  // Workers AI format: { response: "...", tool_calls: [...] }
+  if (typeof raw.response === "string" || (raw.tool_calls && !raw.choices)) {
+    return normalizeWorkersAI(raw);
+  }
+
+  return empty();
+}
+
+function empty() {
+  return {
+    content: "",
+    model: null,
+    usage: { prompt_tokens: 0, completion_tokens: 0 },
+    toolCalls: [],
+  };
+}
+
+function normalizeOpenAI(raw) {
+  const message = raw.choices?.[0]?.message || {};
+  const usage = raw.usage || {};
+  // Workers AI sometimes puts tool_calls at top level instead of inside message
+  const rawToolCalls = message.tool_calls?.length
+    ? message.tool_calls
+    : raw.tool_calls || [];
+  const toolCalls = rawToolCalls.map((tc) => ({
+    tool: tc.function?.name || tc.name,
+    args: parseArgs(tc.function?.arguments || tc.arguments),
+  }));
+
+  return {
+    content: message.content || "",
+    model: raw.model || null,
+    usage: {
+      prompt_tokens: usage.prompt_tokens || 0,
+      completion_tokens: usage.completion_tokens || 0,
+    },
+    toolCalls,
+  };
+}
+
+function normalizeAnthropic(raw) {
+  const usage = raw.usage || {};
+  let content = "";
+  const toolCalls = [];
+
+  for (const block of raw.content) {
+    if (block.type === "text") {
+      content += block.text;
+    } else if (block.type === "tool_use") {
+      toolCalls.push({ tool: block.name, args: block.input || {} });
+    }
+  }
+
+  return {
+    content,
+    model: raw.model || null,
+    usage: {
+      prompt_tokens: usage.input_tokens || 0,
+      completion_tokens: usage.output_tokens || 0,
+    },
+    toolCalls,
+  };
+}
+
+function normalizeWorkersAI(raw) {
+  const usage = raw.usage || {};
+  const toolCalls = (raw.tool_calls || []).map((tc) => ({
+    tool: tc.function?.name || tc.name,
+    args: parseArgs(tc.function?.arguments || tc.arguments || {}),
+  }));
+
+  return {
+    content: raw.response || "",
+    model: raw.model || null,
+    usage: {
+      prompt_tokens: usage.prompt_tokens || 0,
+      completion_tokens: usage.completion_tokens || 0,
+    },
+    toolCalls,
+  };
+}
+
+function parseArgs(args) {
+  if (typeof args === "string") {
+    try {
+      return JSON.parse(args);
+    } catch {
+      return {};
+    }
+  }
+  return args || {};
+}

package/src/session.js

@@ -0,0 +1,181 @@
+import { normalizeResponse } from "./normalizer.js";
+import { sendEvent } from "./transport.js";
+import { buildTrackUrl } from "./tracking.js";
+
+function truncate(value, maxLen) {
+  if (!value || !maxLen || typeof value !== "string") return value;
+  if (value.length <= maxLen) return value;
+  return value.slice(0, maxLen) + "...[truncated]";
+}
+
+export class Session {
+  constructor(clientConfig, { sessionId, metadata } = {}) {
+    Object.defineProperty(this, '_config', {
+      value: clientConfig,
+      enumerable: false,
+    });
+    this.sessionId = sessionId || crypto.randomUUID();
+    this._metadata = metadata || {};
+    this._reset();
+  }
+
+  _reset() {
+    this._promptTokens = 0;
+    this._completionTokens = 0;
+    this._rounds = 0;
+    this._toolCalls = [];
+    this._model = null;
+    this._systemPrompt = null;
+  }
+
+  get totalUsage() {
+    return {
+      prompt_tokens: this._promptTokens,
+      completion_tokens: this._completionTokens,
+      total_tokens: this._promptTokens + this._completionTokens,
+      ai_rounds: this._rounds,
+    };
+  }
+
+  get toolCalls() {
+    return this._toolCalls;
+  }
+
+  record(rawResponse) {
+    const normalized = normalizeResponse(rawResponse);
+    const round = this._rounds;
+
+    this._promptTokens += normalized.usage.prompt_tokens;
+    this._completionTokens += normalized.usage.completion_tokens;
+    this._rounds += 1;
+
+    if (normalized.model) {
+      this._model = normalized.model;
+    }
+
+    for (const tc of normalized.toolCalls) {
+      this._toolCalls.push({ ...tc, round });
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Attach a result summary to the most recent tool call matching `toolName`.
+   * Call this after executing a tool to include results in the emitted event.
+   */
+  recordToolResult(toolName, result) {
+    for (let i = this._toolCalls.length - 1; i >= 0; i--) {
+      if (this._toolCalls[i].tool === toolName && !this._toolCalls[i].result) {
+        this._toolCalls[i].result = result;
+        return;
+      }
+    }
+  }
+
+  async emitChatTurn({ userMessage, assistantResponse, turnNumber, messages }) {
+    const capture = this._config.captureContent !== false;
+    const maxLen = this._config.maxContentLength;
+
+    // Spread metadata first so SDK-controlled fields always win
+    const attributes = {
+      ...this._metadata,
+      source: "pentatonic-ai-sdk",
+      model: this._model,
+      usage: this.totalUsage,
+      tool_calls: this._toolCalls.length
+        ? (capture ? this._toolCalls : this._toolCalls.map(({ args, ...rest }) => rest))
+        : undefined,
+    };
+
+    if (capture) {
+      attributes.user_message = truncate(userMessage, maxLen);
+      attributes.assistant_response = truncate(assistantResponse, maxLen);
+      if (this._systemPrompt) {
+        attributes.system_prompt = truncate(this._systemPrompt, maxLen);
+      }
+
+      if (messages) {
+        attributes.messages = messages.map((m) => {
+          if (typeof m.content === "string") {
+            return { ...m, content: truncate(m.content, maxLen) };
+          }
+          return m;
+        });
+      }
+    }
+
+    if (turnNumber !== undefined) {
+      attributes.turn_number = turnNumber;
+    }
+
+    const result = await sendEvent(this._config, {
+      eventType: "CHAT_TURN",
+      entityType: "conversation",
+      data: {
+        entity_id: this.sessionId,
+        attributes,
+      },
+    });
+
+    this._reset();
+    return result;
+  }
+
+  async emitToolUse({ tool, args, resultSummary, durationMs, turnNumber }) {
+    const capture = this._config.captureContent !== false;
+    const maxLen = this._config.maxContentLength;
+
+    const attributes = {
+      ...this._metadata,
+      source: "pentatonic-ai-sdk",
+      tool,
+      duration_ms: durationMs,
+      turn_number: turnNumber,
+    };
+
+    if (capture) {
+      attributes.args = args;
+      attributes.result_summary = truncate(resultSummary, maxLen);
+    }
+
+    // Spread metadata first so SDK-controlled fields always win
+    return sendEvent(this._config, {
+      eventType: "TOOL_USE",
+      entityType: "conversation",
+      data: {
+        entity_id: this.sessionId,
+        attributes,
+      },
+    });
+  }
+
+  async trackUrl(url, { eventType, attributes } = {}) {
+    const payload = {
+      u: url,
+      s: this.sessionId,
+      c: this._config.clientId,
+      t: Math.floor(Date.now() / 1000),
+      e: eventType || "LINK_CLICK",
+    };
+    const meta = { ...this._metadata, ...attributes };
+    if (Object.keys(meta).length) {
+      payload.a = meta;
+    }
+    return buildTrackUrl(this._config.endpoint, this._config.apiKey, payload);
+  }
+
+  async emitSessionStart() {
+    return sendEvent(this._config, {
+      eventType: "SESSION_START",
+      entityType: "conversation",
+      data: {
+        entity_id: this.sessionId,
+        attributes: {
+          source: "pentatonic-ai-sdk",
+          metadata: this._metadata,
+        },
+      },
+    });
+  }
+}

package/src/tracking.js

@@ -0,0 +1,119 @@
+/**
+ * HMAC signing and URL rewriting utilities for click tracking.
+ *
+ * Uses the Web Crypto API (works in browsers, Node 18+, Cloudflare Workers).
+ */
+
+const encoder = new TextEncoder();
+
+/**
+ * Encode bytes to base64url (RFC 4648 §5) — no padding.
+ */
+function toBase64Url(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * HMAC-SHA256 sign a JSON payload, returning a base64url signature.
+ *
+ * @param {string} secret  Shared secret (TES_INTERNAL_SERVICE_KEY)
+ * @param {object} payload Object to sign (serialised to canonical JSON)
+ * @returns {Promise<string>} base64url HMAC signature
+ */
+export async function signPayload(secret, payload) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const data = encoder.encode(JSON.stringify(payload));
+  const sig = await crypto.subtle.sign("HMAC", key, data);
+  return toBase64Url(sig);
+}
+
+/**
+ * Verify a payload against a base64url HMAC-SHA256 signature.
+ *
+ * @param {string} secret    Shared secret
+ * @param {object} payload   Payload object
+ * @param {string} signature base64url signature to verify
+ * @returns {Promise<boolean>}
+ */
+export async function verifyPayload(secret, payload, signature) {
+  const expected = await signPayload(secret, payload);
+  return expected === signature;
+}
+
+/**
+ * Build a TES redirect/tracking URL.
+ *
+ * @param {string} endpoint TES API base URL (no trailing slash)
+ * @param {string} apiKey   Shared secret for signing
+ * @param {object} payload  Tracking payload with short keys (u, s, c, t, e, a)
+ * @returns {Promise<string>} Full redirect URL
+ */
+export async function buildTrackUrl(endpoint, apiKey, payload) {
+  const p = { ...payload };
+  if (!p.e) p.e = "LINK_CLICK";
+
+  const encoded = toBase64Url(encoder.encode(JSON.stringify(p)));
+  const sig = await signPayload(apiKey, p);
+  return `${endpoint}/r/${encoded}?sig=${sig}`;
+}
+
+const URL_RE = /https?:\/\/[^\s"'<>)\]]+/g;
+
+/**
+ * Scan text for URLs and rewrite each as a tracked redirect URL.
+ *
+ * URLs already pointing at the TES redirect endpoint are left untouched.
+ *
+ * @param {string} text       Text (typically an LLM response) to scan
+ * @param {object} config     { endpoint, apiKey, clientId }
+ * @param {string} sessionId  Current session ID
+ * @param {object} [metadata] Optional attributes merged into payload.a
+ * @returns {Promise<string>} Text with URLs replaced
+ */
+export async function rewriteUrls(text, config, sessionId, metadata) {
+  if (!text) return text;
+
+  const redirectPrefix = `${config.endpoint}/r/`;
+  const matches = [...text.matchAll(URL_RE)];
+
+  if (matches.length === 0) return text;
+
+  // Build tracked URLs for each unique original URL (preserving order)
+  const replacements = new Map();
+  for (const m of matches) {
+    const originalUrl = m[0];
+    if (originalUrl.startsWith(redirectPrefix)) continue;
+    if (replacements.has(originalUrl)) continue;
+
+    const payload = {
+      u: originalUrl,
+      s: sessionId,
+      c: config.clientId,
+      t: Math.floor(Date.now() / 1000),
+    };
+    if (metadata && Object.keys(metadata).length > 0) {
+      payload.a = metadata;
+    }
+
+    const trackUrl = await buildTrackUrl(config.endpoint, config.apiKey, payload);
+    replacements.set(originalUrl, trackUrl);
+  }
+
+  // Replace URLs in text (longest-first to avoid partial matches)
+  let result = text;
+  const sorted = [...replacements.entries()].sort((a, b) => b[0].length - a[0].length);
+  for (const [original, tracked] of sorted) {
+    result = result.split(original).join(tracked);
+  }
+
+  return result;
+}

package/src/transport.js

@@ -0,0 +1,48 @@
+const EMIT_EVENT_MUTATION = `
+  mutation EmitEvent($input: EventInput!) {
+    emitEvent(input: $input) {
+      success
+      eventId
+      message
+    }
+  }
+`;
+
+export async function sendEvent({ endpoint, apiKey, clientId, userId, headers }, input, fetchFn) {
+  const f = fetchFn || globalThis.fetch;
+
+  // tes_ prefixed tokens are API tokens — send as Authorization: Bearer
+  // Other tokens (internal service keys) go as x-service-key
+  const authHeaders = apiKey.startsWith("tes_")
+    ? { Authorization: `Bearer ${apiKey}` }
+    : { "x-service-key": apiKey };
+
+  const response = await f(`${endpoint}/api/graphql`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-client-id": clientId,
+      ...headers,
+      ...authHeaders,
+    },
+    body: JSON.stringify({
+      query: EMIT_EVENT_MUTATION,
+      variables: {
+        input: userId
+          ? { ...input, data: { ...input.data, attributes: { ...input.data?.attributes, userId } } }
+          : input,
+      },
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`TES API error: ${response.status}`);
+  }
+
+  const json = await response.json();
+  if (json.errors?.length) {
+    throw new Error(`TES GraphQL error: ${json.errors[0].message}`);
+  }
+
+  return json.data.emitEvent;
+}