@odla-ai/cli 0.25.8 → 0.25.10

package/README.md

@@ -195,6 +195,8 @@ npx odla-ai provision --email owner@example.com --write-dev-vars --push-secrets
 npx odla-ai smoke --env dev
 npx odla-ai agent jobs --env dev --state dead_letter --json
 npx odla-ai agent retry <job-id> --env dev --json
+npx odla-ai discuss watch <topic-id> --jsonl
+npx odla-ai discuss watch <topic-id> --cursor <saved-cursor> --jsonl
 npx odla-ai secrets push --env dev
 npx odla-ai secrets set clerk_webhook_secret --env dev --stdin
 npx odla-ai secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
@@ -225,6 +227,25 @@ currently running work. Successful receipts are retained for seven days (and
 bounded to the newest 1,000 per tenant); unresolved dead letters remain until
 an operator requeues them.
 
+`discuss watch` waits at a server-issued snapshot boundary instead of comparing
+client clocks or repeatedly reading a topic's oldest 200 posts. It is unbounded
+unless `--timeout <seconds>` is supplied. `--jsonl` emits versioned
+`checkpoint`, `event`, `heartbeat`, and degraded `status` records; persist the
+latest cursor only after consuming its record and pass it back with `--cursor`
+after a restart. Event IDs are stable for at-least-once deduplication. Transient
+429/5xx/network failures retry with bounded exponential backoff without
+advancing the cursor. A restore or truncated history exits 3 and emits an
+explicit replacement checkpoint; an explicit timeout exits 75, and an
+exhausted remote retry exits 6.
+
+`discuss read <topic> --json` follows the server's bounded forward post pages
+before emitting one complete document. A long-lived agent can therefore watch
+an event and then read the full topic rather than receiving an apparently
+successful response capped to its oldest 200 posts. Use `--limit <n>
+--offset <n>` to request one bounded page instead; complete reads fail closed
+after 10,000 posts or three continuously changing scans rather than consuming
+memory forever or claiming an inconsistent result.
+
 `code connect` is the first-party personal Code terminal runtime. Run the exact
 command copied from **Studio → Code → Terminal** while your shell is in the
 local Git checkout. `--platform`, `--app-id`, and `--env` make the requested

package/dist/bin.cjs

@@ -4608,13 +4608,13 @@ async function createConversionRegistry(config) {
     policies.set(policy.conversionId, Object.freeze(policy));
   }
   const outputCounts = /* @__PURE__ */ new Map();
-  const get2 = (id, kind) => {
+  const get = (id, kind) => {
     const policy = policies.get(id);
     if (!policy || policy.output.kind !== kind) throw new CamelError("conversion_rejected", "Conversion policy is missing or has the wrong output kind.");
     return policy;
   };
   const checked = (source, id, kind) => {
-    const policy = get2(id, kind);
+    const policy = get(id, kind);
     if (utf8Length(source.value) > policy.maximumSourceBytes) throw new CamelError("limit_exceeded", "Unsafe conversion input exceeds its byte bound.");
     return policy;
   };
@@ -6563,12 +6563,12 @@ Usage:
   odla-ai pm handoff --app <id> [--json]
   odla-ai discuss groups [--json]
   odla-ai discuss list [--app <id>] [--q <text>] [--state open|resolved|all] [--json]
-  odla-ai discuss read <topic> [--json]
+  odla-ai discuss read <topic> [--limit <n> --offset <n>] [--json]
   odla-ai discuss post --app <id> --subject "..." --body "..." [--markup "... @[Label](kind/id)"] [--mutation-id <id>]
   odla-ai discuss reply <topic> --body "..." [--markup "..."] [--mutation-id <id>]
   odla-ai discuss resolve <topic> [--reopen] [--mutation-id <id>]
   odla-ai discuss who --q <text> [--app <id>] [--kinds user,pm:task] [--json]
-  odla-ai discuss watch [<topic>] [--by <authorId>] [--self <authorId>] [--interval <s>] [--timeout <s>] [--json]
+  odla-ai discuss watch [<topic>] [--cursor <cursor>] [--by <authorId>] [--self <authorId>] [--interval <s>] [--timeout <s>] [--json|--jsonl]
   odla-ai agent jobs [--env dev] [--state pending|running|succeeded|dead_letter] [--limit 50] [--email <email>] [--json]
   odla-ai agent retry <job-id> [--env dev] [--email <email>] [--json]
   odla-ai o11y status [--app <id>] [--env prod] [--minutes 60] [--json]
@@ -7409,22 +7409,59 @@ async function discussList(ctx, parsed) {
     }
   });
 }
