@telemai/sdk 0.1.1 → 0.2.0

package/README.md

@@ -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/TelemSDK/tree/main/js-sdk/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
@@ -245,20 +275,30 @@ 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
+};

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   fingerprint: () => fingerprint,
   sessionKey: () => sessionKey,
   snapshotNodeKey: () => snapshotNodeKey,
+  toolMarker: () => toolMarker,
   windowAnchor: () => windowAnchor,
   withTrajectory: () => withTrajectory
 });
@@ -58,7 +59,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.2.0";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -243,7 +244,7 @@ function retryDelay(retryAfter, attempt) {
   }
   return backoff(attempt);
 }
-async function request(config, method, path, body) {
+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}`;
@@ -256,52 +257,71 @@ async function request(config, method, path, body) {
       throw invalidRequest(`request body is not JSON: ${cause?.message ?? String(cause)}`);
     }
   }
-  for (let attempt = 0; ; attempt++) {
-    const signal = Number.isFinite(config.timeoutMs) ? AbortSignal.timeout(Math.min(config.timeoutMs, MAX_TIMEOUT_MS)) : void 0;
-    let onAbort = () => {
-    };
-    const deadline = signal && new Promise((_, reject) => {
-      onAbort = () => reject(signal.reason);
-      signal.addEventListener("abort", onAbort, { 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
+  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 = () => {
       };
-    } catch (cause) {
-      if (cause instanceof NotAResponse) {
-        throw new TelemError("the injected fetch returned something that is not a Response", {
-          code: "connection_error"
-        });
+      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 (signal?.aborted) {
-        throw new TimeoutError(`request to ${url} timed out after ${config.timeoutMs}ms`, cause);
+      if (received.status >= 200 && received.status < 300) return received.body;
+      if (isRetryable(received.status) && attempt < config.maxRetries) {
+        await pause(retryDelay(received.retryAfter, attempt));
+        continue;
       }
-      if (attempt >= config.maxRetries) throw connectionError(url, cause);
-      await config.sleep(backoff(attempt));
-      continue;
-    } finally {
-      signal?.removeEventListener("abort", onAbort);
+      throw statusError(received.status, received.body);
     }
-    if (received.status >= 200 && received.status < 300) return received.body;
-    if (isRetryable(received.status) && attempt < config.maxRetries) {
-      await config.sleep(retryDelay(received.retryAfter, attempt));
-      continue;
-    }
-    throw statusError(received.status, received.body);
   }
 }
 
@@ -372,10 +392,23 @@ 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";
@@ -505,7 +538,7 @@ function buildFetchResponse(interaction) {
 }
 async function fetchUrls(config, url, options) {
   const body = fetchBody(url, options);
-  return buildFetchResponse(await request(config, "POST", "/v1/fetch", body));
+  return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
 // src/methods/providers.ts
@@ -654,7 +687,7 @@ function buildSearchResponse(interaction) {
 }
 async function search(config, query, options) {
   const body = searchBody(config, query, options);
-  const data = await request(config, "POST", "/v1/interactions", body);
+  const data = await request(config, "POST", "/v1/interactions", body, options.signal);
   assertV2(data);
   return buildSearchResponse(data);
 }
@@ -783,6 +816,7 @@ var index_default = Telem;
   fingerprint,
   sessionKey,
   snapshotNodeKey,
+  toolMarker,
   windowAnchor,
   withTrajectory
 });

package/dist/index.d.cts

@@ -70,6 +70,9 @@ type SearchOptions = {
     goal?: string;
     context?: string;
     session?: string;
+    /** Abort this call: the request stops, no retry follows, and the call rejects
+     *  with the signal's reason. Merged with the per-attempt timeout. */
+    signal?: AbortSignal;
     /** Freeform metadata for the wire. Reserved trajectory-lineage keys
      *  (`RESERVED_METADATA`) are STRIPPED from here — lineage may only be attached
      *  through `withTrajectory`, fed by `buildMetadata`, never smuggled in as data. */
@@ -84,6 +87,9 @@ type FetchOptions = {
     inlineMaxChars?: number;
     contentFormat?: string;
     session?: string;
+    /** Abort this call: the request stops, no retry follows, and the call rejects
+     *  with the signal's reason. Merged with the per-attempt timeout. */
+    signal?: AbortSignal;
     metadata?: Json;
 };
 type TelemOptions = SearchDefaults & {
@@ -258,6 +264,12 @@ declare function snapshotNodeKey(harness: string, conversationId: string, messag
 /** Stable anchor id for content a host did not assign an id to.
  *  Length-prefixed like every other key component, so concatenation stays injective. */
 declare function contentAnchor(...parts: string[]): Promise<string>;
+/** `tool_marker` from telem/integrations/_trajectory_v5.py: one tool call as the
+ *  compact acting-trace marker every harness renders into history. The exporter
+ *  cuts goals on `[tool telem_search:`, so the text is a contract. Compact JSON,
+ *  key order kept, matches Python's `separators=(",", ":")`; an unserializable
+ *  input drops the suffix rather than the marker. */
+declare function toolMarker(name: string, status: string, args: unknown): string;
 /**
  * Identify this context-window generation by its first message.
  *
@@ -366,4 +378,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type ProviderInfo, type ProviderRun, RESERVED_METADATA, type SearchDefaults, type SearchOptions, type SearchResponse, type SearchResult, type SessionResults, type SessionSummary, type SessionsResource, type SnapshotArgs, Telem, type TelemClientErrorCode, TelemError, type TelemErrorOptions, type TelemOptions, TimeoutError, type TrajectoryArgs, type TrajectoryEnvelope, type TrajectorySnapshot, buildMetadata, buildSnapshot, contentAnchor, Telem as default, eventNodeKey, fingerprint, sessionKey, snapshotNodeKey, windowAnchor, withTrajectory };
+export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type ProviderInfo, type ProviderRun, RESERVED_METADATA, type SearchDefaults, type SearchOptions, type SearchResponse, type SearchResult, type SessionResults, type SessionSummary, type SessionsResource, type SnapshotArgs, Telem, type TelemClientErrorCode, TelemError, type TelemErrorOptions, type TelemOptions, TimeoutError, type TrajectoryArgs, type TrajectoryEnvelope, type TrajectorySnapshot, buildMetadata, buildSnapshot, contentAnchor, Telem as default, eventNodeKey, fingerprint, sessionKey, snapshotNodeKey, toolMarker, windowAnchor, withTrajectory };