@odla-ai/cli 0.25.7 → 0.25.9

package/README.md

@@ -193,6 +193,10 @@ npx odla-ai code connect --env prod --once # bounded enrollment + heartbeat proo
 npx odla-ai provision --dry-run
 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
@@ -214,6 +218,26 @@ npx odla-ai skill install
 npx odla-ai version
 ```
 
+`agent jobs` is the remote-operator view of commit-trigger delivery. It reads
+content-free lifecycle metadata—job id, trigger, entity reference, state,
+attempts, timing, and bounded error/status codes—using an audience-bound
+developer token for an owner of the selected environment. `agent retry` accepts one exact
+dead-lettered id and resets its attempt lease; it does not replay successful or
+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.
+
 `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

@@ -1020,11 +1020,6 @@ async function adminCommand(parsed) {
   });
 }
 
-// src/app-export.ts
-var import_node_fs5 = require("fs");
-var import_node_stream = require("stream");
-var import_promises = require("stream/promises");
-
 // src/config.ts
 var import_node_fs4 = require("fs");
 var import_node_path4 = require("path");
@@ -1333,7 +1328,90 @@ function bothTenants(cfg) {
   return { sandbox: (0, import_apps.tenantIdFor)(cfg.app.id, "dev"), live: (0, import_apps.tenantIdFor)(cfg.app.id, "prod") };
 }
 
+// src/agent-command.ts
+async function agentCommand(parsed, deps = {}) {
+  const action = parsed.positionals[1];
+  if (action !== "jobs" && action !== "retry") {
+    throw new Error(`unknown agent action "${action ?? ""}". Try "odla-ai agent jobs --json".`);
+  }
+  assertArgs(parsed, ["config", "env", "state", "limit", "json", "token", "email"], action === "jobs" ? 2 : 3);
+  if (action === "retry" && (parsed.options.state !== void 0 || parsed.options.limit !== void 0)) {
+    throw new Error('--state and --limit are supported only by "agent jobs"');
+  }
+  const cfg = await loadProjectConfig(stringOpt(parsed.options.config) ?? "odla.config.mjs");
+  const { env, tenant } = resolveTenant(cfg, stringOpt(parsed.options.env));
+  const doFetch = deps.fetch ?? fetch;
+  const out = deps.stdout ?? console;
+  const credential2 = await getDeveloperToken(
+    cfg,
+    {
+      configPath: cfg.configPath,
+      token: stringOpt(parsed.options.token),
+      email: stringOpt(parsed.options.email),
+      open: false
+    },
+    doFetch,
+    out
+  );
+  const base = `${cfg.dbEndpoint}/app/${encodeURIComponent(tenant)}/admin/agent-jobs`;
+  const headers = { authorization: `Bearer ${credential2}` };
+  if (action === "retry") {
+    const id = parsed.positionals[2];
+    const res2 = await doFetch(`${base}/${encodeURIComponent(id)}/retry`, { method: "POST", headers });
+    const body2 = await readJson(res2);
+    if (!res2.ok) throw new Error(`agent retry failed (${res2.status}): ${errorMessage(body2)}`);
+    const result2 = { v: 1, appId: cfg.app.id, env, tenant, ...body2 };
+    if (parsed.options.json === true) out.log(JSON.stringify(result2, null, 2));
+    else out.log(`${tenant}: requeued ${id}`);
+    return;
+  }
+  const state2 = stringOpt(parsed.options.state);
+  const allowed = ["pending", "running", "succeeded", "dead_letter"];
+  if (state2 && !allowed.includes(state2)) {
+    throw new Error(`--state must be one of ${allowed.join(", ")}`);
+  }
+  const url = new URL(base);
+  if (state2) url.searchParams.set("state", state2);
+  const limit = numberOpt(parsed.options.limit, "--limit");
+  if (limit) url.searchParams.set("limit", String(limit));
+  const res = await doFetch(url, { headers });
+  const body = await readJson(res);
+  if (!res.ok) throw new Error(`agent jobs failed (${res.status}): ${errorMessage(body)}`);
+  const result = { v: 1, appId: cfg.app.id, env, tenant, jobs: body.jobs ?? [], summary: body.summary };
+  if (parsed.options.json === true) {
+    out.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const summary = body.summary;
+  out.log(
+    `${tenant}: ${summary?.pending ?? 0} pending, ${summary?.running ?? 0} running, ${summary?.deadLetter ?? 0} dead-letter, ${summary?.succeeded ?? 0} succeeded`
+  );
+  for (const job of body.jobs ?? []) {
+    out.log(
+      [job.state, job.id, job.triggerId, `${job.entityNs}/${job.entityId}`, `attempts=${job.attempts}`, job.lastErrorCode ?? ""].filter(Boolean).join("	")
+    );
+  }
+}
+async function readJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    return {};
+  }
+}
+function errorMessage(body) {
+  const error = body.error;
+  if (typeof error === "string") return error;
+  if (error && typeof error === "object" && typeof error.message === "string") {
+    return error.message;
+  }
+  return "request failed";
+}
+
 // src/app-export.ts
