@telemai/sdk 0.3.2 → 0.4.0

package/README.md

@@ -167,6 +167,13 @@ const page = await telem.fetch("https://example.com/article", {
 const { status, content } = page.results[0]
 ```
 
+`providers` pins the fetch providers, in order; `tier` picks the fetch tier; and
+`noCache: true` reads the page live instead of from the shared cache. If you leave
+one out, the client uses its environment variable: `TELEM_FETCH_PROVIDERS` (comma
+separated), `TELEM_FETCH_TIER` (lowercased) or `TELEM_FETCH_NO_CACHE` (`1` turns it
+on). The client reads them when you create it. An option you pass wins, so
+`noCache: false` turns off `TELEM_FETCH_NO_CACHE=1` for that call.
+
 A URL that failed still returns a result. Check `result.status` and `result.error`.
 Do not expect a shorter list. The options are on the
 [fetch parameters](https://docs.telem.ai/resources/fetch-parameters/) page.
@@ -206,10 +213,22 @@ your last poll. `poll` returns a `SearchResponse`:
 ```ts
 const monitor = await telem.monitors.create("Nvidia files a new 8-K with the SEC", { frequency: "1h", ttl: "7d" })
 const response = await telem.monitors.poll(monitor.id)
+for await (const change of telem.monitors.iterateChanges(monitor.id)) {
+  console.log(change.seq, change.kind, change.subject.name)
+}
 await telem.monitors.update(monitor.id, { status: "paused" })
 await telem.monitors.delete(monitor.id)
 ```
 
+A monitor has an agent unless you create it with `agent: false`. The agent checks every
+result against the query and keeps the ones that match. `iterateChanges` reads what it
+kept, oldest first, until you are caught up, and then stops. Keep the `seq` of the last
+change you handled and pass it as `cursor` next time: no change comes twice, and none
+is skipped. `changes` returns one page (`nextCursor`, `watermark`) and takes
+`cursor`, `since`, `kinds` and `limit`. `agent` returns the agent itself: its status,
+query, frequency and plan version. `monitor.agentState` shows it on the monitor. Read
+`iterateChanges` with `for await`.
+
 `telem.monitors` also has `get` and `list`. See [Monitors](https://docs.telem.ai/resources/monitors/)
 for the fields and the errors.
 

package/dist/{chunk-DKTEG7EY.js → chunk-SQ3ZZA72.js}

@@ -80,8 +80,10 @@ function defaultMessage(status) {
   if (status === 404) return "Not found";
   return `Unexpected status code ${status}`;
 }
+var BLOCKED_MESSAGE = "The request was blocked by a firewall before it reached Telem; the text may have characters that are not allowed.";
 function statusError(status, body) {
-  return new TelemError(detailFromBody(body) ?? defaultMessage(status), {
+  const fallback = status === 403 && !isObject(body) ? BLOCKED_MESSAGE : defaultMessage(status);
+  return new TelemError(detailFromBody(body) ?? fallback, {
     status,
     code: codeFromBody(body),
     details: body

package/dist/index.cjs

@@ -60,7 +60,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.3.2";
+var VERSION = "0.4.0";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -120,6 +120,7 @@ function resolveConfig(options) {
   if (typeof send !== "function") {
     throw invalidOption("no fetch on this runtime: pass one with the `fetch` option");
   }
+  if (typeof opts.apiKey === "string" && !opts.apiKey.trim()) throw invalidOption("apiKey is empty");
   let apiKey = opts.apiKey || env.TELEM_API_KEY || void 0;
   let baseUrl = opts.baseUrl || env.TELEM_BASE_URL || void 0;
   if (apiKey === void 0 || baseUrl === void 0) {
@@ -158,6 +159,14 @@ function resolveConfig(options) {
       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)
+    },
+    // Fetch defaults: env var only, parsed as the shared option table parses it (CSV,
+    // a trimmed name, a "1"-only flag); the tier is lowercased, as the agent plugins
+    // send it. No constructor option, and no config file, as above.
+    fetchDefaults: {
+      providers: csvEnv(env.TELEM_FETCH_PROVIDERS),
+      tier: trimBlank(env.TELEM_FETCH_TIER ?? "").toLowerCase() || void 0,
+      noCache: env.TELEM_FETCH_NO_CACHE === "1" || void 0
     }
   };
 }
@@ -224,8 +233,10 @@ function defaultMessage(status) {
   if (status === 404) return "Not found";
   return `Unexpected status code ${status}`;
 }
+var BLOCKED_MESSAGE = "The request was blocked by a firewall before it reached Telem; the text may have characters that are not allowed.";
 function statusError(status, body) {
-  return new TelemError(detailFromBody(body) ?? defaultMessage(status), {
+  const fallback = status === 403 && !isObject(body) ? BLOCKED_MESSAGE : defaultMessage(status);
+  return new TelemError(detailFromBody(body) ?? fallback, {
     status,
     code: codeFromBody(body),
     details: body
@@ -492,7 +503,7 @@ function wireMetadata(options, kind) {
 }
 
 // src/methods/fetch.ts
-function fetchBody(url, options) {
+function fetchBody(url, options, defaults) {
   const urls = stringList(
     typeof url === "string" ? [url] : url,
     "fetch() requires at least one URL",
@@ -500,11 +511,16 @@ function fetchBody(url, options) {
   );
   const { metadata, sessionId } = wireMetadata(options, "fetch");
   const body = { urls, metadata };
+  const providers2 = options.providers ?? defaults.providers;
+  const tier = options.tier ?? defaults.tier;
+  const noCache = options.noCache ?? defaults.noCache;
   const block = {};
-  if (options.providers !== void 0) block.providers = options.providers;
+  if (providers2 !== void 0) block.providers = providers2;
   if (options.inlineContent !== void 0) block.inline_content = options.inlineContent;
   if (options.inlineMaxChars !== void 0) block.inline_max_chars = options.inlineMaxChars;
   if (options.contentFormat !== void 0) block.content_format = options.contentFormat;
+  if (tier !== void 0) block.tier = tier;
+  if (noCache !== void 0) block.no_cache = noCache;
   if (Object.keys(block).length) body.options = block;
   if (sessionId !== void 0) body.session_id = sessionId;
   return body;
@@ -545,12 +561,17 @@ function buildFetchResponse(interaction) {
   };
 }
 async function fetchUrls(config, url, options) {
-  const body = fetchBody(url, options);
+  const body = fetchBody(url, options, config.fetchDefaults);
   return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
 // src/methods/search.ts
 var MIN_SCHEMA_VERSION = 2;
+function providersRefusal(include, includeFromCall, excludeFromCall) {
+  const where = (half, env, fromCall) => fromCall ? `the ${half} search() option` : `the client's ${half} or ${env}`;
+  const names = include.join(", ");
+  return `providersExclude removes every provider in providersInclude (${names}), so no provider is left and no search was sent. Remove ${names} from providersInclude (set by ${where("providersInclude", "TELEM_PROVIDERS_INCLUDE", includeFromCall)}) or from providersExclude (set by ${where("providersExclude", "TELEM_PROVIDERS_EXCLUDE", excludeFromCall)}).`;
+}
 function searchBlock(defaults, options) {
   const fromCallTier = options.tier !== void 0;
   const fromCallFields = options.fields !== void 0;
@@ -564,7 +585,13 @@ function searchBlock(defaults, options) {
   let exclude = options.providersExclude ?? defaults.providersExclude;
   if (include !== void 0 && exclude !== void 0) {
     const excluded = new Set(exclude);
-    include = include.filter((name) => !excluded.has(name));
+    const kept = include.filter((name) => !excluded.has(name));
+    if (include.length && !kept.length) {
+      throw invalidRequest(
+        providersRefusal(include, options.providersInclude !== void 0, options.providersExclude !== void 0)
+      );
+    }
+    include = kept;
     exclude = void 0;
   }
   const includeFullContent = options.includeFullContent ?? defaults.includeFullContent;
@@ -674,7 +701,8 @@ function providerRun(run) {
     related: envelope.related ?? null,
     verticals: envelope.verticals ?? null,
     usage: envelope.usage ?? null,
-    warnings: asArray(envelope.warnings)
+    warnings: asArray(envelope.warnings),
+    sameStory: isObject(envelope.same_story) ? envelope.same_story : null
   };
 }
 function buildSearchResponse(interaction) {
@@ -698,9 +726,25 @@ async function search(config, query, options) {
 }
 
 // src/methods/monitors.ts
+function agentStateFrom(data) {
+  return {
+    engine: String(data.engine ?? ""),
+    status: String(data.status ?? ""),
+    needsAttention: data.needs_attention === true,
+    planVersion: typeof data.plan_version === "number" ? data.plan_version : null,
+    nextRunAt: typeof data.next_run_at === "string" ? data.next_run_at : null,
+    watermark: Number(data.watermark ?? 0),
+    // No compile job yet is null, not an object of empty strings.
+    compile: isObject(data.compile) ? {
+      jobId: String(data.compile.job_id ?? ""),
+      status: String(data.compile.status ?? ""),
+      error: typeof data.compile.error === "string" ? data.compile.error : null
+    } : null
+  };
+}
 function monitorFrom(body) {
   const data = asObject(body);
-  return {
+  const monitor = {
     id: String(data.id ?? ""),
     query: data.query ?? "",
     frequency: data.frequency ?? "",
@@ -713,12 +757,85 @@ function monitorFrom(body) {
     webhookSecret: data.webhook_secret ?? null,
     raw: data
   };
+  if (data.agent_state !== void 0) {
+    monitor.agentState = isObject(data.agent_state) ? agentStateFrom(data.agent_state) : null;
+  }
+  return monitor;
+}
+function agentDocumentFrom(body) {
+  const data = asObject(body);
+  const document = { raw: data };
+  if (typeof data.status === "string") document.status = data.status;
+  if (typeof data.query === "string") document.query = data.query;
+  if (typeof data.frequency === "string") document.frequency = data.frequency;
+  if (typeof data.spec_version === "number") document.specVersion = data.spec_version;
+  if (data.budget !== void 0) document.budget = isObject(data.budget) ? data.budget : null;
+  if (typeof data.spend_usd === "number") document.spendUsd = data.spend_usd;
+  return document;
+}
+function changeRecordFrom(entry) {
+  const subject = asObject(entry.subject);
+  return {
+    seq: Number(entry.seq ?? 0),
+    type: String(entry.type ?? ""),
+    kind: String(entry.kind ?? ""),
+    monitorId: String(entry.monitor_id ?? ""),
+    subject: {
+      entityId: typeof subject.entity_id === "string" ? subject.entity_id : null,
+      name: typeof subject.name === "string" ? subject.name : null
+    },
+    // The values depend on the kind (an object, a status string, nothing): as sent.
+    before: entry.before ?? null,
+    after: entry.after ?? null,
+    factIds: asArray(entry.fact_ids).map(String),
+    at: String(entry.at ?? ""),
+    raw: entry
+  };
+}
+function changesPageFrom(body) {
+  const data = asObject(body);
+  return {
+    changes: asArray(data.changes).filter(isObject).map(changeRecordFrom),
+    nextCursor: Number(data.next_cursor ?? 0),
+    watermark: Number(data.watermark ?? 0)
+  };
+}
+function listQuery(options) {
+  const params = new URLSearchParams();
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  if (options.cursor !== void 0) params.set("cursor", options.cursor);
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+function sinceParam(since) {
+  if (typeof since === "string") return since;
+  if (Number.isNaN(since.getTime())) throw invalidRequest("since is not a valid date");
+  return since.toISOString();
+}
+function changesQuery(options) {
+  const params = new URLSearchParams();
+  if (options.cursor !== void 0) params.set("cursor", String(options.cursor));
+  if (options.since !== void 0) params.set("since", sinceParam(options.since));
+  if (options.kinds !== void 0) params.set("kinds", options.kinds.join(","));
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  const query = params.toString();
+  return query ? `?${query}` : "";
 }
 function createMonitors(config) {
   const path = (monitorId, suffix = "") => {
     if (!monitorId || /^\.+$/.test(monitorId)) throw invalidRequest("a monitor id is required");
     return `/v1/monitors/${encodeURIComponent(monitorId)}${suffix}`;
   };
+  const listPage = async (options = {}) => {
+    const route = `/v1/monitors${listQuery(options)}`;
+    const data = asObject(await request(config, "GET", route, void 0, options.signal));
+    const nextCursor = typeof data.next_cursor === "string" ? data.next_cursor : null;
+    return { monitors: asArray(data.monitors).map(monitorFrom), nextCursor };
+  };
+  const changes = async (monitorId, options = {}) => {
+    const route = `${path(monitorId, "/agent/changes")}${changesQuery(options)}`;
+    return changesPageFrom(await request(config, "GET", route, void 0, options.signal));
+  };
   return {
     /** Create a monitor. Telem runs `query` on the schedule. */
     async create(query, options = {}) {
@@ -732,15 +849,25 @@ function createMonitors(config) {
       if (options.metadata !== void 0) body.metadata = options.metadata;
       if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       if (options.ttl !== void 0) body.ttl = options.ttl;
-      const data = await request(config, "POST", "/v1/monitors", body, options.signal, "rate_limit");
+      if (options.agent !== void 0) body.agent = options.agent;
+      const data = await request(config, "POST", "/v1/monitors", body, options.signal, "rate_limit").catch(
+        (error) => {
+          if (error instanceof TimeoutError) {
+            throw new TimeoutError(
+              `${error.message}. The monitor may exist: list monitors before you create it again.`,
+              error.cause
+            );
+          }
+          throw error;
+        }
+      );
       return monitorFrom(data);
     },
-    /** List your monitors, newest first (server default 50, maximum 200). */
+    /** List your monitors, newest first. `listPage` also gives the next cursor. */
     async list(options = {}) {
-      const query = options.limit === void 0 ? "" : `?limit=${options.limit}`;
-      const body = await request(config, "GET", `/v1/monitors${query}`, void 0, options.signal);
-      return asArray(asObject(body).monitors).map(monitorFrom);
+      return (await listPage(options)).monitors;
     },
+    listPage,
     /** Get one monitor. */
     async get(monitorId, options = {}) {
       return monitorFrom(await request(config, "GET", path(monitorId), void 0, options.signal));
@@ -750,7 +877,7 @@ function createMonitors(config) {
       const body = {};
       if (options.status !== void 0) body.status = options.status;
       if (options.frequency !== void 0) body.frequency = options.frequency;
-      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
+      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl || null;
       const route = path(monitorId);
       return monitorFrom(await request(config, "PATCH", route, body, options.signal));
     },
@@ -766,6 +893,23 @@ function createMonitors(config) {
     /** Delete a monitor. A repeat deletes what a failed delete left. */
     async delete(monitorId, options = {}) {
       await request(config, "DELETE", path(monitorId), void 0, options.signal);
+    },
+    /** Read the monitor agent's document. A monitor without an agent answers 404. */
+    async agent(monitorId, options = {}) {
+      const route = path(monitorId, "/agent");
+      return agentDocumentFrom(await request(config, "GET", route, void 0, options.signal));
+    },
+    /** One page of the agent's changes. Keep `nextCursor` and pass it back as `cursor`. */
+    changes,
+    /** Every change after `cursor`, page by page, until you are caught up. */
+    async *iterateChanges(monitorId, options = {}) {
+      let cursor = options.cursor ?? 0;
+      for (; ; ) {
+        const page = await changes(monitorId, { cursor, signal: options.signal });
+        for (const change of page.changes) yield change;
+        if (!page.changes.length || page.nextCursor <= cursor || page.nextCursor >= page.watermark) return;
+        cursor = page.nextCursor;
+      }
     }
   };
 }
@@ -798,7 +942,8 @@ async function providers(config) {
     method: entry.method ?? null,
     url: entry.url ?? null,
     normalized: entry.normalized ?? false,
-    tiers: asArray(entry.tiers)
+    tiers: asArray(entry.tiers),
+    autoRouted: entry.auto_routed ?? null
   }));
 }
 
@@ -867,7 +1012,8 @@ var Telem = class {
   maxRetries;
   /** The session read surface: `list` and `results(id)`. */
   sessions;
-  /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+  /** Monitors: `create`, `list`, `listPage`, `get`, `update`, `poll`, `delete`, and the
+   *  agent reads `agent`, `changes` and `iterateChanges`. */
   monitors;
   #config;
   /**

package/dist/index.d.cts

@@ -96,10 +96,17 @@ type SearchOptions = {
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
 type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
+    /** Fetch provider chain, in order. Defaults to `TELEM_FETCH_PROVIDERS`. */
     providers?: string[];
     inlineContent?: boolean;
     inlineMaxChars?: number;
     contentFormat?: string;
+    /** Fetch tier: `minimalist`, `default`, `extended` or `max`. Sent as given; the
+     *  server rejects an unknown one. Defaults to `TELEM_FETCH_TIER`, lowercased. */
+    tier?: string;
+    /** `true` reads every page live and skips the shared fetch cache. Defaults to
+     *  `TELEM_FETCH_NO_CACHE` (on with exactly `"1"`); `false` overrides it. */
+    noCache?: boolean;
     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. */
@@ -150,6 +157,8 @@ type ProviderRun = {
     verticals: Json | null;
     usage: Json | unknown[] | null;
     warnings: Json[];
+    /** Monitor polls: results folded as the same story, `{leadUrl: [{url, title}]}`. */
+    sameStory: Record<string, Json[]> | null;
     raw: Json | null;
 };
 type SearchResponse = {
@@ -200,6 +209,8 @@ type ProviderInfo = {
     url: string | null;
     normalized: boolean;
     tiers: string[];
+    /** Whether auto-routing can pick it; `null` from a router that does not say. */
+    autoRouted: boolean | null;
 };
 /** One session as `sessions.list` reports it. */
 type SessionSummary = {
@@ -243,6 +254,10 @@ type MonitorCreateOptions = {
     webhookUrl?: string;
     /** Delete the monitor after this long, such as `"12h"` or `"7d"` (at most `"30d"`). Without it, the monitor never expires. */
     ttl?: string;
+    /** Start the monitor agent with the monitor: it checks every result against the query
+     *  and keeps the ones that match. Telem turns it on when you leave this out; `false`
+     *  creates the monitor without one. Read what the agent keeps with `monitors.changes`. */
+    agent?: boolean;
     signal?: AbortSignal;
 };
 /** Options for `monitors.update`. Send at least one field. */
@@ -250,7 +265,7 @@ type MonitorUpdateOptions = {
     /** `"paused"` or `"active"`. */
     status?: string;
     frequency?: string;
-    /** A new webhook URL, with a new `webhookSecret` in the response. `null` removes it. */
+    /** A new webhook URL, with a new `webhookSecret` in the response. `null` or `""` removes it. */
     webhookUrl?: string | null;
     signal?: AbortSignal;
 };
@@ -267,25 +282,144 @@ type Monitor = {
     id: string;
     query: string;
     frequency: string;
-    /** `active` or `paused` (you paused it). */
+    /** `active`, `paused` (you paused it) or `ended` (past `expiresAt`). */
     status: string;
     sessionId: string;
     createdAt: string;
     lastPolledAt: string | null;
-    /** When Telem deletes the monitor; `null`: never. */
+    /** When the monitor ends; `null`: never. */
     expiresAt: string | null;
     webhookUrl: string | null;
     /** Signs the webhook deliveries. Only in the response that set `webhookUrl`. */
     webhookSecret: string | null;
+    /** The monitor agent's state. `null`: the monitor has no agent. Absent when the router
+     *  sends none, as a router from before the agent reads does. */
+    agentState?: AgentState | null;
+    raw: Json;
+};
+/** The latest compile of an agent's plan (`AgentState.compile`). */
+type AgentCompileState = {
+    jobId: string;
+    /** The compile job's status, such as `done` or `failed`. */
+    status: string;
+    /** Why the compile failed; `null` when it did not. */
+    error: string | null;
+};
+/** The state of a monitor's agent: `monitor.agentState`. */
+type AgentState = {
+    /** The agent engine, `"v4"` today. */
+    engine: string;
+    /** Such as `compiling`, `ready`, `paused` or `failed`. */
+    status: string;
+    /** `true` when `status` is `failed`. */
+    needsAttention: boolean;
+    /** The version of the agent's plan; `null` before it has one. */
+    planVersion: number | null;
+    /** When the agent runs next; `null` when no run is scheduled. */
+    nextRunAt: string | null;
+    /** The `seq` of the newest change `monitors.changes` can serve now. */
+    watermark: number;
+    /** The latest compile of the plan; `null` when there has been none. */
+    compile: AgentCompileState | null;
+};
+/** The monitor agent's document: `monitors.agent`. A field is there only when the
+ *  router sent it. The rest of the document (the plan, the counts, the runs) is in `raw`. */
+type AgentDocument = {
+    /** Such as `compiling`, `ready`, `paused`, `failed` or `ended`. */
+    status?: string;
+    query?: string;
+    frequency?: string;
+    /** The version of the plan; 0 while the agent compiles. */
+    specVersion?: number;
+    /** The agent's spending limits; `null` when none are set. */
+    budget?: Json | null;
+    /** What the agent has spent, in US dollars. */
+    spendUsd?: number;
     raw: Json;
 };
+/** The item a change is about. `entityId` is `null` for a change to the whole monitor,
+ *  such as a run or a plan change. */
+type ChangeSubject = {
+    entityId: string | null;
+    name: string | null;
+};
+/** One change the monitor agent made. */
+type ChangeRecord = {
+    /** The change's place in the stream. It grows with every change and is never reused.
+     *  Pass the last one you handled as `cursor` to read on from there. */
+    seq: number;
+    /** The change's own type, such as `new_object`. */
+    type: string;
+    /** What happened: one of the six kinds `entity_added`, `value_changed`,
+     *  `fact_status_changed`, `alert`, `run` or `plan_changed`. */
+    kind: string;
+    monitorId: string;
+    subject: ChangeSubject;
+    /** What it was before, as the router sent it; `null` when there is no before. Its shape
+     *  depends on `kind`. */
+    before: unknown;
+    /** What it is now, as the router sent it. */
+    after: unknown;
+    /** The facts behind the change; empty when the router names none. */
+    factIds: string[];
+    /** When it happened, ISO 8601. */
+    at: string;
+    raw: Json;
+};
+/** One page of `monitors.changes`. */
+type ChangesPage = {
+    changes: ChangeRecord[];
+    /** Keep this and pass it as `cursor` to read the changes after this page. On a full
+     *  page (`limit` changes) it is the `seq` of the last change. On a shorter page, an
+     *  empty one included, it is `watermark`: the read got that far, past the changes
+     *  that `kinds` left out too. */
+    nextCursor: number;
+    /** The `seq` of the newest change that can be read now. You are caught up when
+     *  `nextCursor` equals it, or when a page is empty. */
+    watermark: number;
+};
+/** Options for `monitors.changes`. */
+type MonitorChangesOptions = {
+    /** Read the changes after this `seq`. If you leave it out, the page starts at the
+     *  first change. Do not send it with `since`. */
+    cursor?: number;
+    /** Read from this time on: a `Date`, or an ISO 8601 time with an offset such as
+     *  `"2026-11-03T12:00:00Z"`. Do not send it with `cursor`. */
+    since?: string | Date;
+    /** Only these kinds of change: `entity_added`, `value_changed`, `fact_status_changed`,
+     *  `alert`, `run` or `plan_changed`, for example `["alert", "run"]`. Another name is a
+     *  400 (`kinds_invalid`). An empty list is no filter. */
+    kinds?: string[];
+    /** How many changes to return (server default 200, maximum 500). */
+    limit?: number;
+    signal?: AbortSignal;
+};
+/** Options for `monitors.iterateChanges`. */
+type MonitorIterateChangesOptions = {
+    /** Read the changes after this `seq`. If you leave it out, the walk starts at the
+     *  first change. */
+    cursor?: number;
+    signal?: AbortSignal;
+};
+/** Options for `monitors.list` and `monitors.listPage`. */
+type MonitorListOptions = {
+    /** How many to return (server default 50, maximum 200). */
+    limit?: number;
+    /** The `nextCursor` of the page before. */
+    cursor?: string;
+    signal?: AbortSignal;
+};
+/** One page of `monitors.listPage`. */
+type MonitorPage = {
+    monitors: Monitor[];
+    /** Pass as `cursor` to get the next page; `null` on the last page. */
+    nextCursor: string | null;
+};
 /** The `telem.monitors` namespace. */
 type MonitorsResource = {
     create(query: string, options?: MonitorCreateOptions): Promise<Monitor>;
-    list(options?: {
-        limit?: number;
-        signal?: AbortSignal;
-    }): Promise<Monitor[]>;
+    list(options?: MonitorListOptions): Promise<Monitor[]>;
+    listPage(options?: MonitorListOptions): Promise<MonitorPage>;
     get(monitorId: string, options?: {
         signal?: AbortSignal;
     }): Promise<Monitor>;
@@ -294,6 +428,14 @@ type MonitorsResource = {
     delete(monitorId: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Read the monitor agent's document. A monitor without an agent answers 404. */
+    agent(monitorId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentDocument>;
+    /** One page of the agent's changes. Keep `nextCursor` and pass it back as `cursor`. */
+    changes(monitorId: string, options?: MonitorChangesOptions): Promise<ChangesPage>;
+    /** Every change after `cursor`, page by page, until you are caught up. */
+    iterateChanges(monitorId: string, options?: MonitorIterateChangesOptions): AsyncGenerator<ChangeRecord, void, undefined>;
 };
 
 /**
@@ -437,7 +579,8 @@ declare class Telem {
     readonly maxRetries: number;
     /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
-    /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+    /** Monitors: `create`, `list`, `listPage`, `get`, `update`, `poll`, `delete`, and the
+     *  agent reads `agent`, `changes` and `iterateChanges`. */
     readonly monitors: MonitorsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
@@ -470,4 +613,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorCreateOptions, type MonitorPollOptions, type MonitorUpdateOptions, type MonitorsResource, 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, verifyWebhook, windowAnchor, withTrajectory };
+export { type AgentCompileState, type AgentDocument, type AgentState, type ChangeRecord, type ChangeSubject, type ChangesPage, type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorChangesOptions, type MonitorCreateOptions, type MonitorIterateChangesOptions, type MonitorListOptions, type MonitorPage, type MonitorPollOptions, type MonitorUpdateOptions, type MonitorsResource, 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, verifyWebhook, windowAnchor, withTrajectory };

package/dist/index.d.ts

@@ -96,10 +96,17 @@ type SearchOptions = {
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
 type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
+    /** Fetch provider chain, in order. Defaults to `TELEM_FETCH_PROVIDERS`. */
     providers?: string[];
     inlineContent?: boolean;
     inlineMaxChars?: number;
     contentFormat?: string;
+    /** Fetch tier: `minimalist`, `default`, `extended` or `max`. Sent as given; the
+     *  server rejects an unknown one. Defaults to `TELEM_FETCH_TIER`, lowercased. */
+    tier?: string;
+    /** `true` reads every page live and skips the shared fetch cache. Defaults to
+     *  `TELEM_FETCH_NO_CACHE` (on with exactly `"1"`); `false` overrides it. */
+    noCache?: boolean;
     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. */
@@ -150,6 +157,8 @@ type ProviderRun = {
     verticals: Json | null;
     usage: Json | unknown[] | null;
     warnings: Json[];
+    /** Monitor polls: results folded as the same story, `{leadUrl: [{url, title}]}`. */
+    sameStory: Record<string, Json[]> | null;
     raw: Json | null;
 };
 type SearchResponse = {
@@ -200,6 +209,8 @@ type ProviderInfo = {
     url: string | null;
     normalized: boolean;
     tiers: string[];
+    /** Whether auto-routing can pick it; `null` from a router that does not say. */
+    autoRouted: boolean | null;
 };
 /** One session as `sessions.list` reports it. */
 type SessionSummary = {
@@ -243,6 +254,10 @@ type MonitorCreateOptions = {
     webhookUrl?: string;
     /** Delete the monitor after this long, such as `"12h"` or `"7d"` (at most `"30d"`). Without it, the monitor never expires. */
     ttl?: string;
+    /** Start the monitor agent with the monitor: it checks every result against the query
+     *  and keeps the ones that match. Telem turns it on when you leave this out; `false`
+     *  creates the monitor without one. Read what the agent keeps with `monitors.changes`. */
+    agent?: boolean;
     signal?: AbortSignal;
 };
 /** Options for `monitors.update`. Send at least one field. */
@@ -250,7 +265,7 @@ type MonitorUpdateOptions = {
     /** `"paused"` or `"active"`. */
     status?: string;
     frequency?: string;
-    /** A new webhook URL, with a new `webhookSecret` in the response. `null` removes it. */
+    /** A new webhook URL, with a new `webhookSecret` in the response. `null` or `""` removes it. */
     webhookUrl?: string | null;
     signal?: AbortSignal;
 };
@@ -267,25 +282,144 @@ type Monitor = {
     id: string;
     query: string;
     frequency: string;
-    /** `active` or `paused` (you paused it). */
+    /** `active`, `paused` (you paused it) or `ended` (past `expiresAt`). */
     status: string;
     sessionId: string;
     createdAt: string;
     lastPolledAt: string | null;
-    /** When Telem deletes the monitor; `null`: never. */
+    /** When the monitor ends; `null`: never. */
     expiresAt: string | null;
     webhookUrl: string | null;
     /** Signs the webhook deliveries. Only in the response that set `webhookUrl`. */
     webhookSecret: string | null;
+    /** The monitor agent's state. `null`: the monitor has no agent. Absent when the router
+     *  sends none, as a router from before the agent reads does. */
+    agentState?: AgentState | null;
+    raw: Json;
+};
+/** The latest compile of an agent's plan (`AgentState.compile`). */
+type AgentCompileState = {
+    jobId: string;
+    /** The compile job's status, such as `done` or `failed`. */
+    status: string;
+    /** Why the compile failed; `null` when it did not. */
+    error: string | null;
+};
+/** The state of a monitor's agent: `monitor.agentState`. */
+type AgentState = {
+    /** The agent engine, `"v4"` today. */
+    engine: string;
+    /** Such as `compiling`, `ready`, `paused` or `failed`. */
+    status: string;
+    /** `true` when `status` is `failed`. */
+    needsAttention: boolean;
+    /** The version of the agent's plan; `null` before it has one. */
+    planVersion: number | null;
+    /** When the agent runs next; `null` when no run is scheduled. */
+    nextRunAt: string | null;
+    /** The `seq` of the newest change `monitors.changes` can serve now. */
+    watermark: number;
+    /** The latest compile of the plan; `null` when there has been none. */
+    compile: AgentCompileState | null;
+};
+/** The monitor agent's document: `monitors.agent`. A field is there only when the
+ *  router sent it. The rest of the document (the plan, the counts, the runs) is in `raw`. */
+type AgentDocument = {
+    /** Such as `compiling`, `ready`, `paused`, `failed` or `ended`. */
+    status?: string;
+    query?: string;
+    frequency?: string;
+    /** The version of the plan; 0 while the agent compiles. */
+    specVersion?: number;
+    /** The agent's spending limits; `null` when none are set. */
+    budget?: Json | null;
+    /** What the agent has spent, in US dollars. */
+    spendUsd?: number;
     raw: Json;
 };
+/** The item a change is about. `entityId` is `null` for a change to the whole monitor,
+ *  such as a run or a plan change. */
+type ChangeSubject = {
+    entityId: string | null;
+    name: string | null;
+};
+/** One change the monitor agent made. */
+type ChangeRecord = {
+    /** The change's place in the stream. It grows with every change and is never reused.
+     *  Pass the last one you handled as `cursor` to read on from there. */
+    seq: number;
+    /** The change's own type, such as `new_object`. */
+    type: string;
+    /** What happened: one of the six kinds `entity_added`, `value_changed`,
+     *  `fact_status_changed`, `alert`, `run` or `plan_changed`. */
+    kind: string;
+    monitorId: string;
+    subject: ChangeSubject;
+    /** What it was before, as the router sent it; `null` when there is no before. Its shape
+     *  depends on `kind`. */
+    before: unknown;
+    /** What it is now, as the router sent it. */
+    after: unknown;
+    /** The facts behind the change; empty when the router names none. */
+    factIds: string[];
+    /** When it happened, ISO 8601. */
+    at: string;
+    raw: Json;
+};
+/** One page of `monitors.changes`. */
+type ChangesPage = {
+    changes: ChangeRecord[];
+    /** Keep this and pass it as `cursor` to read the changes after this page. On a full
+     *  page (`limit` changes) it is the `seq` of the last change. On a shorter page, an
+     *  empty one included, it is `watermark`: the read got that far, past the changes
+     *  that `kinds` left out too. */
+    nextCursor: number;
+    /** The `seq` of the newest change that can be read now. You are caught up when
+     *  `nextCursor` equals it, or when a page is empty. */
+    watermark: number;
+};
+/** Options for `monitors.changes`. */
+type MonitorChangesOptions = {
+    /** Read the changes after this `seq`. If you leave it out, the page starts at the
+     *  first change. Do not send it with `since`. */
+    cursor?: number;
+    /** Read from this time on: a `Date`, or an ISO 8601 time with an offset such as
+     *  `"2026-11-03T12:00:00Z"`. Do not send it with `cursor`. */
+    since?: string | Date;
+    /** Only these kinds of change: `entity_added`, `value_changed`, `fact_status_changed`,
+     *  `alert`, `run` or `plan_changed`, for example `["alert", "run"]`. Another name is a
+     *  400 (`kinds_invalid`). An empty list is no filter. */
+    kinds?: string[];
+    /** How many changes to return (server default 200, maximum 500). */
+    limit?: number;
+    signal?: AbortSignal;
+};
+/** Options for `monitors.iterateChanges`. */
+type MonitorIterateChangesOptions = {
+    /** Read the changes after this `seq`. If you leave it out, the walk starts at the
+     *  first change. */
+    cursor?: number;
+    signal?: AbortSignal;
+};
+/** Options for `monitors.list` and `monitors.listPage`. */
+type MonitorListOptions = {
+    /** How many to return (server default 50, maximum 200). */
+    limit?: number;
+    /** The `nextCursor` of the page before. */
+    cursor?: string;
+    signal?: AbortSignal;
+};
+/** One page of `monitors.listPage`. */
+type MonitorPage = {
+    monitors: Monitor[];
+    /** Pass as `cursor` to get the next page; `null` on the last page. */
+    nextCursor: string | null;
+};
 /** The `telem.monitors` namespace. */
 type MonitorsResource = {
     create(query: string, options?: MonitorCreateOptions): Promise<Monitor>;
-    list(options?: {
-        limit?: number;
-        signal?: AbortSignal;
-    }): Promise<Monitor[]>;
+    list(options?: MonitorListOptions): Promise<Monitor[]>;
+    listPage(options?: MonitorListOptions): Promise<MonitorPage>;
     get(monitorId: string, options?: {
         signal?: AbortSignal;
     }): Promise<Monitor>;
@@ -294,6 +428,14 @@ type MonitorsResource = {
     delete(monitorId: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Read the monitor agent's document. A monitor without an agent answers 404. */
+    agent(monitorId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentDocument>;
+    /** One page of the agent's changes. Keep `nextCursor` and pass it back as `cursor`. */
+    changes(monitorId: string, options?: MonitorChangesOptions): Promise<ChangesPage>;
+    /** Every change after `cursor`, page by page, until you are caught up. */
+    iterateChanges(monitorId: string, options?: MonitorIterateChangesOptions): AsyncGenerator<ChangeRecord, void, undefined>;
 };
 
 /**
@@ -437,7 +579,8 @@ declare class Telem {
     readonly maxRetries: number;
     /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
-    /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+    /** Monitors: `create`, `list`, `listPage`, `get`, `update`, `poll`, `delete`, and the
+     *  agent reads `agent`, `changes` and `iterateChanges`. */
     readonly monitors: MonitorsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
@@ -470,4 +613,4 @@ declare class Telem {
     providers(): Promise<ProviderInfo[]>;
 }
 
-export { type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorCreateOptions, type MonitorPollOptions, type MonitorUpdateOptions, type MonitorsResource, 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, verifyWebhook, windowAnchor, withTrajectory };
+export { type AgentCompileState, type AgentDocument, type AgentState, type ChangeRecord, type ChangeSubject, type ChangesPage, type FetchOptions, type FetchResponse, type FetchResult, type Json, type Monitor, type MonitorChangesOptions, type MonitorCreateOptions, type MonitorIterateChangesOptions, type MonitorListOptions, type MonitorPage, type MonitorPollOptions, type MonitorUpdateOptions, type MonitorsResource, 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, verifyWebhook, windowAnchor, withTrajectory };

package/dist/index.js

@@ -19,10 +19,10 @@ import {
   windowAnchor,
   wireMetadata,
   withTrajectory
-} from "./chunk-DKTEG7EY.js";
+} from "./chunk-SQ3ZZA72.js";
 
 // src/version.ts
-var VERSION = "0.3.2";
+var VERSION = "0.4.0";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -82,6 +82,7 @@ function resolveConfig(options) {
   if (typeof send !== "function") {
     throw invalidOption("no fetch on this runtime: pass one with the `fetch` option");
   }
+  if (typeof opts.apiKey === "string" && !opts.apiKey.trim()) throw invalidOption("apiKey is empty");
   let apiKey = opts.apiKey || env.TELEM_API_KEY || void 0;
   let baseUrl = opts.baseUrl || env.TELEM_BASE_URL || void 0;
   if (apiKey === void 0 || baseUrl === void 0) {
@@ -120,12 +121,20 @@ function resolveConfig(options) {
       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)
+    },
+    // Fetch defaults: env var only, parsed as the shared option table parses it (CSV,
+    // a trimmed name, a "1"-only flag); the tier is lowercased, as the agent plugins
+    // send it. No constructor option, and no config file, as above.
+    fetchDefaults: {
+      providers: csvEnv(env.TELEM_FETCH_PROVIDERS),
+      tier: trimBlank(env.TELEM_FETCH_TIER ?? "").toLowerCase() || void 0,
+      noCache: env.TELEM_FETCH_NO_CACHE === "1" || void 0
     }
   };
 }
 
 // src/methods/fetch.ts
-function fetchBody(url, options) {
+function fetchBody(url, options, defaults) {
   const urls = stringList(
     typeof url === "string" ? [url] : url,
     "fetch() requires at least one URL",
@@ -133,11 +142,16 @@ function fetchBody(url, options) {
   );
   const { metadata, sessionId } = wireMetadata(options, "fetch");
   const body = { urls, metadata };
+  const providers2 = options.providers ?? defaults.providers;
+  const tier = options.tier ?? defaults.tier;
+  const noCache = options.noCache ?? defaults.noCache;
   const block = {};
-  if (options.providers !== void 0) block.providers = options.providers;
+  if (providers2 !== void 0) block.providers = providers2;
   if (options.inlineContent !== void 0) block.inline_content = options.inlineContent;
   if (options.inlineMaxChars !== void 0) block.inline_max_chars = options.inlineMaxChars;
   if (options.contentFormat !== void 0) block.content_format = options.contentFormat;
+  if (tier !== void 0) block.tier = tier;
+  if (noCache !== void 0) block.no_cache = noCache;
   if (Object.keys(block).length) body.options = block;
   if (sessionId !== void 0) body.session_id = sessionId;
   return body;
@@ -178,12 +192,17 @@ function buildFetchResponse(interaction) {
   };
 }
 async function fetchUrls(config, url, options) {
-  const body = fetchBody(url, options);
+  const body = fetchBody(url, options, config.fetchDefaults);
   return buildFetchResponse(await request(config, "POST", "/v1/fetch", body, options.signal));
 }
 
 // src/methods/search.ts
 var MIN_SCHEMA_VERSION = 2;
+function providersRefusal(include, includeFromCall, excludeFromCall) {
+  const where = (half, env, fromCall) => fromCall ? `the ${half} search() option` : `the client's ${half} or ${env}`;
+  const names = include.join(", ");
+  return `providersExclude removes every provider in providersInclude (${names}), so no provider is left and no search was sent. Remove ${names} from providersInclude (set by ${where("providersInclude", "TELEM_PROVIDERS_INCLUDE", includeFromCall)}) or from providersExclude (set by ${where("providersExclude", "TELEM_PROVIDERS_EXCLUDE", excludeFromCall)}).`;
+}
 function searchBlock(defaults, options) {
   const fromCallTier = options.tier !== void 0;
   const fromCallFields = options.fields !== void 0;
@@ -197,7 +216,13 @@ function searchBlock(defaults, options) {
   let exclude = options.providersExclude ?? defaults.providersExclude;
   if (include !== void 0 && exclude !== void 0) {
     const excluded = new Set(exclude);
-    include = include.filter((name) => !excluded.has(name));
+    const kept = include.filter((name) => !excluded.has(name));
+    if (include.length && !kept.length) {
+      throw invalidRequest(
+        providersRefusal(include, options.providersInclude !== void 0, options.providersExclude !== void 0)
+      );
+    }
+    include = kept;
     exclude = void 0;
   }
   const includeFullContent = options.includeFullContent ?? defaults.includeFullContent;
@@ -307,7 +332,8 @@ function providerRun(run) {
     related: envelope.related ?? null,
     verticals: envelope.verticals ?? null,
     usage: envelope.usage ?? null,
-    warnings: asArray(envelope.warnings)
+    warnings: asArray(envelope.warnings),
+    sameStory: isObject(envelope.same_story) ? envelope.same_story : null
   };
 }
 function buildSearchResponse(interaction) {
@@ -331,9 +357,25 @@ async function search(config, query, options) {
 }
 
 // src/methods/monitors.ts
+function agentStateFrom(data) {
+  return {
+    engine: String(data.engine ?? ""),
+    status: String(data.status ?? ""),
+    needsAttention: data.needs_attention === true,
+    planVersion: typeof data.plan_version === "number" ? data.plan_version : null,
+    nextRunAt: typeof data.next_run_at === "string" ? data.next_run_at : null,
+    watermark: Number(data.watermark ?? 0),
+    // No compile job yet is null, not an object of empty strings.
+    compile: isObject(data.compile) ? {
+      jobId: String(data.compile.job_id ?? ""),
+      status: String(data.compile.status ?? ""),
+      error: typeof data.compile.error === "string" ? data.compile.error : null
+    } : null
+  };
+}
 function monitorFrom(body) {
   const data = asObject(body);
-  return {
+  const monitor = {
     id: String(data.id ?? ""),
     query: data.query ?? "",
     frequency: data.frequency ?? "",
@@ -346,12 +388,85 @@ function monitorFrom(body) {
     webhookSecret: data.webhook_secret ?? null,
     raw: data
   };
+  if (data.agent_state !== void 0) {
+    monitor.agentState = isObject(data.agent_state) ? agentStateFrom(data.agent_state) : null;
+  }
+  return monitor;
+}
+function agentDocumentFrom(body) {
+  const data = asObject(body);
+  const document = { raw: data };
+  if (typeof data.status === "string") document.status = data.status;
+  if (typeof data.query === "string") document.query = data.query;
+  if (typeof data.frequency === "string") document.frequency = data.frequency;
+  if (typeof data.spec_version === "number") document.specVersion = data.spec_version;
+  if (data.budget !== void 0) document.budget = isObject(data.budget) ? data.budget : null;
+  if (typeof data.spend_usd === "number") document.spendUsd = data.spend_usd;
+  return document;
+}
+function changeRecordFrom(entry) {
+  const subject = asObject(entry.subject);
+  return {
+    seq: Number(entry.seq ?? 0),
+    type: String(entry.type ?? ""),
+    kind: String(entry.kind ?? ""),
+    monitorId: String(entry.monitor_id ?? ""),
+    subject: {
+      entityId: typeof subject.entity_id === "string" ? subject.entity_id : null,
+      name: typeof subject.name === "string" ? subject.name : null
+    },
+    // The values depend on the kind (an object, a status string, nothing): as sent.
+    before: entry.before ?? null,
+    after: entry.after ?? null,
+    factIds: asArray(entry.fact_ids).map(String),
+    at: String(entry.at ?? ""),
+    raw: entry
+  };
+}
+function changesPageFrom(body) {
+  const data = asObject(body);
+  return {
+    changes: asArray(data.changes).filter(isObject).map(changeRecordFrom),
+    nextCursor: Number(data.next_cursor ?? 0),
+    watermark: Number(data.watermark ?? 0)
+  };
+}
+function listQuery(options) {
+  const params = new URLSearchParams();
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  if (options.cursor !== void 0) params.set("cursor", options.cursor);
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+function sinceParam(since) {
+  if (typeof since === "string") return since;
+  if (Number.isNaN(since.getTime())) throw invalidRequest("since is not a valid date");
+  return since.toISOString();
+}
+function changesQuery(options) {
+  const params = new URLSearchParams();
+  if (options.cursor !== void 0) params.set("cursor", String(options.cursor));
+  if (options.since !== void 0) params.set("since", sinceParam(options.since));
+  if (options.kinds !== void 0) params.set("kinds", options.kinds.join(","));
+  if (options.limit !== void 0) params.set("limit", String(options.limit));
+  const query = params.toString();
+  return query ? `?${query}` : "";
 }
 function createMonitors(config) {
   const path = (monitorId, suffix = "") => {
     if (!monitorId || /^\.+$/.test(monitorId)) throw invalidRequest("a monitor id is required");
     return `/v1/monitors/${encodeURIComponent(monitorId)}${suffix}`;
   };
+  const listPage = async (options = {}) => {
+    const route = `/v1/monitors${listQuery(options)}`;
+    const data = asObject(await request(config, "GET", route, void 0, options.signal));
+    const nextCursor = typeof data.next_cursor === "string" ? data.next_cursor : null;
+    return { monitors: asArray(data.monitors).map(monitorFrom), nextCursor };
+  };
+  const changes = async (monitorId, options = {}) => {
+    const route = `${path(monitorId, "/agent/changes")}${changesQuery(options)}`;
+    return changesPageFrom(await request(config, "GET", route, void 0, options.signal));
+  };
   return {
     /** Create a monitor. Telem runs `query` on the schedule. */
     async create(query, options = {}) {
@@ -365,15 +480,25 @@ function createMonitors(config) {
       if (options.metadata !== void 0) body.metadata = options.metadata;
       if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
       if (options.ttl !== void 0) body.ttl = options.ttl;
-      const data = await request(config, "POST", "/v1/monitors", body, options.signal, "rate_limit");
+      if (options.agent !== void 0) body.agent = options.agent;
+      const data = await request(config, "POST", "/v1/monitors", body, options.signal, "rate_limit").catch(
+        (error) => {
+          if (error instanceof TimeoutError) {
+            throw new TimeoutError(
+              `${error.message}. The monitor may exist: list monitors before you create it again.`,
+              error.cause
+            );
+          }
+          throw error;
+        }
+      );
       return monitorFrom(data);
     },
-    /** List your monitors, newest first (server default 50, maximum 200). */
+    /** List your monitors, newest first. `listPage` also gives the next cursor. */
     async list(options = {}) {
-      const query = options.limit === void 0 ? "" : `?limit=${options.limit}`;
-      const body = await request(config, "GET", `/v1/monitors${query}`, void 0, options.signal);
-      return asArray(asObject(body).monitors).map(monitorFrom);
+      return (await listPage(options)).monitors;
     },
+    listPage,
     /** Get one monitor. */
     async get(monitorId, options = {}) {
       return monitorFrom(await request(config, "GET", path(monitorId), void 0, options.signal));
@@ -383,7 +508,7 @@ function createMonitors(config) {
       const body = {};
       if (options.status !== void 0) body.status = options.status;
       if (options.frequency !== void 0) body.frequency = options.frequency;
-      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl;
+      if (options.webhookUrl !== void 0) body.webhook_url = options.webhookUrl || null;
       const route = path(monitorId);
       return monitorFrom(await request(config, "PATCH", route, body, options.signal));
     },
@@ -399,6 +524,23 @@ function createMonitors(config) {
     /** Delete a monitor. A repeat deletes what a failed delete left. */
     async delete(monitorId, options = {}) {
       await request(config, "DELETE", path(monitorId), void 0, options.signal);
+    },
+    /** Read the monitor agent's document. A monitor without an agent answers 404. */
+    async agent(monitorId, options = {}) {
+      const route = path(monitorId, "/agent");
+      return agentDocumentFrom(await request(config, "GET", route, void 0, options.signal));
+    },
+    /** One page of the agent's changes. Keep `nextCursor` and pass it back as `cursor`. */
+    changes,
+    /** Every change after `cursor`, page by page, until you are caught up. */
+    async *iterateChanges(monitorId, options = {}) {
+      let cursor = options.cursor ?? 0;
+      for (; ; ) {
+        const page = await changes(monitorId, { cursor, signal: options.signal });
+        for (const change of page.changes) yield change;
+        if (!page.changes.length || page.nextCursor <= cursor || page.nextCursor >= page.watermark) return;
+        cursor = page.nextCursor;
+      }
     }
   };
 }
@@ -431,7 +573,8 @@ async function providers(config) {
     method: entry.method ?? null,
     url: entry.url ?? null,
     normalized: entry.normalized ?? false,
-    tiers: asArray(entry.tiers)
+    tiers: asArray(entry.tiers),
+    autoRouted: entry.auto_routed ?? null
   }));
 }
 
@@ -500,7 +643,8 @@ var Telem = class {
   maxRetries;
   /** The session read surface: `list` and `results(id)`. */
   sessions;
-  /** Monitors: `create`, `list`, `get`, `update`, `poll`, `delete`. */
+  /** Monitors: `create`, `list`, `listPage`, `get`, `update`, `poll`, `delete`, and the
+   *  agent reads `agent`, `changes` and `iterateChanges`. */
   monitors;
   #config;
   /**

package/dist/vercel/index.js

@@ -9,7 +9,7 @@ import {
   toolMarker,
   windowAnchor,
   withTrajectory
-} from "../chunk-DKTEG7EY.js";
+} from "../chunk-SQ3ZZA72.js";
 
 // src/vercel/index.ts
 import { jsonSchema } from "ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemai/sdk",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",