-async function discussRead(ctx, id) {
-  const result = await request(
-    ctx,
-    "GET",
-    `/topics/${encodeURIComponent(id)}`
-  );
-  emit(ctx, result, () => {
-    ctx.out.log(`${result.topic.subject}  [${state(result.topic)}]  ${result.topic.appId ?? ""}`);
-    for (const post of result.posts) {
-      const who = post.authorKind === "bot" ? `${post.authorId} (agent)` : post.authorId;
-      ctx.out.log(`
-\u2014 ${who}`);
-      ctx.out.log(bodyWithRefs(post));
-      for (const file of post.attachments ?? []) ctx.out.log(`  [attachment] ${file.name} (${file.size} bytes)`);
+async function discussRead(ctx, id, parsed) {
+  const requestedLimit = stringOpt(parsed.options.limit);
+  const requestedOffset = stringOpt(parsed.options.offset);
+  if (requestedLimit !== void 0 || requestedOffset !== void 0) {
+    const query = new URLSearchParams({
+      limit: requestedLimit ?? "200",
+      offset: requestedOffset ?? "0"
+    });
+    const page = await request(ctx, "GET", `/topics/${encodeURIComponent(id)}?${query}`);
+    emit(ctx, page, () => renderRead(ctx, page.topic, page.posts));
+    return;
+  }
+  for (let scan = 0; scan < 3; scan++) {
+    const posts = /* @__PURE__ */ new Map();
+    let topic = null;
+    let offset = 0;
+    for (; ; ) {
+      const page = await request(
+        ctx,
+        "GET",
+        `/topics/${encodeURIComponent(id)}?limit=200&offset=${offset}`
+      );
+      topic = page.topic;
+      for (const post of page.posts) posts.set(post.id, post);
+      if (posts.size > 1e4) throw new Error("discuss read failed: conversation exceeds 10000 posts");
+      if (!page.page?.hasMore) break;
+      if (page.page.nextOffset === null || page.page.nextOffset <= offset) {
+        throw new Error("discuss read failed: registry returned a non-advancing post page");
+      }
+      offset = page.page.nextOffset;
     }
-  });
+    const ordered = [...posts.values()].sort(
+      (a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+    );
+    const expected = Number.isInteger(topic.replyCount) ? topic.replyCount + 1 : ordered.length;
+    if (ordered.length === expected) {
+      const result = { topic, posts: ordered };
+      emit(ctx, result, () => renderRead(ctx, result.topic, result.posts));
+      return;
+    }
+    if (offset === 0) throw new Error("discuss read failed: registry did not provide forward post pages");
+  }
+  throw new Error("discuss read failed: conversation changed during every complete-read attempt");
+}
+function renderRead(ctx, topic, posts) {
+  ctx.out.log(`${topic.subject}  [${state(topic)}]  ${topic.appId ?? ""}`);
+  for (const post of posts) {
+    const who = post.authorKind === "bot" ? `${post.authorId} (agent)` : post.authorId;
+    ctx.out.log(`
+\u2014 ${who}`);
+    ctx.out.log(bodyWithRefs(post));
+    for (const file of post.attachments ?? []) ctx.out.log(`  [attachment] ${file.name} (${file.size} bytes)`);
+  }
 }
 async function discussPost(ctx, parsed) {
   const appId = stringOpt(parsed.options.app);
@@ -7473,61 +7510,214 @@ async function discussWho(ctx, parsed) {
   });
 }
 
+// src/discuss-watch-http.ts
+var WatchRequestError = class extends Error {
+  constructor(message2, retryable, status, code) {
+    super(message2);
+    this.retryable = retryable;
+    this.status = status;
+    this.code = code;
+    this.name = "WatchRequestError";
+  }
+  retryable;
+  status;
+  code;
+};
+var WatchCheckpointError = class extends Error {
+  constructor(cursor, streamId) {
+    super("discussion cursor requires a new checkpoint");
+    this.cursor = cursor;
+    this.streamId = streamId;
+    this.name = "WatchCheckpointError";
+  }
+  cursor;
+  streamId;
+  code = "checkpoint_required";
+};
+var WatchRemoteError = class extends Error {
+  constructor(cursor, cause) {
+    super("discussion watch dependency remained unavailable", { cause });
+    this.cursor = cursor;
+    this.name = "WatchRemoteError";
+  }
+  cursor;
+  code = "remote_unavailable";
+};
+var WatchTimeoutError = class extends Error {
+  constructor(cursor) {
+    super("nothing new before the timeout");
+    this.cursor = cursor;
+    this.name = "WatchTimeoutError";
+  }
+  cursor;
+  code = "watch_timeout";
+};
+function requestPath(topicId, app, cursor) {
+  const params = new URLSearchParams();
+  if (topicId) params.set("topic", topicId);
+  if (app) params.set("app", app);
+  if (cursor) params.set("cursor", cursor);
+  return `/watch?${params}`;
+}
+async function getWatchPage(ctx, path) {
+  let res;
+  try {
+    res = await ctx.doFetch(`${ctx.platformUrl}/registry/discuss${path}`, {
+      headers: { authorization: `Bearer ${ctx.token}` }
+    });
+  } catch (error) {
+    throw new WatchRequestError(
+      `discuss watch request failed: ${error instanceof Error ? error.message : String(error)}`,
+      true
+    );
+  }
+  const data = await res.json().catch(() => ({}));
+  if (res.status === 409 && data.code === "checkpoint_required") {
+    throw new WatchCheckpointError(data.cursor, data.streamId);
+  }
+  if (!res.ok) {
+    throw new WatchRequestError(
+      `discuss watch failed: ${data.error ?? `registry returned ${res.status}`}`,
+      res.status === 429 || res.status >= 500,
+      res.status,
+      data.code ?? (res.status === 401 || res.status === 403 ? "auth_failed" : void 0)
+    );
+  }
+  return data;
+}
+
 // src/discuss-watch.ts
 var DEFAULT_INTERVAL_MS = 15e3;
-var DEFAULT_TIMEOUT_MS = 15 * 6e4;
+var MAX_CONSECUTIVE_FAILURES = 5;
+var MAX_BACKOFF_MS = 3e4;
 function numberOpt2(parsed, flag, fallback) {
   const raw = stringOpt(parsed.options[flag]);
   const value = raw == null ? NaN : Number(raw);
   return Number.isFinite(value) && value > 0 ? value : fallback;
 }
-async function get(ctx, path) {
-  const res = await ctx.doFetch(`${ctx.platformUrl}/registry/discuss${path}`, {
-    headers: { authorization: `Bearer ${ctx.token}` }
-  });
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(`discuss watch failed: ${data.error ?? `registry returned ${res.status}`}`);
-  return data;
+function jsonl(ctx, parsed, value) {
+  if (parsed.options.jsonl === true) ctx.out.log(JSON.stringify({ v: 1, ...value }));
 }
 async function discussWatch(ctx, topicId, parsed) {
+  if (ctx.json && parsed.options.jsonl === true) throw new Error("--json and --jsonl cannot be combined");
   const sleep = ctx.sleep ?? ((ms) => new Promise((resolve11) => setTimeout(resolve11, ms)));
   const now = ctx.now ?? Date.now;
-  const intervalMs = numberOpt2(parsed, "interval", DEFAULT_INTERVAL_MS / 1e3) * 1e3;
-  const timeoutMs = numberOpt2(parsed, "timeout", DEFAULT_TIMEOUT_MS / 1e3) * 1e3;
+  const intervalMs = (numberOpt2(parsed, "interval", DEFAULT_INTERVAL_MS / 1e3) ?? DEFAULT_INTERVAL_MS / 1e3) * 1e3;
+  const timeoutSeconds = numberOpt2(parsed, "timeout");
+  const deadline = timeoutSeconds === void 0 ? void 0 : now() + timeoutSeconds * 1e3;
   const by = stringOpt(parsed.options.by);
   const self = stringOpt(parsed.options.self);
-  const deadline = now() + timeoutMs;
-  const fresh = (post) => (!by || post.authorId === by) && (!self || post.authorId !== self);
-  let seen = /* @__PURE__ */ new Set();
-  let since = now();
-  if (topicId) {
-    const first = await get(ctx, `/topics/${encodeURIComponent(topicId)}`);
-    seen = new Set(first.posts.map((post) => post.id));
-  }
+  const app = stringOpt(parsed.options.app);
+  let cursor = stringOpt(parsed.options.cursor);
+  let firstSuccess = true;
+  let consecutiveFailures = 0;
   for (; ; ) {
-    if (topicId) {
-      const { posts } = await get(ctx, `/topics/${encodeURIComponent(topicId)}`);
-      const added = posts.filter((post) => !seen.has(post.id) && fresh(post));
-      if (added.length > 0) return report2(ctx, { found: true, posts: added });
-      for (const post of posts) seen.add(post.id);
-    } else {
-      const app = stringOpt(parsed.options.app);
-      const { topics } = await get(
-        ctx,
-        `/topics?state=all${app ? `&app=${encodeURIComponent(app)}` : ""}`
-      );
-      const active = topics.filter((topic) => topic.lastActivityAt > since);
-      if (active.length > 0) return report2(ctx, { found: true, topics: active });
-      since = now();
+    let page;
+    try {
+      page = await getWatchPage(ctx, requestPath(topicId, app, cursor));
+      consecutiveFailures = 0;
+    } catch (error) {
+      if (!(error instanceof WatchRequestError) || !error.retryable) {
+        if (error instanceof WatchCheckpointError) {
+          jsonl(ctx, parsed, {
+            type: "status",
+            state: "checkpoint_required",
+            retryable: false,
+            ...error.cursor ? { cursor: error.cursor } : {},
+            ...error.streamId ? { streamId: error.streamId } : {}
+          });
+        }
+        throw error;
+      }
+      consecutiveFailures++;
+      jsonl(ctx, parsed, {
+        type: "status",
+        state: "degraded",
+        retryable: true,
+        attempt: consecutiveFailures,
+        ...cursor ? { cursor } : {},
+        ...error.status ? { status: error.status } : {}
+      });
+      if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+        throw new WatchRemoteError(cursor, error);
+      }
+      if (deadline !== void 0 && now() >= deadline) {
+        const result = report2(ctx, parsed, { found: false, cursor: cursor ?? "" });
+        throw new WatchTimeoutError(result.cursor);
+      }
+      const base = Math.min(intervalMs, 1e3);
+      const backoff = Math.min(MAX_BACKOFF_MS, base * 2 ** (consecutiveFailures - 1));
+      await sleep(deadline === void 0 ? backoff : Math.min(backoff, Math.max(0, deadline - now())));
+      continue;
+    }
+    cursor = page.cursor;
+    const baseline = firstSuccess && page.events.length === 0;
+    if (baseline) {
+      jsonl(ctx, parsed, {
+        type: "checkpoint",
+        streamId: page.streamId,
+        cursor,
+        serverTime: page.serverTime
+      });
+    }
+    firstSuccess = false;
+    const matching = page.events.filter((event) => {
+      if (topicId && (event.type !== "message" || event.action !== "created")) return false;
+      return (!by || event.actor.id === by) && (!self || event.actor.id !== self);
+    });
+    for (const event of matching) {
+      jsonl(ctx, parsed, {
+        type: "event",
+        streamId: page.streamId,
+        eventId: event.id,
+        cursor: event.cursor,
+        event
+      });
+    }
+    if (matching.length > 0) {
+      jsonl(ctx, parsed, {
+        type: "checkpoint",
+        streamId: page.streamId,
+        cursor,
+        serverTime: page.serverTime
+      });
+      const posts = topicId ? matching.filter((event) => event.type === "message").map((event) => event.payload) : void 0;
+      const topics = topicId ? void 0 : matching.filter((event) => event.type === "activity").map((event) => event.payload);
+      return report2(ctx, parsed, {
+        found: true,
+        cursor,
+        events: matching,
+        ...posts && posts.length > 0 ? { posts } : {},
+        ...topics && topics.length > 0 ? { topics } : {}
+      });
     }
-    if (now() >= deadline) return report2(ctx, { found: false });
-    await sleep(Math.min(intervalMs, Math.max(0, deadline - now())));
+    if (page.events.length > 0) {
+      jsonl(ctx, parsed, {
+        type: "checkpoint",
+        streamId: page.streamId,
+        cursor,
+        serverTime: page.serverTime
+      });
+    } else if (!baseline) {
+      jsonl(ctx, parsed, {
+        type: "heartbeat",
+        streamId: page.streamId,
+        cursor,
+        serverTime: page.serverTime
+      });
+    }
+    if (page.hasMore) continue;
+    if (deadline !== void 0 && now() >= deadline) {
+      return report2(ctx, parsed, { found: false, cursor });
+    }
+    const wait2 = deadline === void 0 ? intervalMs : Math.min(intervalMs, Math.max(0, deadline - now()));
+    await sleep(wait2);
   }
 }
-function report2(ctx, result) {
+function report2(ctx, parsed, result) {
   if (ctx.json) {
     ctx.out.log(JSON.stringify(result, null, 2));
-  } else if (result.found) {
+  } else if (parsed.options.jsonl !== true && result.found) {
     for (const post of result.posts ?? []) {
       const who = post.authorKind === "bot" ? `${post.authorId} (agent)` : post.authorId;
       ctx.out.log(`\u2014 ${who}
@@ -7539,13 +7729,6 @@ ${post.body}`);
   }
   return result;
 }
-var WatchTimeoutError = class extends Error {
-  code = "watch_timeout";
-  constructor() {
-    super("nothing new before the timeout");
-    this.name = "WatchTimeoutError";
-  }
-};
 
 // src/discuss-command.ts
 var ALLOWED = [
@@ -7567,6 +7750,8 @@ var ALLOWED = [
   "self",
   "interval",
   "timeout",
+  "cursor",
+  "jsonl",
   "mutation-id"
 ];
 function requireId(id, action) {
@@ -7603,7 +7788,7 @@ async function discussCommand(parsed, deps = {}) {
     case "topics":
       return discussList(ctx, parsed);
     case "read":
-      return discussRead(ctx, requireId(id, "read"));
+      return discussRead(ctx, requireId(id, "read"), parsed);
     case "post":
       return discussPost(ctx, parsed);
     case "reply":
@@ -7614,7 +7799,7 @@ async function discussCommand(parsed, deps = {}) {
       return discussWho(ctx, parsed);
     case "watch": {
       const result = await discussWatch(ctx, id, parsed);
-      if (!result.found) throw new WatchTimeoutError();
+      if (!result.found) throw new WatchTimeoutError(result.cursor);
       return;
     }
     default:
@@ -10378,7 +10563,12 @@ async function securityStatus(parsed, dependencies) {
 // src/cli.ts
 function exitCodeFor(err) {
   const code = err?.code;
-  return code === "handshake_pending" || code === "watch_timeout" ? 75 : 1;
+  if (code === "handshake_pending" || code === "watch_timeout") return 75;
+  if (code === "checkpoint_required") return 3;
+  if (code === "remote_unavailable") return 6;
+  if (code === "auth_failed") return 5;
+  if (code === "invalid_cursor") return 2;
+  return 1;
 }
 async function runCli(argv = process.argv.slice(2), dependencies = {}) {
   const runtime = {