@telemai/sdk 0.1.1 → 0.2.1

package/README.md

@@ -42,7 +42,7 @@ See [Authentication](https://docs.telem.ai/authentication/) for the full rules.
 
 ```ts
 
-const telem = new Telem()          // environment, then ~/.telem/credentials.json
+const telem = new Telem          // environment, then ~/.telem/credentials.json
 const telem = new Telem("tlm_...") // just a key
 const telem = new Telem({
   apiKey: "tlm_...",
@@ -176,7 +176,7 @@ Do not expect a shorter list. The options are on the
 List the providers the deployment can run:
 
 ```ts
-for (const provider of await telem.providers()) {
+for (const provider of await telem.providers) {
   console.log(provider.name, provider.activeByDefault, provider.tiers)
 }
 ```
@@ -187,7 +187,7 @@ Every search belongs to a session. The response carries its id as `sessionId`. R
 your sessions back to see what an agent searched for. Both methods require an API key:
 
 ```ts
-for (const session of await telem.sessions.list()) {
+for (const session of await telem.sessions.list) {
   console.log(session.id, session.interactionCount, session.latestInteractionAt)
 }
 
@@ -198,8 +198,38 @@ console.log(summary.query, summary.goal, summary.context)
 `results` returns the query, the goal and the context of the session, plus the
 results of each search step.
 
+## Vercel AI SDK
+
+If your agent runs on the Vercel AI SDK, `@telemai/sdk/vercel` gives it
+`telem_search` and `telem_fetch` tools with query lineage attached to every call,
+subagents included. Build the tool set once per conversation and pass it to
+`generateText`:
+
+```ts
+import { generateText } from "ai"
+import Telem from "@telemai/sdk"
+import { createTelemVercelTools } from "@telemai/sdk/vercel"
+
+const telem = new Telem
+const tools = createTelemVercelTools({ telem, harness: "my-app" })
+
+const result = await generateText({ model, tools, prompt: "Is the Nintendo Museum open over New Year?" })
+```
+
+A subagent is a `generateText` started inside one of your tools. Pass that tool to
+`createTelemVercelTools` and use the same tool set inside the subagent; its calls
+then appear in the console under the tool call that started it. `ai` version 5
+or later is an optional peer dependency, used by this subpath only. The full
+guide, subagents, your own tools, and the options, is on the
+[Vercel AI SDK page](https://docs.telem.ai/integrations/vercel-ai/). The runnable example is `examples/vercel-ai-agents.mjs`
+in the SDK source, first in the [examples list](https://github.com/TelemAI/telem-js-sdk/tree/main/examples).
+
 ## Query lineage
 
+If your agent uses the Vercel AI SDK, use
+[`@telemai/sdk/vercel`](https://docs.telem.ai/integrations/vercel-ai/). It attaches lineage data to
+every call by itself, subagents included, and you build nothing below by hand.
+
 Every search and fetch from an agent can carry **lineage data**. Lineage data tells
 Telem which conversation made the call, and where in the conversation it happened.
 The console then shows all the calls of one conversation together, in order, and
@@ -221,8 +251,8 @@ Node SDK, where the completion id is the turn and each tool call has its own id:
 
 ```ts
 
-const telem = new Telem()
-const openai = new OpenAI()
+const telem = new Telem
+const openai = new OpenAI
 const messages = [{ role: "user" as const, content: "Is the Nintendo Museum open over New Year?" }]
 const tools = [
   {
@@ -239,26 +269,36 @@ const tools = [
   },
 ]
 
-const conversationId = crypto.randomUUID()     // once, when the conversation starts
+const conversationId = crypto.randomUUID     // once, when the conversation starts
 const windowId = await windowAnchor(messages)  // once, from the first message
 
 const completion = await openai.chat.completions.create({ model: "gpt-4o", messages, tools })
 for (const call of completion.choices[0].message.tool_calls ?? []) {
   if (call.type !== "function") continue
+  const { query, goal, context } = JSON.parse(call.function.arguments)
   const lineage = await buildMetadata({
     harness: "my-app",         // a stable name for your integration
     conversationId,
     windowId,
     messageId: completion.id,  // this model turn
     toolCallId: call.id,       // this tool call
-    history: messages,         // [{ role, content }]: the conversation so far
+    history: [                 // [{ role, content }]: the conversation so far, ending with this call
+      ...messages,
+      { role: "assistant", content: toolMarker("telem_search", "running", { query, goal, context }) },
+    ],
     ancestors: [],             // the parent snapshot; [] for the first agent
   })
-  const { query, goal, context } = JSON.parse(call.function.arguments)
   const response = await telem.search(query, withTrajectory({ goal, context }, lineage))
 }
 ```
 
+`history` has a rule the console depends on, and the example follows it on its
+`history` line: write each tool call into the history as a marker with
+`toolMarker(name, status, input)`, and end the history of every call with the
+call being made, marked `running`. When a call completes, keep its marker in the
+history as `completed`. The console reads the conversation's goals from those
+markers, so build them with the helper rather than by hand.
+
 `withTrajectory` attaches the lineage data to one call. Use it the same way with
 `telem.fetch`. When lineage data is present, the client ignores a `session` id.
 

package/dist/chunk-RYY4S5LP.js

@@ -0,0 +1,373 @@
+// src/errors.ts
+var TelemError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "TelemError";
+    this.status = options.status;
+    this.code = options.code;
+    this.details = options.details;
+  }
+};
+var TimeoutError = class extends TelemError {
+  constructor(message, cause) {
+    super(message, { code: "timeout", cause });
+    this.name = "TimeoutError";
+  }
+};
+
+// src/http.ts
+var MAX_DELAY_MS = 3e4;
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
+var BASE_DELAY_MS = 500;
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asObject(value) {
+  return isObject(value) ? value : {};
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function invalidRequest(message) {
+  return new TelemError(message, { code: "invalid_request" });
+}
+function stringList(items, empty, what) {
+  const list = asArray(items);
+  if (!list.length) throw invalidRequest(empty);
+  for (const item of list) {
+    if (typeof item !== "string") {
+      throw invalidRequest(`${what} must be strings, got ${item === null ? "null" : typeof item}`);
+    }
+    if (item === "") throw invalidRequest(`${what} must not be empty`);
+  }
+  return list;
+}
+function errorEnvelope(body) {
+  if (!isObject(body)) return void 0;
+  if (isObject(body.error)) return body.error;
+  if (isObject(body.detail)) return body.detail;
+  return void 0;
+}
+function detailFromBody(body) {
+  if (!isObject(body)) return void 0;
+  const envelope = errorEnvelope(body);
+  if (envelope && typeof envelope.message === "string" && envelope.message) {
+    return envelope.message;
+  }
+  const detail = body.detail;
+  if (typeof detail === "string" && detail) return detail;
+  if (Array.isArray(detail) && detail.length) {
+    const messages = detail.map((item) => isObject(item) && typeof item.msg === "string" ? item.msg : void 0).filter((message) => message !== void 0);
+    return messages.join(", ") || JSON.stringify(detail);
+  }
+  return void 0;
+}
+function codeFromBody(body) {
+  const envelope = errorEnvelope(body);
+  return envelope && typeof envelope.code === "string" ? envelope.code : void 0;
+}
+function isResponseLike(value) {
+  return isObject(value) && typeof value.text === "function" && typeof value.status === "number" && typeof value.headers?.get === "function";
+}
+var NotAResponse = class extends Error {
+};
+function defaultMessage(status) {
+  if (status === 400) return "Bad request";
+  if (status === 401 || status === 403) return "Authentication failed";
+  if (status === 404) return "Not found";
+  return `Unexpected status code ${status}`;
+}
+function statusError(status, body) {
+  return new TelemError(detailFromBody(body) ?? defaultMessage(status), {
+    status,
+    code: codeFromBody(body),
+    details: body
+  });
+}
+function connectionError(url, cause) {
+  const error = cause;
+  const detail = typeof error?.cause?.message === "string" && error.cause.message || typeof error?.message === "string" && error.message || String(cause);
+  return new TelemError(`could not reach ${url}: ${detail}`, {
+    code: "connection_error",
+    cause
+  });
+}
+function isRetryable(status) {
+  return status >= 500 || status === 429;
+}
+function backoff(attempt) {
+  return Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+}
+function retryDelay(retryAfter, attempt) {
+  if (retryAfter !== null && /^\s*\d+\s*$/.test(retryAfter)) {
+    return Math.min(Number(retryAfter) * 1e3, MAX_DELAY_MS);
+  }
+  return backoff(attempt);
+}
+async function request(config, method, path, body, abort) {
+  const url = `${config.baseUrl}/${path.replace(/^\/+/, "")}`;
+  const headers = { "User-Agent": config.userAgent };
+  if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+  const init = { method, headers };
+  if (body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    try {
+      init.body = JSON.stringify(body);
+    } catch (cause) {
+      throw invalidRequest(`request body is not JSON: ${cause?.message ?? String(cause)}`);
+    }
+  }
+  let onAbort = () => {
+  };
+  const abortion = abort && new Promise((_, reject) => {
+    onAbort = () => reject(abort.reason ?? new Error("aborted"));
+    abort.addEventListener("abort", onAbort, { once: true });
+  });
+  abortion?.catch(() => {
+  });
+  const pause = (ms) => abortion ? Promise.race([config.sleep(ms), abortion]) : config.sleep(ms);
+  try {
+    return await attempts();
+  } finally {
+    abort?.removeEventListener("abort", onAbort);
+  }
+  async function attempts() {
+    for (let attempt = 0; ; attempt++) {
+      if (abort?.aborted) throw abort.reason ?? new Error("aborted");
+      const timeout = Number.isFinite(config.timeoutMs) ? AbortSignal.timeout(Math.min(config.timeoutMs, MAX_TIMEOUT_MS)) : void 0;
+      const signal = timeout && abort ? typeof AbortSignal.any === "function" ? AbortSignal.any([timeout, abort]) : timeout : timeout ?? abort;
+      let onAbort2 = () => {
+      };
+      const deadline = signal && new Promise((_, reject) => {
+        onAbort2 = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort2, { once: true });
+      });
+      const race = (work) => deadline ? Promise.race([work, deadline]) : work;
+      let received;
+      try {
+        const response = await race(config.fetch(url, { ...init, signal }));
+        if (!isResponseLike(response)) throw new NotAResponse();
+        const text = await race(response.text());
+        let parsed;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+        received = {
+          status: response.status,
+          retryAfter: response.headers.get("retry-after"),
+          body: parsed
+        };
+      } catch (cause) {
+        if (cause instanceof NotAResponse) {
+          throw new TelemError("the injected fetch returned something that is not a Response", {
+            code: "connection_error"
+          });
+        }
+        if (abort?.aborted) throw abort.reason ?? cause;
+        if (signal?.aborted) {
+          throw new TimeoutError(`request to ${url} timed out after ${config.timeoutMs}ms`, cause);
+        }
+        if (attempt >= config.maxRetries) throw connectionError(url, cause);
+        await pause(backoff(attempt));
+        continue;
+      } finally {
+        signal?.removeEventListener("abort", onAbort2);
+      }
+      if (received.status >= 200 && received.status < 300) return received.body;
+      if (isRetryable(received.status) && attempt < config.maxRetries) {
+        await pause(retryDelay(received.retryAfter, attempt));
+        continue;
+      }
+      throw statusError(received.status, received.body);
+    }
+  }
+}
+
+// src/trajectory.ts
+var NS_TRAJECTORY = "443866ab-1b45-5ed8-979e-52fdad07b810";
+var NONE = "none";
+var RESERVED_METADATA = /* @__PURE__ */ new Set([
+  "message_history",
+  "session_key",
+  "fingerprint",
+  "node_key",
+  "kind",
+  "parent_node_key",
+  "ancestors"
+]);
+var ENCODER = new TextEncoder();
+var NAMESPACE_BYTES = Uint8Array.from(
+  NS_TRAJECTORY.replaceAll("-", "").match(/../g) ?? [],
+  (pair) => parseInt(pair, 16)
+);
+function hex(bytes) {
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
+async function digest(algorithm, bytes) {
+  return new Uint8Array(await crypto.subtle.digest(algorithm, bytes));
+}
+async function sha256(value) {
+  return hex(await digest("SHA-256", ENCODER.encode(value)));
+}
+function lp(value) {
+  return `${ENCODER.encode(value).length}:${value}`;
+}
+async function uuid5(name) {
+  const encoded = ENCODER.encode(name);
+  const input = new Uint8Array(NAMESPACE_BYTES.length + encoded.length);
+  input.set(NAMESPACE_BYTES);
+  input.set(encoded, NAMESPACE_BYTES.length);
+  const bytes = (await digest("SHA-1", input)).slice(0, 16);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const chars = hex(bytes);
+  return [
+    chars.slice(0, 8),
+    chars.slice(8, 12),
+    chars.slice(12, 16),
+    chars.slice(16, 20),
+    chars.slice(20)
+  ].join("-");
+}
+async function fingerprint(harness, conversationId) {
+  return await sha256(lp(harness) + lp(conversationId));
+}
+async function sessionKey(harness, conversationId, windowId) {
+  const name = lp(harness) + lp(await sha256(conversationId)) + lp(windowId) + lp(NONE);
+  return await uuid5(name);
+}
+async function eventNodeKey(harness, session, messageId, toolCallId) {
+  const name = lp(harness) + lp(session) + lp(messageId) + lp(toolCallId) + lp("event");
+  return await uuid5(name);
+}
+async function snapshotNodeKey(harness, conversationId, messageId) {
+  const name = lp(harness) + lp(await sha256(conversationId)) + lp(messageId) + lp("snap");
+  return await uuid5(name);
+}
+async function contentAnchor(...parts) {
+  return await sha256(parts.map(lp).join(""));
+}
+var HISTORY_TEXT_CAP = 128e3;
+var TOOL_INPUT_CAP = 128e3;
+function cap(value) {
+  if (value.length <= HISTORY_TEXT_CAP) return value;
+  return Array.from(value).slice(0, HISTORY_TEXT_CAP).join("");
+}
+function toolMarker(name, status, args) {
+  let serialized = "";
+  try {
+    const text = JSON.stringify(args);
+    if (typeof text === "string") serialized = text;
+  } catch {
+    serialized = "";
+  }
+  if (serialized.length > TOOL_INPUT_CAP) serialized = Array.from(serialized).slice(0, TOOL_INPUT_CAP).join("");
+  const suffix = serialized ? ` ${serialized}` : "";
+  return `[tool ${name || "?"}: ${status}${suffix}]`;
+}
+function pyStr(value) {
+  if (typeof value === "string") return value;
+  if (value === null) return "None";
+  if (value === true) return "True";
+  if (value === false) return "False";
+  return String(value);
+}
+function messageText(content) {
+  if (typeof content === "string") return cap(content);
+  if (Array.isArray(content)) {
+    const pieces = [];
+    for (const block of content) {
+      if (typeof block === "string") pieces.push(block);
+      else if (isObject(block) && typeof block.text === "string") pieces.push(block.text);
+    }
+    return cap(pieces.join("\n"));
+  }
+  return content === null || content === void 0 ? "" : cap(pyStr(content));
+}
+async function windowAnchor(messages) {
+  const first = messages[0];
+  if (first === void 0) return NONE;
+  return await contentAnchor(
+    first.role === void 0 ? "" : pyStr(first.role),
+    messageText(first.content)
+  );
+}
+async function buildMetadata(args) {
+  const [session, fp] = await Promise.all([
+    sessionKey(args.harness, args.conversationId, args.windowId),
+    fingerprint(args.harness, args.conversationId)
+  ]);
+  return {
+    message_history: args.history,
+    session_key: session,
+    fingerprint: fp,
+    node_key: await eventNodeKey(args.harness, session, args.messageId, args.toolCallId),
+    parent_node_key: parentNodeKey(args.ancestors),
+    ancestors: args.ancestors
+  };
+}
+async function buildSnapshot(args) {
+  const [session, fp, node] = await Promise.all([
+    sessionKey(args.harness, args.conversationId, args.windowId),
+    fingerprint(args.harness, args.conversationId),
+    snapshotNodeKey(args.harness, args.conversationId, args.messageId)
+  ]);
+  return {
+    session_key: session,
+    fingerprint: fp,
+    node_key: node,
+    parent_node_key: parentNodeKey(args.ancestors),
+    context: args.context,
+    spawned_at: args.spawnedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function parentNodeKey(ancestors) {
+  return ancestors.at(-1)?.node_key ?? null;
+}
+var TRAJECTORY = /* @__PURE__ */ Symbol.for("telem.trajectory");
+function withTrajectory(options, envelope) {
+  return { ...options, [TRAJECTORY]: envelope };
+}
+function wireMetadata(options, kind) {
+  const metadata = {};
+  for (const [key, value] of Object.entries(options.metadata ?? {})) {
+    if (!RESERVED_METADATA.has(key)) metadata[key] = value;
+  }
+  const envelope = options[TRAJECTORY];
+  if (envelope !== void 0) Object.assign(metadata, envelope, { kind });
+  const sessionId = metadata.session_key === void 0 ? options.session : void 0;
+  return { metadata, sessionId };
+}
+
+export {
+  TelemError,
+  TimeoutError,
+  isObject,
+  asObject,
+  asArray,
+  invalidRequest,
+  stringList,
+  request,
+  RESERVED_METADATA,
+  sha256,
+  fingerprint,
+  sessionKey,
+  eventNodeKey,
+  snapshotNodeKey,
+  contentAnchor,
+  cap,
+  toolMarker,
+  messageText,
+  windowAnchor,
+  buildMetadata,
+  buildSnapshot,
+  withTrajectory,
+  wireMetadata
+};