@odla-ai/cli 0.25.6 → 0.25.8

package/README.md

@@ -72,7 +72,8 @@ snapshot instead of scraping Studio or composing collector routes themselves:
 npx odla-ai o11y status --app <appId> --env prod --minutes 60 --json
 ```
 
-Schema v3 keeps application RED, reconciled live-sync load/freshness, the exact
+Schema v4 keeps application RED, reconciled live-sync load/freshness and
+subscription recompute/fanout/payload/commit-to-send performance, the exact
 latest protected commit-to-visible canary, collector ingest/scheduler trust,
 and Cloudflare-owned Worker runtime evidence separate. It derives one
 `healthy`, `degraded`, or `unhealthy` verdict with stable reason codes while
@@ -192,6 +193,8 @@ 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 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
@@ -213,6 +216,15 @@ 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.
+
 `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"
@@ -3946,8 +4025,8 @@ async function materializeGitTree(source, commitSha, options = {}) {
   const maxFiles = options.maxFiles ?? 2e4;
   const maxBytes = options.maxBytes ?? 512 * 1024 * 1024;
   const inventory = (await gitOutput(sourceDir, ["ls-tree", "-rz", commitSha], 16 * 1024 * 1024)).toString("utf8").split("\0").filter(Boolean);
-  const entries = inventory.flatMap((record6) => {
-    const match = /^(100644|100755) blob ([0-9a-f]{40,64})\t([\s\S]+)$/.exec(record6);
+  const entries = inventory.flatMap((record7) => {
+    const match = /^(100644|100755) blob ([0-9a-f]{40,64})\t([\s\S]+)$/.exec(record7);
     return match && allowedWorkspacePath(match[3]) ? [{ mode: match[1], hash: match[2], path: match[3] }] : [];
   });
   if (entries.length > maxFiles) throw new Error(`workspace exceeds ${maxFiles} files`);
@@ -4195,8 +4274,8 @@ function normalize(value) {
   if (Array.isArray(value)) return value.map(normalize);
   if (value instanceof Uint8Array) return { $bytes: [...value] };
   if (typeof value === "object") {
-    const record6 = value;
-    return Object.fromEntries(Object.keys(record6).filter((key) => record6[key] !== void 0).sort().map((key) => [key, normalize(record6[key])]));
+    const record7 = value;
+    return Object.fromEntries(Object.keys(record7).filter((key) => record7[key] !== void 0).sort().map((key) => [key, normalize(record7[key])]));
   }
   throw new CamelError("state_conflict", "Canonical JSON rejects unsupported values.");
 }
@@ -6490,6 +6569,8 @@ Usage:
   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 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.
@@ -7650,8 +7733,8 @@ async function pmAdd(ctx, entity, parsed) {
   emit2(ctx, res, () => ctx.out.log(`created ${entity} ${res.id}`));
 }
 async function pmGet(ctx, entity, id) {
-  const { record: record6 } = await pmRequest(ctx, "GET", `/${entity}/${encodeURIComponent(id)}`);
-  emit2(ctx, record6, () => printRecord(ctx, entity, record6));
+  const { record: record7 } = await pmRequest(ctx, "GET", `/${entity}/${encodeURIComponent(id)}`);
+  emit2(ctx, record7, () => printRecord(ctx, entity, record7));
 }
 async function pmSet(ctx, entity, id, parsed) {
   const patch2 = collectEntityFields(entity, parsed, true);
@@ -7696,9 +7779,9 @@ async function pmHandoff(ctx, parsed) {
   ]);
   const handoff = {
     appId,
-    unmetGoals: goals.filter((record6) => record6.status !== "met"),
-    activeTasks: tasks.filter((record6) => record6.column !== "done"),
-    openBugs: bugs.filter((record6) => record6.status !== "fixed" && record6.status !== "wontfix")
+    unmetGoals: goals.filter((record7) => record7.status !== "met"),
+    activeTasks: tasks.filter((record7) => record7.column !== "done"),
+    openBugs: bugs.filter((record7) => record7.status !== "fixed" && record7.status !== "wontfix")
   };
   const result = {
     ...handoff,
@@ -7717,10 +7800,10 @@ async function pmHandoff(ctx, parsed) {
     ]) {
       ctx.out.log(`${label}:`);
       if (!records.length) ctx.out.log("- (none)");
-      else for (const record6 of records) printRecord(
+      else for (const record7 of records) printRecord(
         ctx,
         label === "unmet goals" ? "goal" : label === "active tasks" ? "task" : "bug",
-        record6
+        record7
       );
     }
   });
@@ -7861,6 +7944,21 @@ function statusVerdict(reads) {
       severity: "degraded"
     });
   }
