@telemai/sdk 0.1.1 → 0.2.1

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.1";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -73,6 +74,9 @@ function csvEnv(raw) {
   const items = raw.split(",").map(trimBlank).filter((item) => item !== "");
   return items.length ? items : void 0;
 }
+function intEnv(raw) {
+  return raw !== void 0 && /^\s*[+-]?\d+\s*$/.test(raw) ? Number(raw) : void 0;
+}
 function readCredentials(env) {
   try {
     const proc = globalThis.process;
@@ -149,7 +153,10 @@ function resolveConfig(options) {
       fields: opts.fields ?? csvEnv(env.TELEM_FIELDS),
       providersInclude: opts.providersInclude ?? csvEnv(env.TELEM_PROVIDERS_INCLUDE),
       providersExclude: opts.providersExclude ?? csvEnv(env.TELEM_PROVIDERS_EXCLUDE),
-      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0)
+      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0),
+      autoRouting: opts.autoRouting ?? (trimBlank(env.TELEM_AUTO_ROUTING ?? "") || void 0),
+      maxRoutingProviders: opts.maxRoutingProviders ?? intEnv(env.TELEM_MAX_ROUTING_PROVIDERS),
+      topic: opts.topic ?? (trimBlank(env.TELEM_TOPIC ?? "") || void 0)
     }
   };
 }
@@ -243,7 +250,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 +263,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);
-    }
-    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);
     }
-    throw statusError(received.status, received.body);
   }
 }
 
@@ -372,10 +398,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 +544,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
@@ -554,6 +593,12 @@ function searchBlock(defaults, options) {
   if (options.includeRaw !== void 0) block.include_raw = options.includeRaw;
   if (options.rerank !== void 0) block.rerank = options.rerank;
   if (includeFullContent !== void 0) block.include_full_content = includeFullContent;
+  const autoRouting = options.autoRouting ?? defaults.autoRouting;
+  if (autoRouting !== void 0) block.auto_routing = autoRouting;
+  const maxRoutingProviders = options.maxRoutingProviders ?? defaults.maxRoutingProviders;
+  if (maxRoutingProviders !== void 0) block.max_routing_providers = maxRoutingProviders;
+  const topic = options.topic ?? defaults.topic;
+  if (topic !== void 0) block.topic = topic;
   return block;
 }
 function userInput(query) {
@@ -654,7 +699,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);
 }
@@ -722,7 +767,7 @@ var Telem = class {
   timeoutMs;
   /** Resolved retry budget (attempts after the first). */
   maxRetries;
-  /** The session read surface: `list()` and `results(id)`. */
+  /** The session read surface: `list` and `results(id)`. */
   sessions;
   #config;
   /**
@@ -783,6 +828,7 @@ var index_default = Telem;
   fingerprint,
   sessionKey,
   snapshotNodeKey,
+  toolMarker,
   windowAnchor,
   withTrajectory
 });

package/dist/index.d.cts

@@ -61,6 +61,9 @@ type SearchOptions = {
     numResults?: number;
     includeRaw?: boolean;
     includeFullContent?: boolean;
+    autoRouting?: string;
+    maxRoutingProviders?: number;
+    topic?: string;
     /** Opt this request into the server's rerank stage. It is the only path where
      *  `context`, the reasoning on the last assistant entry of the lineage history
      *  (that entry only), and `goal` change result ORDER (in that precedence) —
@@ -70,6 +73,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. */
@@ -77,13 +83,16 @@ type SearchOptions = {
 };
 /** The subset of search options that may also be set as a client default.
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
-type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent">;
+type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
     providers?: string[];
     inlineContent?: boolean;
     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 & {
@@ -181,7 +190,7 @@ type ProviderInfo = {
     normalized: boolean;
     tiers: string[];
 };
-/** One session as `sessions.list()` reports it. */
+/** One session as `sessions.list` reports it. */
 type SessionSummary = {
     id: string;
     createdAt: string | null;
@@ -258,6 +267,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 the Python SDK's _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.
  *
@@ -318,7 +333,7 @@ declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvel
  *
  * @example
  * ```ts
- * const telem = new Telem()                    // env / credentials-file resolution
+ * const telem = new Telem                    // env / credentials-file resolution
  * const telem = new Telem("tlm_...")           // bare API-key shorthand
  * const telem = new Telem({ apiKey, baseUrl, tier: "max" })
  * ```
@@ -333,7 +348,7 @@ declare class Telem {
     readonly timeoutMs: number;
     /** Resolved retry budget (attempts after the first). */
     readonly maxRetries: number;
-    /** The session read surface: `list()` and `results(id)`. */
+    /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
@@ -366,4 +381,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.d.ts

@@ -61,6 +61,9 @@ type SearchOptions = {
     numResults?: number;
     includeRaw?: boolean;
     includeFullContent?: boolean;
+    autoRouting?: string;
+    maxRoutingProviders?: number;
+    topic?: string;
     /** Opt this request into the server's rerank stage. It is the only path where
      *  `context`, the reasoning on the last assistant entry of the lineage history
      *  (that entry only), and `goal` change result ORDER (in that precedence) —
@@ -70,6 +73,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. */
@@ -77,13 +83,16 @@ type SearchOptions = {
 };
 /** The subset of search options that may also be set as a client default.
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
-type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent">;
+type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
     providers?: string[];
     inlineContent?: boolean;
     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 & {
@@ -181,7 +190,7 @@ type ProviderInfo = {
     normalized: boolean;
     tiers: string[];
 };
-/** One session as `sessions.list()` reports it. */
+/** One session as `sessions.list` reports it. */
 type SessionSummary = {
     id: string;
     createdAt: string | null;
@@ -258,6 +267,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 the Python SDK's _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.
  *
@@ -318,7 +333,7 @@ declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvel
  *
  * @example
  * ```ts
- * const telem = new Telem()                    // env / credentials-file resolution
+ * const telem = new Telem                    // env / credentials-file resolution
  * const telem = new Telem("tlm_...")           // bare API-key shorthand
  * const telem = new Telem({ apiKey, baseUrl, tier: "max" })
  * ```
@@ -333,7 +348,7 @@ declare class Telem {
     readonly timeoutMs: number;
     /** Resolved retry budget (attempts after the first). */
     readonly maxRetries: number;
-    /** The session read surface: `list()` and `results(id)`. */
+    /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
@@ -366,4 +381,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 };