+var import_node_fs5 = require("fs");
+var import_node_stream = require("stream");
+var import_promises = require("stream/promises");
 async function appExport(options) {
   const cfg = await loadProjectConfig(options.configPath);
   const out = options.stdout ?? console;
@@ -2311,6 +2389,7 @@ var CAPABILITIES = {
     "apply Google Calendar booking config, then drive state-bound consent, status, discovery, and disconnect flows (bookings run live through the platform proxy)",
     "validate integration contracts offline and smoke-test a provisioned db environment plus anonymous capability routes",
     "read one versioned o11y status envelope spanning application RED, current live-sync freshness/load, the protected commit-to-visible canary, collector ingest/scheduler trust, provider-owned runtime metrics, and a bounded machine verdict",
+    "inspect durable agent wakeups as a versioned JSON envelope and explicitly requeue one dead-lettered job with a scoped environment credential",
     "run app-attributed hosted security discovery and independent validation without provider keys",
     "connect/revoke source-read-only GitHub sources and drive commit-pinned hosted security jobs without PATs or provider keys",
     "let admins manage system AI policy and credentials, inspect attributed usage, and read immutable admin changes through separate short-lived capability-only approvals"
@@ -4529,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;
   };
@@ -6489,7 +6568,9 @@ Usage:
   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]
   odla-ai whoami [--json]
   odla-ai runbook ask "<question>" [--app <id>] [--all] [--json]
@@ -6537,6 +6618,8 @@ Usage:
   odla-ai version
 
 Commands:
+  agent        Inspect durable agent wakeups and explicitly requeue a
+               dead-lettered job; JSON output is stable for remote operators.
   runbook      odla's operational procedures, stored in the database and read at
                the moment they are followed. "ask" gives a written, cited answer;
                "search" the passages behind it; "get" the whole document.
@@ -7390,61 +7473,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}
@@ -7456,13 +7692,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 = [
@@ -7484,6 +7713,8 @@ var ALLOWED = [
   "self",
   "interval",
   "timeout",
+  "cursor",
+  "jsonl",
   "mutation-id"
 ];
 function requireId(id, action) {
@@ -7531,7 +7762,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:
@@ -8519,6 +8750,7 @@ var PM_ENTITIES = Object.fromEntries(
   ["goal", "conformance", "task", "kanban", "decision", "bug"].map((entity) => [entity, PM_ACTIONS])
 );
 var COMMAND_SURFACE = {
+  agent: { jobs: {}, retry: {} },
   admin: {
     ai: {
       show: {},
@@ -10294,7 +10526,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 = {
@@ -10334,6 +10571,10 @@ async function runCli(argv = process.argv.slice(2), dependencies = {}) {
     await adminCommand(parsed);
     return;
   }
+  if (command === "agent") {
+    await agentCommand(parsed, runtime);
+    return;
+  }
   if (command === "app") {
     await appCommand(parsed, runtime);
     return;