@telemai/sdk 0.3.3 → 0.5.0

package/README.md

@@ -207,18 +207,35 @@ results of each search step.
 
 ## Monitors
 
-A monitor runs a query on a schedule. Poll it to get the results that are new since
-your last poll. `poll` returns a `SearchResponse`:
+A monitor runs a query on a schedule, and its agent checks every result against the
+query and keeps the ones that match. A monitor has the agent unless you create it with
+`agent: false`, and a monitor with the agent needs a `ttl`, at most `"30d"`: without
+one, `create` throws a `TelemError` with the code `invalid_request`.
 
 ```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)
+const monitor = await telem.monitors.create("Nvidia files a new 8-K with the SEC", { frequency: "1h", ttl: "30d" })
+console.log(monitor.agentState?.status) // what its agent does: compiling, then ready
+for await (const change of telem.monitors.iterateChanges(monitor.id)) {
+  console.log(change.seq, change.kind, change.subject.name)
+}
+const agent = await telem.monitors.agent(monitor.id)
 await telem.monitors.update(monitor.id, { status: "paused" })
+await telem.monitors.update(monitor.id, { ttl: "30d" }) // renew: it ends 30 days from now
 await telem.monitors.delete(monitor.id)
 ```
 
-`telem.monitors` also has `get` and `list`. See [Monitors](https://docs.telem.ai/resources/monitors/)
-for the fields and the errors.
+`iterateChanges` reads what the agent 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; when the agent did not start, the
+create's `monitor.agentNote` says why. Read `iterateChanges` with `for await`.
+
+`telem.monitors` also has `get` and `list`. `poll` is deprecated and warns once:
+read the agent's changes with `iterateChanges` instead.
+See [Monitors](https://docs.telem.ai/resources/monitors/) for the fields, the errors and
+the older reads.
 
 ## Vercel AI SDK
 
@@ -369,7 +386,7 @@ try {
 
 | Situation | Result |
 |---|---|
-| Bad input (empty query, empty URL list) | `TelemError`, `code: "invalid_request"`, nothing sent |
+| Bad input (empty query, empty URL list, a monitor with an agent and no `ttl`) | `TelemError`, `code: "invalid_request"`, nothing sent |
 | Network failure | `TelemError`, `code: "connection_error"`, after the retries |
 | 5xx or 429 | Retried with backoff (`Retry-After` applies), then `TelemError` with the status |
 | Other 4xx | `TelemError` with the status and the code from the server, not retried |

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.3";
+var VERSION = "0.5.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) {
@@ -232,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
@@ -698,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) {
@@ -722,9 +726,33 @@ async function search(config, query, options) {
 }
 
 // src/methods/monitors.ts
+var NEEDS_TTL = 'A monitor with an agent must end: pass ttl, such as ttl: "30d" (at most 30 days), or agent: false for a monitor without an agent.';
+var POLL_DEPRECATED = "@telemai/sdk: monitors.poll() is deprecated: read what the monitor agent finds with monitors.iterateChanges() or monitors.changes().";
+var pollWarned = false;
+function warnPollDeprecated() {
+  if (pollWarned) return;
+  pollWarned = true;
+  console.warn(POLL_DEPRECATED);
+}
+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 ?? "",
@@ -735,51 +763,141 @@ function monitorFrom(body) {
     expiresAt: data.expires_at ?? null,
     webhookUrl: data.webhook_url ?? null,
     webhookSecret: data.webhook_secret ?? null,
+    agentNote: typeof data.agent_note === "string" ? data.agent_note : 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 = {}) {
+    /** Create a monitor. Telem runs `query` on the schedule, and its agent keeps what matches. */
+    async create(query, options) {
+      const given = options ?? {};
+      const agent = given.agent == null ? true : Boolean(given.agent);
+      if (agent && !given.ttl) throw invalidRequest(NEEDS_TTL);
       const monitorOptions = {};
-      if (options.frequency !== void 0) monitorOptions.frequency = options.frequency;
-      if (options.includeDomains !== void 0) {
-        monitorOptions.include_domains = options.includeDomains;
+      if (given.frequency !== void 0) monitorOptions.frequency = given.frequency;
+      if (given.includeDomains !== void 0) {
+        monitorOptions.include_domains = given.includeDomains;
       }
-      if (options.search !== void 0) monitorOptions.search = searchBlock({}, options.search);
+      if (given.search !== void 0) monitorOptions.search = searchBlock({}, given.search);
       const body = { query, options: monitorOptions };
-      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 (given.metadata !== void 0) body.metadata = given.metadata;
+      if (given.webhookUrl !== void 0) body.webhook_url = given.webhookUrl;
+      if (given.ttl !== void 0) body.ttl = given.ttl;
+      body.agent = agent;
+      const data = await request(config, "POST", "/v1/monitors", body, given.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));
     },
-    /** Pause, resume or change a monitor. Only the fields given are sent. */
+    /** Pause, resume, renew or change a monitor. Only the fields given are sent. */
     async update(monitorId, options) {
       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.ttl !== void 0) body.ttl = options.ttl;
+      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));
     },
-    /** Get the results that are new since the last poll. */
+    /** Get the monitor's own results that are new since the last poll. Deprecated: it
+     *  warns once per process. */
     async poll(monitorId, options = {}) {
+      warnPollDeprecated();
       const body = {};
       if (options.session !== void 0) body.session_id = options.session;
       if (options.metadata !== void 0) body.metadata = options.metadata;
@@ -790,6 +908,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;
+      }
     }
   };
 }