+  const performance = record5(reads.liveSync.body.performance) ? reads.liveSync.body.performance : null;
+  if (performance?.status === "unavailable") {
+    reasons.push({
+      source: "liveSync",
+      code: "subscription_metrics_unavailable",
+      severity: "degraded"
+    });
+  }
+  if (numeric2(performance?.telemetryDropped) > 0) {
+    reasons.push({
+      source: "liveSync",
+      code: "subscription_telemetry_dropped",
+      severity: "degraded"
+    });
+  }
   const canaryStatus = String(reads.canary.body.status ?? "");
   if (canaryStatus === "failing") {
     reasons.push({
@@ -7908,6 +8006,12 @@ function statusVerdict(reads) {
     reasons
   };
 }
+function record5(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function numeric2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
 function collectorReason(read3, fallback) {
   const reasons = read3.body.reasons;
   if (!Array.isArray(reasons)) return fallback;
@@ -7965,7 +8069,7 @@ async function o11yCommand(parsed, deps = {}) {
   const [application, liveSync, canary, collector, provider] = await Promise.all([
     read2(`${base}/metrics/red?${query}`, headers, doFetch),
     read2(
-      `${base}/live-sync/health?${new URLSearchParams({ env })}`,
+      `${base}/live-sync/health?${query}`,
       headers,
       doFetch
     ),
@@ -7985,7 +8089,7 @@ async function o11yCommand(parsed, deps = {}) {
     provider
   });
   const status = {
-    schemaVersion: 3,
+    schemaVersion: 4,
     scope: { appId, env, minutes },
     observedAt: (/* @__PURE__ */ new Date()).toISOString(),
     verdict,
@@ -8025,42 +8129,47 @@ function printStatus2(status, out) {
   out.log(
     `o11y status ${status.scope.appId}/${status.scope.env} (${status.scope.minutes}m)`
   );
-  const routes = Array.isArray(status.application.body.routes) ? status.application.body.routes.filter(record5) : [];
+  const routes = Array.isArray(status.application.body.routes) ? status.application.body.routes.filter(record6) : [];
   const requests = routes.reduce(
-    (total, row) => total + numeric2(row.requests),
+    (total, row) => total + numeric3(row.requests),
     0
   );
   const errors = routes.reduce(
-    (total, row) => total + numeric2(row.errors),
+    (total, row) => total + numeric3(row.errors),
     0
   );
   out.log(
     `application	${status.application.httpStatus}	${requests} requests	${errors} errors`
   );
   out.log(
-    `live-sync	${status.liveSync.httpStatus}	${String(status.liveSync.body.status ?? status.liveSync.body.error ?? "unavailable")}	${numeric2(status.liveSync.body.activeConnections)} active`
+    liveSyncLine(status.liveSync)
   );
-  const canaryDurations = record5(status.canary.body.durationsMs) ? status.canary.body.durationsMs : {};
+  const canaryDurations = record6(status.canary.body.durationsMs) ? status.canary.body.durationsMs : {};
   out.log(
     `canary	${status.canary.httpStatus}	${String(status.canary.body.status ?? status.canary.body.error ?? "unavailable")}	${optionalNumeric(canaryDurations.publishToVisibleMs)} publish-to-visible`
   );
-  const collectorIngest = record5(status.collector.body.ingest) ? status.collector.body.ingest : {};
-  const collectorStorage = record5(collectorIngest.storage) ? collectorIngest.storage : {};
+  const collectorIngest = record6(status.collector.body.ingest) ? status.collector.body.ingest : {};
+  const collectorStorage = record6(collectorIngest.storage) ? collectorIngest.storage : {};
   out.log(
-    `collector	${status.collector.httpStatus}	${String(status.collector.body.status ?? status.collector.body.error ?? "unavailable")}	${numeric2(collectorStorage.affectedPoints)} affected points`
+    `collector	${status.collector.httpStatus}	${String(status.collector.body.status ?? status.collector.body.error ?? "unavailable")}	${numeric3(collectorStorage.affectedPoints)} affected points`
   );
-  const providerMetrics = record5(status.provider.body.metrics) ? status.provider.body.metrics : {};
+  const providerMetrics = record6(status.provider.body.metrics) ? status.provider.body.metrics : {};
   out.log(
-    `cloudflare	${status.provider.httpStatus}	${String(status.provider.body.status ?? status.provider.body.error ?? "unavailable")}	${numeric2(providerMetrics.requests)} invocations	${numeric2(providerMetrics.errors)} runtime errors`
+    `cloudflare	${status.provider.httpStatus}	${String(status.provider.body.status ?? status.provider.body.error ?? "unavailable")}	${numeric3(providerMetrics.requests)} invocations	${numeric3(providerMetrics.errors)} runtime errors`
   );
   out.log(
     `verdict	${status.verdict.status}	${status.verdict.reasons.map((reason) => `${reason.source}:${reason.code}`).join(", ") || "all required signals healthy"}`
   );
 }
-function record5(value) {
+function liveSyncLine(read3) {
+  const performance = record6(read3.body.performance) ? read3.body.performance : {};
+  const commitToSend = record6(performance.commitToSend) ? performance.commitToSend : {};
+  return `live-sync	${read3.httpStatus}	${String(read3.body.status ?? read3.body.error ?? "unavailable")}	${numeric3(read3.body.activeConnections)} active	${optionalNumeric(commitToSend.p95)} commit-to-send p95	${numeric3(performance.sendFailures)} send failures`;
+}
+function record6(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function numeric2(value) {
+function numeric3(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 function optionalNumeric(value) {
@@ -8493,6 +8602,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: {},
@@ -10308,6 +10418,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;