@erdoai/cli 0.49.0 → 0.50.0

package/dist/index.js

@@ -916,6 +916,47 @@ var ErdoClient = class {
       input
     );
   }
+  // --- decisions ---
+  // The decision record: what the organization committed to, what executed, and
+  // what the evidence said afterwards. Referenced by slug, never UUID.
+  listDecisions(opts) {
+    const params = new URLSearchParams();
+    if (opts.workstream_slug) params.set("workstream_slug", opts.workstream_slug);
+    if (opts.source) params.set("source", opts.source);
+    if (opts.decision_class) params.set("decision_class", opts.decision_class);
+    if (opts.subject_kind) params.set("subject_kind", opts.subject_kind);
+    if (opts.subject_ref) params.set("subject_ref", opts.subject_ref);
+    if (opts.status) params.set("status", opts.status);
+    if (opts.applicability) params.set("applicability", opts.applicability);
+    if (opts.outcome) params.set("outcome", opts.outcome);
+    if (opts.limit) params.set("limit", String(opts.limit));
+    if (opts.offset) params.set("offset", String(opts.offset));
+    const qs = params.toString();
+    return this.request("GET", `/v1/decisions${qs ? `?${qs}` : ""}`);
+  }
+  // One decision in full. A slug belonging to another organization reads as 404,
+  // so it cannot be probed for existence.
+  getDecision(slug) {
+    return this.request(
+      "GET",
+      `/v1/decisions/${encodeURIComponent(slug)}`
+    );
+  }
+  // Raw aggregates with their denominators — no eligibility verdict, and no single
+  // pooled "worked rate" across evidence kinds and decision classes.
+  decisionScorecard(opts) {
+    const params = new URLSearchParams();
+    if (opts.workstream_slug) params.set("workstream_slug", opts.workstream_slug);
+    if (opts.source) params.set("source", opts.source);
+    if (opts.decision_class) params.set("decision_class", opts.decision_class);
+    if (opts.since) params.set("since", opts.since);
+    if (opts.until) params.set("until", opts.until);
+    const qs = params.toString();
+    return this.request(
+      "GET",
+      `/v1/decisions-scorecard${qs ? `?${qs}` : ""}`
+    );
+  }
   // --- pages / artifacts ---
   deployPage(input) {
     return this.request("POST", "/v1/pages", input);
@@ -1722,7 +1763,7 @@ wsCmd.command("arm <slug>").description("Arm the recurring reconciliation loop (
   }
 );
 wsCmd.command("ledger <slug>").description(
-  "Read the allocator's single ledger view \u2014 budget, experiments + observations, judge calibration, attention items, allocator recommendation"
+  "Read the allocator's single ledger view \u2014 budget, experiments + observations, judge calibration, the decisions currently in force, attention items, allocator recommendation"
 ).option("--observations <n>", "observations to include per experiment", (v) => parseInt(v, 10)).action(async (slug, opts) => {
   try {
     print(await new ErdoClient().readWorkstreamLedger(slug, opts.observations));
@@ -2437,6 +2478,210 @@ runsCmd.command("get <id>").description("Show an agent run (status, output, trac
     fail(e);
   }
 });
+var decisionsCmd = program.command("decisions").description(
+  "The decision record \u2014 what your organization committed to, whether the change actually happened, and what the evidence said afterwards"
+);
+function decisionLine(d) {
+  const parts = [d.slug, d.status];
+  if (d.execution_status) parts.push(d.execution_status);
+  parts.push(d.what);
+  if (d.outcome_label) {
+    parts.push(d.outcome_label);
+  } else if (d.outcome_status) {
+    parts.push(d.outcome_status);
+  }
+  return parts.join("	");
+}
+decisionsCmd.command("list").description("List decisions, newest first").option("--workstream <slug>", "only decisions filed under this workstream/Strategy").option(
+  "--source <source>",
+  "producer family: approval | escalation | engine_gate | allocator | experiment | workstream_commitment"
+).option("--class <class>", "decision class, e.g. paid_media.ad_group.pause").option("--subject-kind <kind>", "only decisions about this kind of subject").option("--subject-ref <id>", "only decisions about this exact subject").option(
+  "--status <status>",
+  "proposed | authorized | executing | effective | measuring | settled | rejected | failed | censored"
+).option("--applicability <kind>", "standing | one_shot").option("--outcome <outcome>", "only decisions with a settled effect that came back met | not_met | inconclusive").option("-l, --limit <n>", "max rows (default 50, max 200)", (v) => parseInt(v, 10)).option("--offset <n>", "pagination offset", (v) => parseInt(v, 10)).option("--json", "output raw JSON").action(
+  async (opts) => {
+    try {
+      const res = await new ErdoClient().listDecisions({
+        workstream_slug: opts.workstream,
+        source: opts.source,
+        decision_class: opts.class,
+        subject_kind: opts.subjectKind,
+        subject_ref: opts.subjectRef,
+        status: opts.status,
+        applicability: opts.applicability,
+        outcome: opts.outcome,
+        limit: opts.limit,
+        offset: opts.offset
+      });
+      if (opts.json) {
+        print(res);
+        return;
+      }
+      if (!res.decisions.length) {
+        console.log("No decisions match. Widen the filters, or check that the work engine is on for this org.");
+        return;
+      }
+      for (const d of res.decisions) console.log(decisionLine(d));
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+function renderDecision(detail) {
+  const d = detail.decision;
+  console.log(d.what);
+  const facts = [
+    ["status", d.status],
+    ["class", d.decision_class],
+    ["source", d.source],
+    ["applies", d.applicability === "standing" ? "standing (until superseded)" : "one-off authorization"],
+    ["decided by", d.decider_kind]
+  ];
+  if (d.subject_label) facts.push(["subject", d.subject_label]);
+  if (d.execution_status) facts.push(["execution", d.execution_status]);
+  if (d.outcome_status) facts.push(["outcome", d.outcome_label || d.outcome_status]);
+  facts.push(["proposed", d.proposed_at]);
+  if (d.authorized_at) facts.push(["authorized", d.authorized_at]);
+  for (const [label, value] of facts) console.log(`  ${label.padEnd(11)} ${value}`);
+  if (d.why) {
+    console.log("");
+    console.log(`Why: ${d.why}`);
+  }
+  if (d.decider_rationale) console.log(`Decider said: ${d.decider_rationale}`);
+  if (detail.actions.length) {
+    console.log("");
+    console.log(detail.actions.length === 1 ? "Action:" : `Actions (${detail.actions.length}):`);
+    detail.actions.forEach((a, i) => {
+      console.log(`  ${i + 1}. ${a.action_key} \u2014 ${a.execution_status}`);
+      if (a.subject_label) console.log(`     subject: ${a.subject_label}`);
+      if (a.effective_at) console.log(`     effective: ${a.effective_at}`);
+      if (a.result_summary) console.log(`     result: ${a.result_summary}`);
+    });
+  }
+  if (detail.effects.length) {
+    console.log("");
+    console.log(detail.effects.length === 1 ? "Expected effect:" : `Expected effects (${detail.effects.length}):`);
+    detail.effects.forEach((e, i) => {
+      const predicate = [e.metric, e.success_operator, e.target_value ?? e.min_delta].filter((p) => p !== void 0 && p !== null && p !== "").join(" ");
+      console.log(`  ${i + 1}. ${predicate || e.measurability} \u2014 ${e.status}`);
+      if (e.outcome) {
+        console.log(`     outcome: ${e.outcome_label || e.outcome} (${e.evidence_kind} evidence)`);
+      }
+      if (e.baseline_value !== void 0 && e.baseline_value !== null && e.outcome_value !== void 0 && e.outcome_value !== null) {
+        console.log(`     measured: ${e.baseline_value} \u2192 ${e.outcome_value}`);
+      }
+      if (e.unmeasurable_reason) console.log(`     reason: ${e.unmeasurable_reason}`);
+    });
+  }
+  if (detail.lineage.supersedes_slug || detail.lineage.superseded_by_slugs?.length) {
+    console.log("");
+    console.log("Lineage:");
+    if (detail.lineage.supersedes_slug) console.log(`  replaced ${detail.lineage.supersedes_slug}`);
+    for (const slug of detail.lineage.superseded_by_slugs ?? []) {
+      console.log(`  replaced by ${slug}`);
+    }
+  }
+}
+decisionsCmd.command("show <slug>").description(
+  "Show one decision in full: the commitment and its authority, every exact action it authorized with how each one ended, every declared effect with the evidence that settled it, and what it replaced or was replaced by"
+).option("--json", "output raw JSON").action(async (slug, opts) => {
+  try {
+    const detail = await new ErdoClient().getDecision(slug);
+    if (opts.json) {
+      print(detail);
+      return;
+    }
+    renderDecision(detail);
+  } catch (e) {
+    fail(e);
+  }
+});
+function renderStrata(title, strata) {
+  if (!strata.length) return;
+  console.log("");
+  console.log(title);
+  for (const s of strata) {
+    const axis = s.decision_class || s.source || "(unclassified)";
+    console.log(`  ${axis} \xB7 ${s.evidence_kind} evidence \u2014 ${s.settled} settled`);
+    console.log(`     ${s.met} ${s.met_label} \xB7 ${s.not_met} ${s.not_met_label} \xB7 ${s.inconclusive} inconclusive`);
+  }
+}
+function renderScorecard(card) {
+  console.log("Decision record");
+  console.log(`  decisions   ${card.totals.decisions}`);
+  for (const [status, n] of Object.entries(card.totals.by_status)) {
+    console.log(`     ${status.padEnd(11)} ${n}`);
+  }
+  if (card.totals.legacy_unclassified > 0) {
+    console.log(`  legacy      ${card.totals.legacy_unclassified} (predates expected-effect capture; excluded from outcomes below)`);
+  }
+  console.log("");
+  console.log("Execution");
+  console.log(`  decisions with an external action   ${card.execution.decisions_with_actions} of ${card.totals.decisions}`);
+  console.log(`  actions                            ${card.execution.actions}`);
+  for (const [status, n] of Object.entries(card.execution.by_status)) {
+    console.log(`     ${status.padEnd(11)} ${n}`);
+  }
+  console.log("");
+  console.log("Measurement coverage");
+  console.log(
+    `  decisions that declared an effect   ${card.measurement.decisions_with_declared_effect} of ${card.totals.decisions}`
+  );
+  console.log(`  effects                            ${card.measurement.effects}`);
+  console.log(`     settled                 ${card.measurement.settled}`);
+  console.log(`     censored                ${card.measurement.censored}`);
+  console.log(`     measurement unavailable ${card.measurement.measurement_unavailable}`);
+  for (const [kind, n] of Object.entries(card.measurement.by_measurability)) {
+    console.log(`     ${kind.padEnd(29)} ${n}`);
+  }
+  renderStrata("Outcomes by decision class and evidence", card.outcomes_by_class_and_evidence);
+  renderStrata("Outcomes by source and evidence", card.outcomes_by_source_and_evidence);
+  console.log("");
+  console.log("Deciders");
+  console.log(`  answered                 ${card.deciders.answered}`);
+  for (const [kind, n] of Object.entries(card.deciders.by_decider_kind)) {
+    console.log(`     ${kind.padEnd(21)} ${n}`);
+  }
+  console.log(
+    `  safe default applied     ${card.deciders.safe_default} of ${card.deciders.answered} (${(card.deciders.safe_default_rate * 100).toFixed(1)}%)`
+  );
+  console.log(
+    `  human refused a proposal ${card.deciders.human_override} of ${card.deciders.answered} (${(card.deciders.human_override_rate * 100).toFixed(1)}%)`
+  );
+  if (card.decide_latency.decided > 0) {
+    console.log("");
+    console.log("Time to authorize");
+    console.log(`  decisions authorized  ${card.decide_latency.decided}`);
+    console.log(`  median                ${(card.decide_latency.p50_seconds / 3600).toFixed(1)}h`);
+    console.log(`  90th percentile       ${(card.decide_latency.p90_seconds / 3600).toFixed(1)}h`);
+  }
+  console.log("");
+  console.log(
+    "Raw counts only \u2014 no eligibility verdict, and no single pooled rate: deterministic confirmation, experimental results and observational movement are counted separately because they support different claims."
+  );
+}
+decisionsCmd.command("scorecard").description(
+  "Raw aggregates over the decision record with their denominators: totals by status, how much executed, how much can be measured at all, and the settled outcome split within each comparable stratum"
+).option("--workstream <slug>", "score only this workstream/Strategy's decisions").option("--source <source>", "score only one producer family").option("--class <class>", "score only one decision class").option("--since <rfc3339>", "inclusive lower bound on when the decision was recorded").option("--until <rfc3339>", "exclusive upper bound on when the decision was recorded").option("--json", "output raw JSON").action(
+  async (opts) => {
+    try {
+      const card = await new ErdoClient().decisionScorecard({
+        workstream_slug: opts.workstream,
+        source: opts.source,
+        decision_class: opts.class,
+        since: opts.since,
+        until: opts.until
+      });
+      if (opts.json) {
+        print(card);
+        return;
+      }
+      renderScorecard(card);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
 var approvalsCmd = program.command("approvals").description("List and decide approval requests (actions agents paused on)");
 approvalsCmd.command("list").description("List approval requests, optionally filtered by status").option("-s, --status <status>", "pending | approved | rejected | expired (default: all)").option("-l, --limit <n>", "max requests", (v) => parseInt(v, 10)).option("--workstream <slug>", "only approvals for this workstream").option(
   "--subject-type <type>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdoai/cli",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
   "type": "module",
   "bin": {