@@ -892,7 +1027,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` and `delete`, the agent reads
+   *  `agent`, `changes` and `iterateChanges`, and the deprecated `poll`. */
   monitors;
   #config;
   /**

package/dist/index.d.cts

@@ -157,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 = {
@@ -207,7 +209,7 @@ type ProviderInfo = {
     url: string | null;
     normalized: boolean;
     tiers: string[];
-    /** Whether auto-routing can pick it for a ranked topic; `null` from a router that does not say. */
+    /** Whether auto-routing can pick it; `null` from a router that does not say. */
     autoRouted: boolean | null;
 };
 /** One session as `sessions.list` reports it. */
@@ -236,34 +238,55 @@ type SessionsResource = {
 };
 /** The search options a monitor can run on its schedule (`MonitorCreateOptions.search`). */
 type MonitorSearchOptions = Pick<SearchOptions, "tier" | "numResults">;
-/** Options for `monitors.create`. */
-type MonitorCreateOptions = {
+/** The options of `monitors.create` that a monitor takes with the agent or without. */
+type MonitorCreateCommonOptions = {
     /** `"1h"`, `"6h"`, `"12h"`, `"1d"` or `"7d"`. If you leave it out, the monitor runs once a day. */
     frequency?: string;
     /** Also run a web search for the query on the schedule, with these options. `{}`
-     *  uses the defaults. Client search defaults do not apply. */
+     *  uses the defaults. Client search defaults do not apply. It adds to what a poll returns. */
     search?: MonitorSearchOptions;
-    /** Only results from these sites and their subdomains, such as `["sec.gov"]`,
-     *  from every source of the monitor. */
+    /** Only results from these sites and their subdomains, such as `["sec.gov"]`, in what
+     *  a poll returns. */
     includeDomains?: string[];
-    /** Request metadata (query lineage keys), sent as given. */
+    /** Query lineage keys, sent as given. They choose the session that records the polls of
+     *  the monitor. */
     metadata?: Json;
     /** An `https` URL that receives the new results. */
     webhookUrl?: string;
-    /** Delete the monitor after this long, such as `"12h"` or `"7d"` (at most `"30d"`). Without it, the monitor never expires. */
-    ttl?: string;
     signal?: AbortSignal;
 };
+/** Options for `monitors.create`. A monitor has the agent unless `agent` is `false`,
+ *  and a monitor with the agent must end: then `ttl` is required. */
+type MonitorCreateOptions = MonitorCreateCommonOptions & ({
+    /** `false` creates a monitor without an agent, which you read with the deprecated
+     *  `monitors.poll`. */
+    agent: false;
+    /** End the monitor after this long, such as `"7d"` or `"30d"` (at most `"30d"`).
+     *  Without it, a monitor without an agent never ends. */
+    ttl?: string;
+} | {
+    /** Start the monitor agent with the monitor, the default: it checks every result
+     *  against the query and keeps the ones that match. Read what it keeps with
+     *  `monitors.iterateChanges` or `monitors.changes`. */
+    agent?: true;
+    /** End the monitor after this long, such as `"7d"` or `"30d"` (at most `"30d"`).
+     *  Required with the agent. */
+    ttl: string;
+});
 /** Options for `monitors.update`. Send at least one field. */
 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;
+    /** A new end, this long from now, such as `"30d"` (at most `"30d"`). It renews a monitor
+     *  before it ends; an ended monitor cannot be renewed. */
+    ttl?: string;
     signal?: AbortSignal;
 };
-/** Options for `monitors.poll`. */
+/** Options for `monitors.poll`.
+ *  @deprecated `poll` is deprecated: read the agent with `monitors.iterateChanges`. */
 type MonitorPollOptions = {
     /** Record this poll in another session (default: the monitor's own). */
     session?: string;
@@ -276,33 +299,169 @@ 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;
+    /** Only in the answer to a create: why the monitor agent did not start, or not yet.
+     *  `null` when it started, and in every other answer. */
+    agentNote: string | 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[]>;
+    /** Create a monitor. It has the agent unless `agent` is `false`, and with the agent
+     *  `ttl` is required: a create without it throws a `TelemError` (`invalid_request`)
+     *  before anything is sent. */
+    create(query: string, options: MonitorCreateOptions): Promise<Monitor>;
+    list(options?: MonitorListOptions): Promise<Monitor[]>;
+    listPage(options?: MonitorListOptions): Promise<MonitorPage>;
     get(monitorId: string, options?: {
         signal?: AbortSignal;
     }): Promise<Monitor>;
     update(monitorId: string, options: MonitorUpdateOptions): Promise<Monitor>;
+    /** Get the monitor's own results that are new since the last poll.
+     *  @deprecated Read what the monitor agent finds with `iterateChanges` or `changes`.
+     *  A poll still works, and warns once per process with `console.warn`. */
     poll(monitorId: string, options?: MonitorPollOptions): Promise<SearchResponse>;
     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>;
 };
 
 /**
@@ -446,7 +605,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` and `delete`, the agent reads
+     *  `agent`, `changes` and `iterateChanges`, and the deprecated `poll`. */
     readonly monitors: MonitorsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
