@telemai/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -1,25 +1,28 @@
-// 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";
-  }
-};
+import {
+  RESERVED_METADATA,
+  TelemError,
+  TimeoutError,
+  asArray,
+  asObject,
+  buildMetadata,
+  buildSnapshot,
+  contentAnchor,
+  eventNodeKey,
+  fingerprint,
+  invalidRequest,
+  isObject,
+  request,
+  sessionKey,
+  snapshotNodeKey,
+  stringList,
+  toolMarker,
+  windowAnchor,
+  wireMetadata,
+  withTrajectory
+} from "./chunk-RYY4S5LP.js";
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -115,302 +118,6 @@ function resolveConfig(options) {
   };
 }
 
-// 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) {
-  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)}`);
-    }
-  }
-  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
-      };
-    } catch (cause) {
-      if (cause instanceof NotAResponse) {
-        throw new TelemError("the injected fetch returned something that is not a Response", {
-          code: "connection_error"
-        });
-      }
-      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 config.sleep(backoff(attempt));
-      continue;
-    } finally {
-      signal?.removeEventListener("abort", onAbort);
-    }
-    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);
-  }
-}
-
-// 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;
-function cap(value) {
-  if (value.length <= HISTORY_TEXT_CAP) return value;
-  return Array.from(value).slice(0, HISTORY_TEXT_CAP).join("");
-}
-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 };
-}
-
 // src/methods/fetch.ts
 function fetchBody(url, options) {
   const urls = stringList(
@@ -466,7 +173,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
@@ -615,7 +322,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);
 }
@@ -744,6 +451,7 @@ export {
   fingerprint,
   sessionKey,
   snapshotNodeKey,
+  toolMarker,
   windowAnchor,
   withTrajectory
 };