@telemai/sdk 0.3.3 → 0.4.0

package/README.md

@@ -213,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.3";
+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) {
@@ -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,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 ?? "",
@@ -737,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 = {}) {
@@ -756,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));
@@ -774,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));
     },
@@ -790,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;
+      }
     }
   };
 }
@@ -892,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

@@ -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. */
@@ -252,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. */
@@ -259,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;
 };
@@ -276,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>;
@@ -303,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>;
 };
 
 /**
@@ -446,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
@@ -479,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

@@ -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. */
@@ -252,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. */
@@ -259,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;
 };
@@ -276,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>;
@@ -303,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>;
 };
 
 /**
@@ -446,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
@@ -479,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.3";
+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) {
@@ -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,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 ?? "",
@@ -370,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 = {}) {
@@ -389,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));
@@ -407,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));
     },
@@ -423,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;
+      }
     }
   };
 }
@@ -525,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.3",
+  "version": "0.4.0",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",