@telemai/sdk 0.1.1 → 0.2.0

package/dist/vercel/index.js

@@ -0,0 +1,583 @@
+import {
+  buildMetadata,
+  buildSnapshot,
+  cap,
+  contentAnchor,
+  isObject,
+  messageText,
+  sha256,
+  toolMarker,
+  windowAnchor,
+  withTrajectory
+} from "../chunk-RYY4S5LP.js";
+
+// src/vercel/index.ts
+import { jsonSchema } from "ai";
+
+// src/incremental.ts
+function incrementalMode(raw) {
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  return value === "off" || value === "history" ? value : "ancestors";
+}
+function env(name) {
+  const value = globalThis.process?.env?.[name];
+  return typeof value === "string" ? value : void 0;
+}
+var DELIVERED_CAP = 4096;
+var CAPABILITY_CAP = 64;
+var HISTORY_WATERMARK_CAP = 256;
+var MISSING_SNAPSHOTS = "missing_snapshots";
+var SEARCH_MARKER = "[tool telem_search:";
+function createLruSet(cap2) {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    has: (key) => entries.has(key),
+    add(key) {
+      entries.delete(key);
+      entries.set(key, true);
+      while (entries.size > cap2) {
+        const oldest = entries.keys().next().value;
+        if (oldest === void 0) break;
+        entries.delete(oldest);
+      }
+    },
+    remove(key) {
+      entries.delete(key);
+    }
+  };
+}
+function createLruMap(cap2) {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => entries.get(key),
+    set(key, value) {
+      entries.delete(key);
+      entries.set(key, value);
+      while (entries.size > cap2) {
+        const oldest = entries.keys().next().value;
+        if (oldest === void 0) break;
+        entries.delete(oldest);
+      }
+    }
+  };
+}
+async function cacheScope(baseUrl, apiKey) {
+  return baseUrl + " " + await sha256(apiKey ?? "");
+}
+function deliveredKey(scope, snapshotKey) {
+  return scope + "\0" + snapshotKey;
+}
+function newDeliveryPlan(scope) {
+  return { scope, sentWithContext: [], omitted: [], epochDegraded: false };
+}
+function isMissingSnapshotsRefusal(error, plan) {
+  if (error.status !== 409 || !plan.omitted.length) return false;
+  return error.code === void 0 || error.code === MISSING_SNAPSHOTS;
+}
+async function historyHash(entry) {
+  return await sha256(entry.content + "\0" + (entry.reasoning ?? ""));
+}
+async function fullHistorySend(flat) {
+  const hashes = await Promise.all(flat.map((message) => historyHash(message.entry)));
+  return {
+    entries: flat.map((message) => message.entry),
+    sent: flat.map((message, index) => ({ id: message.id, hash: hashes[index] }))
+  };
+}
+async function historyDelta(flat, hashes) {
+  const include = /* @__PURE__ */ new Set();
+  const boosters = /* @__PURE__ */ new Set();
+  const hashOf = await Promise.all(flat.map((message) => historyHash(message.entry)));
+  for (let i = 0; i < flat.length; i++) {
+    const { id, entry } = flat[i];
+    if (hashes.get(id) !== hashOf[i]) {
+      include.add(i);
+      if (entry.reasoning) boosters.add(entry.reasoning);
+    } else if (entry.role === "user") {
+      include.add(i);
+    } else if (entry.role === "assistant" && entry.content.includes(SEARCH_MARKER)) {
+      include.add(i);
+    }
+  }
+  if (flat.length) include.add(flat.length - 1);
+  for (let i = 0; i < flat.length; i++) {
+    if (include.has(i)) continue;
+    const reasoning = flat[i].entry.reasoning;
+    if (reasoning && boosters.has(reasoning)) include.add(i);
+  }
+  const chosen = [...include].sort((a, b) => a - b);
+  return {
+    entries: chosen.map((i) => flat[i].entry),
+    sent: chosen.map((i) => ({ id: flat[i].id, hash: hashOf[i] }))
+  };
+}
+function continuesEpoch(previous, flat) {
+  const at = flat.findIndex((message) => message.id === previous.lastMsgId);
+  return at >= 0 && at <= previous.msgCount - 1;
+}
+function historyKey(scope, conversationId) {
+  return scope + "\0" + conversationId;
+}
+function createIncrementalState(options = {}) {
+  const mode = options.mode ?? (() => incrementalMode(env("TELEM_INCREMENTAL")));
+  const forced = options.forced ?? (() => env("TELEM_INCREMENTAL_FORCE") === "1");
+  const delivered = createLruSet(DELIVERED_CAP);
+  const capability = createLruSet(CAPABILITY_CAP);
+  const historyWatermarks = createLruMap(HISTORY_WATERMARK_CAP);
+  function omitsDeliveredContext(scope) {
+    if (mode() === "off") return false;
+    if (forced()) return true;
+    return capability.has(scope);
+  }
+  function planAncestors(plan, chain) {
+    const omit = omitsDeliveredContext(plan.scope);
+    const entries = [];
+    const sentWithContext = [];
+    const omitted = [];
+    for (const snapshot of chain) {
+      const entry = { ...snapshot };
+      const key = typeof snapshot.node_key === "string" ? snapshot.node_key : void 0;
+      if (key !== void 0 && omit && delivered.has(deliveredKey(plan.scope, key))) {
+        const context = entry.context;
+        delete entry.context;
+        entry.context_omitted = true;
+        omitted.push({ key, entry, context });
+      } else if (key !== void 0) {
+        sentWithContext.push(key);
+      }
+      entries.push(entry);
+    }
+    plan.sentWithContext = sentWithContext;
+    plan.omitted = omitted;
+    return entries;
+  }
+  async function planHistory(plan, conversationId, sessionKey, flat) {
+    if (mode() !== "history") return flat.map((message) => message.entry);
+    const epoch = {
+      sessionKey,
+      lastMsgId: flat.length ? flat[flat.length - 1].id : "none",
+      msgCount: flat.length
+    };
+    const previous = historyWatermarks.get(historyKey(plan.scope, conversationId));
+    const continuous = previous !== void 0 && !plan.epochDegraded && previous.epoch.sessionKey === epoch.sessionKey && continuesEpoch(previous.epoch, flat);
+    const chosen = continuous ? await historyDelta(flat, previous.hashes) : await fullHistorySend(flat);
+    plan.history = { conversationKey: conversationId, epoch, sent: chosen.sent };
+    return chosen.entries;
+  }
+  function advanceHistory(plan) {
+    const send = plan.history;
+    if (!send) return;
+    const key = historyKey(plan.scope, send.conversationKey);
+    const current = historyWatermarks.get(key);
+    if (!current || current.epoch.sessionKey !== send.epoch.sessionKey) {
+      const hashes = /* @__PURE__ */ new Map();
+      for (const { id, hash } of send.sent) hashes.set(id, hash);
+      historyWatermarks.set(key, { epoch: send.epoch, hashes });
+      return;
+    }
+    for (const { id, hash } of send.sent) current.hashes.set(id, hash);
+    current.epoch = send.epoch;
+    historyWatermarks.set(key, current);
+  }
+  function recordDelivery(plan, body) {
+    for (const key of plan.sentWithContext) delivered.add(deliveredKey(plan.scope, key));
+    advanceHistory(plan);
+    if (!body || typeof body !== "object") return;
+    if (!(MISSING_SNAPSHOTS in body)) return;
+    capability.add(plan.scope);
+    const missing = body[MISSING_SNAPSHOTS];
+    if (Array.isArray(missing)) {
+      for (const key of missing) delivered.remove(deliveredKey(plan.scope, String(key)));
+    }
+  }
+  function restoreOmittedContexts(plan) {
+    for (const { key, entry, context } of plan.omitted) {
+      delivered.remove(deliveredKey(plan.scope, key));
+      delete entry.context_omitted;
+      entry.context = context;
+      plan.sentWithContext.push(key);
+    }
+    plan.omitted = [];
+  }
+  async function sendWithOmissionRetry(plan, send) {
+    try {
+      return await send();
+    } catch (error) {
+      const shape = error;
+      if (!isMissingSnapshotsRefusal(shape, plan)) throw error;
+      restoreOmittedContexts(plan);
+      return await send();
+    }
+  }
+  return { planAncestors, planHistory, recordDelivery, sendWithOmissionRetry };
+}
+
+// src/vercel/index.ts
+var SEARCH_TOOL = "telem_search";
+var FETCH_TOOL = "telem_fetch";
+var RESULT_CAP = 12;
+var PAGE_CAP = 4e3;
+var RUNNING = "running";
+function answeredCalls(messages) {
+  const answered = /* @__PURE__ */ new Set();
+  for (const message of messages) {
+    if (!isObject(message) || !Array.isArray(message.content)) continue;
+    if (message.role !== "tool" && message.role !== "assistant") continue;
+    for (const part of message.content) {
+      if (isObject(part) && part.type === "tool-result" && typeof part.toolCallId === "string") {
+        answered.add(part.toolCallId);
+      }
+    }
+  }
+  return answered;
+}
+function telemVercelMessageHistory(messages, current) {
+  const answered = answeredCalls(messages);
+  const flat = [];
+  for (let index = 0; index < messages.length; index++) {
+    const message = messages[index];
+    if (!isObject(message)) continue;
+    const role = message.role;
+    if (role !== "user" && role !== "assistant" && role !== "system") continue;
+    const pieces = [];
+    const thoughts = [];
+    const content = message.content;
+    if (typeof content === "string") {
+      pieces.push(content);
+    } else if (Array.isArray(content)) {
+      for (const raw of content) {
+        if (typeof raw === "string") {
+          pieces.push(raw);
+          continue;
+        }
+        if (!isObject(raw)) continue;
+        const part = raw;
+        if (part.type === "text" && typeof part.text === "string") pieces.push(part.text);
+        else if (part.type === "reasoning" && typeof part.text === "string") thoughts.push(part.text);
+        else if (part.type === "tool-call") {
+          const id = typeof part.toolCallId === "string" ? part.toolCallId : "";
+          const name = typeof part.toolName === "string" ? part.toolName : "";
+          const status = answered.has(id) ? "completed" : "pending";
+          pieces.push(toolMarker(name, status, part.input !== void 0 ? part.input : part.args));
+        }
+      }
+    } else if (content !== null && content !== void 0) {
+      pieces.push(messageText(content));
+    }
+    const text = cap(pieces.join("\n"));
+    const reasoning = cap(thoughts.join("\n"));
+    if (!text && !reasoning) continue;
+    const entry = { role, content: text };
+    if (reasoning) entry.reasoning = reasoning;
+    flat.push({ id: "\0pos:" + index, entry });
+  }
+  if (current) {
+    flat.push({
+      id: "\0pos:" + messages.length,
+      entry: { role: "assistant", content: toolMarker(current.name, RUNNING, current.input) }
+    });
+  }
+  return flat;
+}
+async function turnAnchor(messages, windowId) {
+  const last = messages[messages.length - 1];
+  let text = "";
+  try {
+    text = last === void 0 ? "" : cap(JSON.stringify(last) ?? "");
+  } catch {
+    text = isObject(last) ? messageText(last.content) : "";
+  }
+  return await contentAnchor(String(messages.length), windowId, text);
+}
+function compact(response) {
+  return response.results.slice(0, RESULT_CAP).map(({ provider, title, url, summary }) => ({ provider, title, url, summary }));
+}
+function page(response) {
+  const first = response.results[0];
+  return {
+    status: first?.status,
+    error: first?.error ?? null,
+    content: (first?.content ?? "").slice(0, PAGE_CAP)
+  };
+}
+function isInteraction(raw) {
+  return isObject(raw) && "session_id" in raw;
+}
+var SEARCH_SCHEMA = jsonSchema({
+  type: "object",
+  properties: {
+    query: { type: "string", description: "One search query." },
+    goal: { type: "string", description: "What this search is for, in a few words." },
+    context: {
+      type: "string",
+      description: "Two or three sentences of your reasoning: what you want to find out and why, given what you already know. Not a restatement of the query."
+    }
+  },
+  required: ["query"],
+  additionalProperties: false
+});
+var FETCH_SCHEMA = jsonSchema({
+  type: "object",
+  properties: {
+    url: { type: "string", description: "The http(s) URL to read." },
+    goal: { type: "string", description: "What you want from this page, in a few words." }
+  },
+  required: ["url"],
+  additionalProperties: false
+});
+function loadFrames() {
+  try {
+    const proc = globalThis.process;
+    if (typeof proc?.getBuiltinModule !== "function") return void 0;
+    const hooks = proc.getBuiltinModule("node:async_hooks");
+    return hooks?.AsyncLocalStorage ? new hooks.AsyncLocalStorage() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var REGISTRY = /* @__PURE__ */ Symbol.for("telem.vercel.registry");
+var registry = globalThis[REGISTRY] ??= {
+  frames: loadFrames(),
+  sets: /* @__PURE__ */ new WeakMap(),
+  owners: /* @__PURE__ */ new WeakMap(),
+  turnStarts: /* @__PURE__ */ new WeakMap()
+};
+registry.turnStarts ??= /* @__PURE__ */ new WeakMap();
+var { frames, sets, owners, turnStarts } = registry;
+function turnStart(execution) {
+  const key = execution.messages;
+  if (typeof key !== "object" || key === null) return (/* @__PURE__ */ new Date()).toISOString();
+  const cached = turnStarts.get(key);
+  if (cached && cached.length === key.length) return cached.startedAt;
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  turnStarts.set(key, { startedAt, length: key.length });
+  return startedAt;
+}
+var telemVercelAutoNesting = frames !== void 0;
+function createTelemVercelAgent(options) {
+  const { telem, harness } = options;
+  if (typeof harness !== "string" || !harness) throw new TypeError("createTelemVercelAgent requires `harness`");
+  const conversationId = options.conversationId ?? crypto.randomUUID();
+  const ancestors = [...options.ancestors ?? []];
+  const mode = options.incremental;
+  const state = options.incrementalState ?? createIncrementalState(mode === void 0 ? {} : { mode: () => mode });
+  const renderSearch = options.render?.search ?? compact;
+  const renderFetch = options.render?.fetch ?? page;
+  const callsPerToolCall = createLruMap(1024);
+  function callIdFor(execution) {
+    const n = (callsPerToolCall.get(execution.toolCallId) ?? 0) + 1;
+    callsPerToolCall.set(execution.toolCallId, n);
+    return n === 1 ? execution.toolCallId : `${execution.toolCallId}#${n}`;
+  }
+  function signalFor(execution, own) {
+    const sdk = execution?.abortSignal;
+    if (!sdk || !own) return sdk ?? own;
+    return typeof AbortSignal.any === "function" ? AbortSignal.any([sdk, own]) : own;
+  }
+  async function turn(messages) {
+    const windowId = await windowAnchor(messages);
+    return { windowId, messageId: await turnAnchor(messages, windowId) };
+  }
+  async function lineage(execution, current) {
+    const messages = execution?.messages ?? [];
+    const plan = newDeliveryPlan(await cacheScope(telem.baseUrl, telem.apiKey));
+    plan.epochDegraded = execution?.messages === void 0;
+    const flat = telemVercelMessageHistory(messages, current);
+    const { windowId, messageId } = await turn(messages);
+    const planned = state.planAncestors(plan, ancestors);
+    const envelope = await buildMetadata({
+      harness,
+      conversationId,
+      windowId,
+      messageId,
+      toolCallId: execution ? callIdFor(execution) : crypto.randomUUID(),
+      history: flat.map((message) => message.entry),
+      ancestors: planned
+    });
+    envelope.message_history = await state.planHistory(plan, conversationId, envelope.session_key, flat);
+    return { envelope, plan };
+  }
+  async function search(query, searchOptions, execution) {
+    const opts = { ...searchOptions ?? {}, signal: signalFor(execution, searchOptions?.signal) };
+    const { envelope, plan } = await lineage(execution, {
+      name: SEARCH_TOOL,
+      input: { query, goal: opts.goal, context: opts.context }
+    });
+    const response = await state.sendWithOmissionRetry(
+      plan,
+      () => telem.search(query, withTrajectory(opts, envelope))
+    );
+    if (isInteraction(response.raw)) state.recordDelivery(plan, response.raw);
+    await notify({ kind: "search", agent, query, response });
+    return response;
+  }
+  async function fetch(url, fetchOptions, execution) {
+    const opts = { ...fetchOptions ?? {}, signal: signalFor(execution, fetchOptions?.signal) };
+    const { envelope, plan } = await lineage(execution, {
+      name: FETCH_TOOL,
+      input: { url, goal: opts.metadata?.goal }
+    });
+    const response = await state.sendWithOmissionRetry(
+      plan,
+      () => telem.fetch(url, withTrajectory(opts, envelope))
+    );
+    if (isInteraction(response.raw)) state.recordDelivery(plan, response.raw);
+    await notify({ kind: "fetch", agent, url, response });
+    return response;
+  }
+  async function notify(event) {
+    try {
+      await options.onResponse?.(event);
+    } catch {
+    }
+  }
+  async function snapshot(execution, spawnedAt) {
+    const messages = execution?.messages ?? [];
+    const { windowId, messageId } = await turn(messages);
+    return await buildSnapshot({
+      harness,
+      conversationId,
+      windowId,
+      messageId,
+      context: telemVercelMessageHistory(messages).map((message) => message.entry),
+      ancestors,
+      spawnedAt
+    });
+  }
+  async function child(execution, childOptions) {
+    return createTelemVercelAgent({
+      telem,
+      harness,
+      conversationId: childOptions?.conversationId,
+      ancestors: [...ancestors, await snapshot(execution, childOptions?.spawnedAt)],
+      incremental: mode,
+      render: options.render,
+      onResponse: options.onResponse,
+      incrementalState: state
+    });
+  }
+  const tools = {
+    telem_search: {
+      description: "Search the public web. One query per call; returns the top results with provider, title, url and summary. Use telem_fetch to read a page in full.",
+      inputSchema: SEARCH_SCHEMA,
+      execute: async (input, execution) => renderSearch(await search(input.query, { goal: input.goal, context: input.context }, execution))
+    },
+    telem_fetch: {
+      description: "Read the text of one web page by URL. telem_search returns snippets; this returns the page.",
+      inputSchema: FETCH_SCHEMA,
+      execute: async (input, execution) => renderFetch(
+        await fetch(
+          input.url,
+          { inlineContent: true, inlineMaxChars: PAGE_CAP, metadata: input.goal ? { goal: input.goal } : void 0 },
+          execution
+        )
+      )
+    }
+  };
+  const agent = { conversationId, ancestors, telem, tools, search, fetch, snapshot, child };
+  return agent;
+}
+async function agentFor(entry, execution) {
+  const frame = frames?.getStore();
+  if (!frame || frame.owner !== entry) return entry.root;
+  if (execution === frame.options || execution?.messages === frame.options.messages) return await frame.agent;
+  const parent = await frame.agent;
+  const key = await contentAnchor(parent.conversationId, frame.options.toolCallId);
+  let child = frame.children.get(key);
+  if (!child) {
+    child = parent.child(frame.options, { conversationId: key, spawnedAt: frame.startedAt });
+    child.catch(() => frame.children.delete(key));
+    frame.children.set(key, child);
+  }
+  return await child;
+}
+function isAsyncIterable(value) {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+function within(store, frame, source) {
+  return {
+    [Symbol.asyncIterator]() {
+      const iterator = store.run(frame, () => source[Symbol.asyncIterator]());
+      return {
+        next: (value) => store.run(frame, () => iterator.next(value)),
+        return: (value) => store.run(frame, () => iterator.return?.(value) ?? Promise.resolve({ done: true, value })),
+        throw: (error) => store.run(frame, () => iterator.throw?.(error) ?? Promise.reject(error))
+      };
+    }
+  };
+}
+function wrapTool(tool, entry) {
+  const execute = tool.execute;
+  if (typeof execute !== "function") return tool;
+  return {
+    ...tool,
+    execute(input, execution) {
+      if (!isObject(execution)) return execute.call(tool, input, execution);
+      owners.set(execution, entry);
+      if (entry.explicit || !frames) return execute.call(tool, input, execution);
+      const frame = {
+        owner: entry,
+        // Never rejects: a frame whose run makes no Telem call never awaits it.
+        agent: agentFor(entry, execution).catch(() => entry.root),
+        options: execution,
+        startedAt: turnStart(execution),
+        children: /* @__PURE__ */ new Map()
+      };
+      const result = frames.run(frame, () => execute.call(tool, input, execution));
+      return isAsyncIterable(result) ? within(frames, frame, result) : result;
+    }
+  };
+}
+function createTelemVercelTools(options) {
+  const { tools: own, ...agentOptions } = options;
+  return buildSet(createTelemVercelAgent(agentOptions), own, false);
+}
+function entryFor(tools, execution, who) {
+  const entry = (isObject(execution) ? owners.get(execution) : void 0) ?? sets.get(tools);
+  if (!entry) {
+    throw new TypeError(`${who}: pass the set that createTelemVercelTools returned, not a copy of it`);
+  }
+  return entry;
+}
+async function childTelemVercelTools(tools, execution, options) {
+  const entry = entryFor(tools, execution, "childTelemVercelTools");
+  const parent = entry.explicit ? entry.root : await agentFor(entry, execution);
+  const child = await parent.child(execution, { ...options, spawnedAt: turnStart(execution) });
+  return buildSet(child, entry.own, true);
+}
+function buildSet(root, own, explicit) {
+  const entry = { root, own, explicit };
+  const resolve = explicit ? async () => root : (execution) => agentFor(entry, execution);
+  const set = {
+    telem_search: {
+      ...root.tools.telem_search,
+      execute: async (input, execution) => (await resolve(execution)).tools.telem_search.execute(input, execution)
+    },
+    telem_fetch: {
+      ...root.tools.telem_fetch,
+      execute: async (input, execution) => (await resolve(execution)).tools.telem_fetch.execute(input, execution)
+    }
+  };
+  for (const [name, tool] of Object.entries(own ?? {})) {
+    if (name === SEARCH_TOOL || name === FETCH_TOOL) {
+      throw new TypeError(`createTelemVercelTools: \`${name}\` is the Telem tool's own name; use \`render\` to change what it returns`);
+    }
+    set[name] = wrapTool(tool, entry);
+  }
+  sets.set(set, entry);
+  return set;
+}
+async function telemVercelAgentFor(tools, execution) {
+  const entry = entryFor(tools, execution, "telemVercelAgentFor");
+  return entry.explicit ? entry.root : await agentFor(entry, execution);
+}
+var vercel_default = createTelemVercelAgent;
+export {
+  childTelemVercelTools,
+  createTelemVercelAgent,
+  createTelemVercelTools,
+  vercel_default as default,
+  telemVercelAgentFor,
+  telemVercelAutoNesting,
+  telemVercelMessageHistory
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemai/sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",
@@ -21,6 +21,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./vercel": {
+      "import": {
+        "types": "./dist/vercel/index.d.ts",
+        "default": "./dist/vercel/index.js"
+      },
+      "require": {
+        "types": "./dist/vercel/index.d.cts",
+        "default": "./dist/vercel/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -38,11 +48,28 @@
     "gen-version": "node scripts/gen-version.mjs",
     "prebuild": "node scripts/gen-version.mjs",
     "build": "tsup",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "smoke:vercel": "node scripts/vercel-live.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
+    "ai": "^6.0.277",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "ai": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "vercel": [
+        "./dist/vercel/index.d.ts"
+      ]
+    }
   }
 }