@@ -479,4 +639,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

@@ -157,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 = {
@@ -207,7 +209,7 @@ type ProviderInfo = {
     url: string | null;
     normalized: boolean;
     tiers: string[];
-    /** Whether auto-routing can pick it for a ranked topic; `null` from a router that does not say. */
+    /** Whether auto-routing can pick it; `null` from a router that does not say. */
     autoRouted: boolean | null;
 };
 /** One session as `sessions.list` reports it. */
@@ -236,34 +238,55 @@ type SessionsResource = {
 };
 /** The search options a monitor can run on its schedule (`MonitorCreateOptions.search`). */
 type MonitorSearchOptions = Pick<SearchOptions, "tier" | "numResults">;
-/** Options for `monitors.create`. */
-type MonitorCreateOptions = {
+/** The options of `monitors.create` that a monitor takes with the agent or without. */
+type MonitorCreateCommonOptions = {
     /** `"1h"`, `"6h"`, `"12h"`, `"1d"` or `"7d"`. If you leave it out, the monitor runs once a day. */
     frequency?: string;
     /** Also run a web search for the query on the schedule, with these options. `{}`
-     *  uses the defaults. Client search defaults do not apply. */
+     *  uses the defaults. Client search defaults do not apply. It adds to what a poll returns. */
     search?: MonitorSearchOptions;
-    /** Only results from these sites and their subdomains, such as `["sec.gov"]`,
-     *  from every source of the monitor. */
+    /** Only results from these sites and their subdomains, such as `["sec.gov"]`, in what
+     *  a poll returns. */
     includeDomains?: string[];
-    /** Request metadata (query lineage keys), sent as given. */
+    /** Query lineage keys, sent as given. They choose the session that records the polls of
+     *  the monitor. */
     metadata?: Json;
     /** An `https` URL that receives the new results. */
     webhookUrl?: string;
-    /** Delete the monitor after this long, such as `"12h"` or `"7d"` (at most `"30d"`). Without it, the monitor never expires. */
-    ttl?: string;
     signal?: AbortSignal;
 };
+/** Options for `monitors.create`. A monitor has the agent unless `agent` is `false`,
+ *  and a monitor with the agent must end: then `ttl` is required. */
+type MonitorCreateOptions = MonitorCreateCommonOptions & ({
+    /** `false` creates a monitor without an agent, which you read with the deprecated
+     *  `monitors.poll`. */
+    agent: false;
+    /** End the monitor after this long, such as `"7d"` or `"30d"` (at most `"30d"`).
+     *  Without it, a monitor without an agent never ends. */
+    ttl?: string;
+} | {
+    /** Start the monitor agent with the monitor, the default: it checks every result
+     *  against the query and keeps the ones that match. Read what it keeps with
+     *  `monitors.iterateChanges` or `monitors.changes`. */
+    agent?: true;
+    /** End the monitor after this long, such as `"7d"` or `"30d"` (at most `"30d"`).
+     *  Required with the agent. */
+    ttl: string;
+});
 /** Options for `monitors.update`. Send at least one field. */
 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;
+    /** A new end, this long from now, such as `"30d"` (at most `"30d"`). It renews a monitor
+     *  before it ends; an ended monitor cannot be renewed. */
+    ttl?: string;
     signal?: AbortSignal;
 };
-/** Options for `monitors.poll`. */
+/** Options for `monitors.poll`.
+ *  @deprecated `poll` is deprecated: read the agent with `monitors.iterateChanges`. */
 type MonitorPollOptions = {
     /** Record this poll in another session (default: the monitor's own). */
     session?: string;
@@ -276,33 +299,169 @@ 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;
+    /** Only in the answer to a create: why the monitor agent did not start, or not yet.
+     *  `null` when it started, and in every other answer. */
+    agentNote: string | 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[]>;
+    /** Create a monitor. It has the agent unless `agent` is `false`, and with the agent
+     *  `ttl` is required: a create without it throws a `TelemError` (`invalid_request`)
+     *  before anything is sent. */
+    create(query: string, options: MonitorCreateOptions): Promise<Monitor>;
+    list(options?: MonitorListOptions): Promise<Monitor[]>;
+    listPage(options?: MonitorListOptions): Promise<MonitorPage>;
     get(monitorId: string, options?: {
         signal?: AbortSignal;
     }): Promise<Monitor>;
     update(monitorId: string, options: MonitorUpdateOptions): Promise<Monitor>;
+    /** Get the monitor's own results that are new since the last poll.
+     *  @deprecated Read what the monitor agent finds with `iterateChanges` or `changes`.
+     *  A poll still works, and warns once per process with `console.warn`. */
     poll(monitorId: string, options?: MonitorPollOptions): Promise<SearchResponse>;
     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>;
 };
 
 /**
@@ -446,7 +605,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` and `delete`, the agent reads
+     *  `agent`, `changes` and `iterateChanges`, and the deprecated `poll`. */
     readonly monitors: MonitorsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset
@@ -479,4 +639,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.3";
+var VERSION = "0.5.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) {
@@ -331,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) {
@@ -355,9 +357,33 @@ async function search(config, query, options) {
 }
 
 // src/methods/monitors.ts
+var NEEDS_TTL = 'A monitor with an agent must end: pass ttl, such as ttl: "30d" (at most 30 days), or agent: false for a monitor without an agent.';
+var POLL_DEPRECATED = "@telemai/sdk: monitors.poll() is deprecated: read what the monitor agent finds with monitors.iterateChanges() or monitors.changes().";
+var pollWarned = false;
+function warnPollDeprecated() {
+  if (pollWarned) return;
+  pollWarned = true;
+  console.warn(POLL_DEPRECATED);
+}
+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 ?? "",
@@ -368,51 +394,141 @@ function monitorFrom(body) {
     expiresAt: data.expires_at ?? null,
     webhookUrl: data.webhook_url ?? null,
     webhookSecret: data.webhook_secret ?? null,
+    agentNote: typeof data.agent_note === "string" ? data.agent_note : 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 = {}) {
+    /** Create a monitor. Telem runs `query` on the schedule, and its agent keeps what matches. */
+    async create(query, options) {
+      const given = options ?? {};
+      const agent = given.agent == null ? true : Boolean(given.agent);
+      if (agent && !given.ttl) throw invalidRequest(NEEDS_TTL);
       const monitorOptions = {};
-      if (options.frequency !== void 0) monitorOptions.frequency = options.frequency;
-      if (options.includeDomains !== void 0) {
-        monitorOptions.include_domains = options.includeDomains;
+      if (given.frequency !== void 0) monitorOptions.frequency = given.frequency;
+      if (given.includeDomains !== void 0) {
+        monitorOptions.include_domains = given.includeDomains;
       }
-      if (options.search !== void 0) monitorOptions.search = searchBlock({}, options.search);
+      if (given.search !== void 0) monitorOptions.search = searchBlock({}, given.search);
       const body = { query, options: monitorOptions };
-      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 (given.metadata !== void 0) body.metadata = given.metadata;
+      if (given.webhookUrl !== void 0) body.webhook_url = given.webhookUrl;
+      if (given.ttl !== void 0) body.ttl = given.ttl;
+      body.agent = agent;
+      const data = await request(config, "POST", "/v1/monitors", body, given.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));
     },
-    /** Pause, resume or change a monitor. Only the fields given are sent. */
+    /** Pause, resume, renew or change a monitor. Only the fields given are sent. */
     async update(monitorId, options) {
       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.ttl !== void 0) body.ttl = options.ttl;
+      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));
     },
-    /** Get the results that are new since the last poll. */
+    /** Get the monitor's own results that are new since the last poll. Deprecated: it
+     *  warns once per process. */
     async poll(monitorId, options = {}) {
+      warnPollDeprecated();
       const body = {};
       if (options.session !== void 0) body.session_id = options.session;
       if (options.metadata !== void 0) body.metadata = options.metadata;
@@ -423,6 +539,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;
+      }
     }
   };
 }
@@ -525,7 +658,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` and `delete`, the agent reads
+   *  `agent`, `changes` and `iterateChanges`, and the deprecated `poll`. */
   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.3",
+  "version": "0.5.0",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",