@datarails-ai/dr-cli 1.6.179 → 1.6.181

package/README.md

@@ -435,6 +435,7 @@ dr skill print <name>     # print an embedded skill's SKILL.md
 | Folders              | `folders list/create`, `folders reorder --container <root\|id> (--items folder:12,entity:87 \| --move <kind:id> --to-index <n>)`, `folders move <id> --parent <root\|id>` (dashboard / story picker tree, flag-gated; reorder and move are two-step confirm; a dashboard moves with `dashboards set-folder`)                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Functions            | `functions list/get/create/delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Dynamic ranges       | `dynamic-ranges list/get/data/create/delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Calc models          | `calcmodels list/get/create/update/set-flow/recalculate/delete`; AGENT builder: `calcmodels agent ask/preview/save/approve` (`save` makes a draft; `approve` is two-step, Tier A)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Lookups (LUTs)       | `lut list/create/update/delete/reorder/unmapped` (alias `lookups`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Documents            | `documents support-api set <id> --on/--off`, `documents calculate <id> --year/--quarter/--month/--day/--week ... [--backward] [--no-roll]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | Semantic tables      | `semantic-tables list/get`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.179",
+  version: "1.6.181",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -40,7 +40,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.12.56",
+    "@datarails-ai/dr-appspace-cli": "0.12.58",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-29T15:44:45.951Z";
+var BUILD_TIME = "2026-11-01T14:08:05.005Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -1410,11 +1410,11 @@ function exchangeForSession(store, serverKey, email, session, host, opts) {
         if (err.throttled && cachedIsUsable) return session;
         if (err.transient) {
           if (cachedIsUsable) return session;
-          const delay = API_KEY_EXCHANGE_RETRY_DELAYS_MS[attempt];
-          if (delay !== void 0) {
+          const delay2 = API_KEY_EXCHANGE_RETRY_DELAYS_MS[attempt];
+          if (delay2 !== void 0) {
             attempt += 1;
             try {
-              await sleep(delay, void 0, { signal });
+              await sleep(delay2, void 0, { signal });
             } catch {
               throw new SessionExpiredError(
                 `${identity2} (api-key exchange ended before its retry)`
@@ -4438,6 +4438,13 @@ var PROD_GATE_TIER_A = /* @__PURE__ */ new Set([
   "category|delete",
   // calc-models
   "calcmodel|delete",
+  // dr calcmodels agent approve — activates an AGENT model's newest version and starts its
+  // first production run, which writes new rows into a table that reports read. Unlike
+  // `set-flow` / `recalculate` (Tier B), which re-run a model already approved, this puts
+  // numbers nobody has run before into production, so a person confirms it. The plan
+  // prints the version and its impact (rows, pool, allocated, coverage); the token binds
+  // that version.
+  "calcmodel|approve",
   // filebox
   "filebox|archive",
   "filebox-data-query|clear",
@@ -7421,8 +7428,8 @@ async function retryAsync(fn, opts) {
       const kind = classifyFailure(err);
       const retryable = kind === "transient" || kind !== "abort" && opts.alsoRetry?.(err) === true;
       if (!retryable || attempt > retries) throw err;
-      const delay = opts.delayMs ?? defaultBackoffMs;
-      const waitMs = typeof delay === "function" ? delay(attempt) : delay;
+      const delay2 = opts.delayMs ?? defaultBackoffMs;
+      const waitMs = typeof delay2 === "function" ? delay2(attempt) : delay2;
       opts.onRetry?.(attempt, err, waitMs);
       await sleep2(waitMs, opts.signal);
     }
@@ -35556,7 +35563,7 @@ function registerDatamappersCommand(root) {
   });
   addServerFlag(customFnsCmd);
   addAccountFlag(customFnsCmd);
-  const previewCmd = dm.command("preview").description(
+  const previewCmd2 = dm.command("preview").description(
     "Render a mapper config's projected output for a sample input. Posts to `POST /api/templates/preview-data` with the operator-supplied JSON (typically built from a saved mapper config + template_id + document_version + datamapper_id). Output is the server's `{output: {header, projected_config, \u2026}, err}` envelope, emitted as JSON."
   ).requiredOption("--payload-file <path>", "Path to a JSON body for the preview request").option(
     "--json",
@@ -35576,8 +35583,8 @@ function registerDatamappersCommand(root) {
       setup.cleanup();
     }
   });
-  addServerFlag(previewCmd);
-  addAccountFlag(previewCmd);
+  addServerFlag(previewCmd2);
+  addAccountFlag(previewCmd2);
   const bindCmd = dm.command("bind").description(
     "Update which document IDs a mapper is bound to. The --doc list replaces the mapper's current documents; repeat every filebox you want to keep (dr warns first and names any it drops). Posts to `POST /api/templates/mappers/<id>/binding` with `{selected_document_ids, rescan?}`. The legacy webclient's \"Mapping table with documents\" modal calls this when the operator checks/unchecks docs in the binding picker. Warns first when another mapper of the table on the same ordinal is bound to one of those docs: mappers that share an ordinal are versions of one mapper, so the bind unbinds the other."
   ).argument("<mapper_id>", "mapper id (positive integer)").option("--doc <id>", "Document id to bind (positive integer; repeatable)", collectInts, []).option(
@@ -43482,7 +43489,7 @@ function registerFileboxCommand(root) {
   });
   addServerFlag(sheetsCmd);
   addAccountFlag(sheetsCmd);
-  const previewCmd = fb.command("preview").description("Preview raw cell data of a filebox version (row 1 is headers)").argument("<version_id>", "version id (positive integer)").option("--sheet <name>", "Sheet name. Defaults to first sheet from /desc.", "").option("--sheet-ind <n>", "Sheet index (0-based). Defaults to 0.", "0").option("--start <n>", "First row to read (1-based)", "1").option("--rows <n>", "Number of rows to return (start..start+rows-1)", "100").option("--data-only", "Return evaluated values only; omit raw formulas", false).option("--json", "Output raw JSON instead of a table", false).action(
+  const previewCmd2 = fb.command("preview").description("Preview raw cell data of a filebox version (row 1 is headers)").argument("<version_id>", "version id (positive integer)").option("--sheet <name>", "Sheet name. Defaults to first sheet from /desc.", "").option("--sheet-ind <n>", "Sheet index (0-based). Defaults to 0.", "0").option("--start <n>", "First row to read (1-based)", "1").option("--rows <n>", "Number of rows to return (start..start+rows-1)", "100").option("--data-only", "Return evaluated values only; omit raw formulas", false).option("--json", "Output raw JSON instead of a table", false).action(
     async (vidStr, opts) => {
       const versionId = parseVersionIdArg2(vidStr);
       const sheetInd = parsePositiveIntFlag2(opts.sheetInd, "--sheet-ind", 0);
@@ -43507,8 +43514,8 @@ function registerFileboxCommand(root) {
       }
     }
   );
-  addServerFlag(previewCmd);
-  addAccountFlag(previewCmd);
+  addServerFlag(previewCmd2);
+  addAccountFlag(previewCmd2);
   const createCmd = fb.command("create").description(
     "Create an empty filebox (no file yet). Resolves the date tag config from /versions/tags. Pass --folder to create a folder filebox instead (no date tag, no version, no data \u2014 used to mirror the org-bootstrap hierarchy of Actuals / COA / FX Rates / Configuration)."
   ).option("--name <name>", "Filebox display name (required)", "").option("--scenario <s>", `Scenario: ${VALID_SCENARIOS_HELP}`, "Actuals").option(
@@ -47006,10 +47013,10 @@ function toControlPlaneError(method, path13, err) {
 }
 
 // src/api/awsConnections.ts
-async function call(method, path13, send, what) {
+async function call(method, path13, send2, what) {
   let out;
   try {
-    out = await send();
+    out = await send2();
   } catch (err) {
     throw toControlPlaneError(method, path13, err);
   }
@@ -48184,10 +48191,10 @@ import { readFileSync as readFileSync3 } from "fs";
 
 // src/api/scheduledTasks.ts
 var BASE2 = "/scheduled-tasks";
-async function call2(method, path13, send, what) {
+async function call2(method, path13, send2, what) {
   let out;
   try {
-    out = await send();
+    out = await send2();
   } catch (err) {
     throw toControlPlaneError(method, path13, err);
   }
@@ -65487,6 +65494,742 @@ async function remove(client, id, options) {
   await client.deleteJSON(`/api/templates/${id}/calcmodels`, options);
 }
 
+// src/commands/calcmodelsAgent.ts
+import { setTimeout as delay } from "timers/promises";
+
+// src/types/calcmodelsAgent.ts
+import { z as z3 } from "zod";
+var optionalText = z3.string().nullish();
+var amount = z3.number().nullish();
+var calcAgentOperationStatusSchema = z3.enum([
+  "PENDING",
+  "RUNNING",
+  "SUCCEEDED",
+  "NO_PROPOSAL",
+  "FAILED"
+]);
+var calcAgentGateErrorSchema = z3.object({
+  code: z3.string(),
+  phase: optionalText,
+  segment: optionalText,
+  suggestion: optionalText,
+  detail: optionalText
+}).passthrough();
+var calcAgentTurnAcceptedSchema = z3.object({ operation_id: z3.string().uuid(), conversation_id: z3.string().optional() }).passthrough();
+var coverageSchema = z3.object({
+  pct: amount,
+  pool_total: amount,
+  allocated_total: amount,
+  unallocated_amount: amount,
+  uncovered_group_count: z3.number().nullish()
+}).passthrough();
+var balanceCheckSchema = z3.object({ group: z3.string(), net: z3.number(), ok: z3.boolean() }).passthrough();
+var warningSchema = z3.object({ code: optionalText, message: optionalText }).passthrough();
+var calcAgentPreviewResultSchema = z3.object({
+  total_count: z3.number().nullish(),
+  coverage: coverageSchema.nullish(),
+  balance_checks: z3.array(balanceCheckSchema).nullish(),
+  warnings: z3.array(warningSchema).nullish()
+}).passthrough();
+var calcAgentDefinitionSchema = z3.object({
+  model_type: optionalText,
+  name: optionalText,
+  destination_template_id: z3.number().nullish()
+}).passthrough();
+var calcAgentPreviewSchema = z3.object({
+  status: calcAgentOperationStatusSchema,
+  phase: optionalText,
+  conversation_id: optionalText,
+  answer_text: optionalText,
+  changes_summary: optionalText,
+  definition: calcAgentDefinitionSchema.nullish(),
+  error: calcAgentGateErrorSchema.nullish(),
+  result: calcAgentPreviewResultSchema.nullish()
+}).passthrough();
+var calcAgentSaveResultSchema = z3.object({ id: z3.number(), name: z3.string(), version_id: z3.number() }).passthrough();
+var calcAgentImpactSchema = z3.object({
+  total_rows: amount,
+  pool_total: amount,
+  allocated_total: amount,
+  coverage_pct: amount
+}).passthrough();
+var calcAgentApprovalPlanSchema = z3.object({ impact: calcAgentImpactSchema, version_id: z3.number() }).passthrough();
+var calcAgentApproveResultSchema = z3.object({
+  id: z3.number(),
+  name: z3.string(),
+  impact: calcAgentImpactSchema.nullish(),
+  run_id: z3.string().nullish()
+}).passthrough();
+
+// src/api/_htmlEntities.ts
+var ENTITIES2 = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#x27;": "'",
+  "&#39;": "'"
+};
+var ENTITY_RE2 = /&(?:amp|lt|gt|quot|#x27|#39);/g;
+function decodeHtmlDeep(value) {
+  if (typeof value === "string") return value.replace(ENTITY_RE2, (m) => ENTITIES2[m] ?? m);
+  if (Array.isArray(value)) return value.map(decodeHtmlDeep);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, decodeHtmlDeep(v)]));
+  }
+  return value;
+}
+
+// src/api/calcmodelsAgent.ts
+var BASE3 = "/api/templates/calcmodels/agent";
+var APPROVAL_ACK_REQUIRED = "CALC_APPROVAL_ACK_REQUIRED";
+var CalcAgentHttpError = class extends Error {
+  status;
+  body;
+  code;
+  constructor(status2, body, message) {
+    super(message);
+    this.name = "CalcAgentHttpError";
+    this.status = status2;
+    this.body = body;
+    const code = isRecord(body) ? body["code"] : void 0;
+    this.code = typeof code === "string" ? code : void 0;
+  }
+  /** A numeric field of the body (`calc_model_id`, `version_id`), or undefined. */
+  numberField(key) {
+    const v = isRecord(this.body) ? this.body[key] : void 0;
+    return typeof v === "number" ? v : void 0;
+  }
+};
+var CONTROL_CHARS2 = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+function escapeControlChars(text2) {
+  return text2.replace(
+    CONTROL_CHARS2,
+    (c) => c === "\r" ? "\\r" : `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`
+  );
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function textField(body, key) {
+  if (!isRecord(body)) return void 0;
+  const v = body[key];
+  return typeof v === "string" && v !== "" ? v : void 0;
+}
+async function send(client, method, path13, payload, options) {
+  const res = await client.do(
+    method,
+    path13,
+    payload === void 0 ? void 0 : JSON.stringify(payload),
+    options
+  );
+  const text2 = await res.text();
+  let body = text2;
+  if (text2 !== "") {
+    try {
+      body = JSON.parse(text2);
+    } catch {
+      body = text2;
+    }
+  }
+  return { status: res.status, body: decodeHtmlDeep(body) };
+}
+function describeServerError(body) {
+  if (!isRecord(body)) {
+    const raw2 = typeof body === "string" ? body.trim() : "";
+    return raw2.length > 200 ? `${raw2.slice(0, 200)}\u2026` : raw2;
+  }
+  const code = textField(body, "code");
+  const phase = textField(body, "phase");
+  const parts = [
+    textField(body, "detail"),
+    textField(body, "suggestion"),
+    textField(body, "segment") !== void 0 ? `[${textField(body, "segment")}]` : void 0
+  ].filter((p) => p !== void 0);
+  const head = code !== void 0 ? `${code}${phase !== void 0 ? ` (${phase})` : ""}` : "";
+  if (head === "") return parts.join(" \u2014 ");
+  return parts.length > 0 ? `${head}: ${parts.join(" \u2014 ")}` : head;
+}
+function httpError(method, path13, answer, hint) {
+  const detail = escapeControlChars(hint ?? describeServerError(answer.body));
+  const tail = detail !== "" ? `: ${detail}` : "";
+  return new CalcAgentHttpError(
+    answer.status,
+    answer.body,
+    `${method} ${path13}: HTTP ${answer.status}${tail}`
+  );
+}
+function parse2(schema, method, path13, body) {
+  const out = schema.safeParse(body);
+  if (!out.success) {
+    const issues = out.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+    throw new Error(`${method} ${path13}: unexpected response from the server (${issues})`);
+  }
+  return out.data;
+}
+async function postTurn(client, input, options) {
+  const path13 = `${BASE3}/turns`;
+  const payload = { message: input.message };
+  if (input.conversationId !== void 0) payload["conversation_id"] = input.conversationId;
+  const answer = await send(client, "POST", path13, payload, options);
+  if (answer.status === 202) return parse2(calcAgentTurnAcceptedSchema, "POST", path13, answer.body);
+  if (answer.status === 404 && input.conversationId !== void 0) {
+    throw httpError(
+      "POST",
+      path13,
+      answer,
+      `conversation ${input.conversationId} not found (only the user who started it can continue it)`
+    );
+  }
+  throw httpError("POST", path13, answer);
+}
+async function getPreview2(client, operationId, options) {
+  const path13 = `${BASE3}/preview/${encodeURIComponent(operationId)}`;
+  const answer = await send(client, "GET", path13, void 0, options);
+  if (answer.status === 200) return parse2(calcAgentPreviewSchema, "GET", path13, answer.body);
+  if (answer.status === 404) {
+    throw httpError(
+      "GET",
+      path13,
+      answer,
+      `operation ${operationId} not found (only the user who started the turn can read it)`
+    );
+  }
+  throw httpError("GET", path13, answer);
+}
+async function save2(client, input, options) {
+  const payload = {
+    preview_operation_id: input.operationId,
+    name: input.name
+  };
+  if (input.calcModelId !== void 0) payload["calc_model_id"] = input.calcModelId;
+  const answer = await send(client, "POST", BASE3, payload, options);
+  if (answer.status === 201) return parse2(calcAgentSaveResultSchema, "POST", BASE3, answer.body);
+  throw httpError("POST", BASE3, answer);
+}
+async function requestApprovalImpact(client, calcModelId, options) {
+  const path13 = `${BASE3}/${calcModelId}/approve`;
+  const answer = await send(client, "POST", path13, {}, options);
+  if (answer.status >= 200 && answer.status < 300) {
+    throw new Error(
+      `POST ${path13}: HTTP ${answer.status} to a request without an acknowledgment; expected ${APPROVAL_ACK_REQUIRED}. Check the model with \`dr calcmodels get ${calcModelId}\`.`
+    );
+  }
+  if (answer.status === 400 && textField(answer.body, "code") === APPROVAL_ACK_REQUIRED) {
+    return parse2(calcAgentApprovalPlanSchema, "POST", path13, answer.body);
+  }
+  throw httpError("POST", path13, answer);
+}
+async function confirmApproval(client, calcModelId, versionId, options) {
+  const path13 = `${BASE3}/${calcModelId}/approve`;
+  const answer = await send(
+    client,
+    "POST",
+    path13,
+    { acknowledged: true, version_id: versionId },
+    options
+  );
+  if (answer.status === 200) return parse2(calcAgentApproveResultSchema, "POST", path13, answer.body);
+  throw httpError("POST", path13, answer);
+}
+
+// src/commands/_agentCli.ts
+import { access } from "fs/promises";
+var JSON_HELP = "Emit raw JSON to stdout instead of a pretty render.";
+var CONFIRM_HELP = "Token from a prior plan run \u2014 required to actually write";
+function withTarget(cmd) {
+  addServerFlag(cmd);
+  addAccountFlag(cmd);
+  return cmd;
+}
+function std() {
+  return { out: process.stdout, err: process.stderr };
+}
+function requireId(value, placeholder) {
+  const id = (value ?? "").trim();
+  if (id === "") {
+    throw new Error(`missing required option: --id ${placeholder}`);
+  }
+  return id;
+}
+function requirePositiveInt(value, flag) {
+  const n = /^\d+$/.test(value) ? Number(value) : NaN;
+  if (!Number.isSafeInteger(n) || n <= 0) {
+    throw new Error(`${flag} ${JSON.stringify(value)}: expected a positive integer`);
+  }
+  return n;
+}
+function requireBool(value, flag) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`${flag} ${JSON.stringify(value ?? "")}: expected true or false`);
+}
+function splitList(value) {
+  return [
+    ...new Set(
+      (value ?? "").split(",").map((part) => part.trim()).filter((part) => part !== "")
+    )
+  ];
+}
+function isNoneSentinel(parts, flag, value, what) {
+  if (!parts.includes("none")) return false;
+  if (parts.length === 1) return true;
+  throw new Error(`${flag} ${JSON.stringify(value)}: "none" cannot be combined with ${what}`);
+}
+function shellArg(value) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
+}
+function proseStream(cfg) {
+  return cfg.asJson ? cfg.err : cfg.out;
+}
+async function assertNoOverwrite(paths, force) {
+  if (force) return;
+  const existing = [];
+  for (const path13 of paths) {
+    try {
+      await access(path13);
+      existing.push(path13);
+    } catch {
+    }
+  }
+  if (existing.length > 0) {
+    throw new Error(
+      `refusing to overwrite existing file(s): ${existing.join(", ")}. Pull into another --dir, or pass --force to replace them.`
+    );
+  }
+}
+
+// src/commands/calcmodelsAgent.ts
+var AGENT_POLL_INTERVAL_MS = 3e3;
+var AGENT_DEFAULT_TIMEOUT_S = 900;
+var MAX_TRANSIENT_READ_FAILURES = 5;
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function parseOperationIdArg(raw2) {
+  if (!UUID_RE2.test(raw2)) throw new Error(`invalid operation id: "${raw2}" (expected a UUID)`);
+  return raw2.toLowerCase();
+}
+function isLive(p) {
+  return p.status === "PENDING" || p.status === "RUNNING";
+}
+function formatNumber(n) {
+  return n === null || n === void 0 ? "n/a" : n.toLocaleString("en-US", { maximumFractionDigits: 2 });
+}
+function previewLine(result) {
+  const parts = [`${formatNumber(result.total_count)} rows`];
+  const cov = result.coverage;
+  if (cov) {
+    const pct2 = cov.pct === null || cov.pct === void 0 ? "n/a" : `${formatNumber(cov.pct)}%`;
+    parts.push(
+      `coverage ${pct2} (allocated ${formatNumber(cov.allocated_total)} of pool ${formatNumber(cov.pool_total)})`
+    );
+  }
+  const checks = result.balance_checks ?? [];
+  if (checks.length > 0) {
+    const ok = checks.filter((c) => c.ok).length;
+    parts.push(`balance: ${ok} of ${checks.length} groups net to zero`);
+  }
+  return `preview: ${parts.join(" \xB7 ")}`;
+}
+function previewCmd(operationId, serverFlag) {
+  return `dr calcmodels agent preview ${operationId} --server ${serverFlag}`;
+}
+function renderPreview(out, p, operationId, serverFlag) {
+  out.write(`status: ${p.status}
+`);
+  if (p.conversation_id) out.write(`conversation: ${escapeControlChars(p.conversation_id)}
+`);
+  if (isLive(p)) {
+    out.write(
+      `
+The turn is still running. Check again with:
+  ${previewCmd(operationId, serverFlag)}
+`
+    );
+    return;
+  }
+  if (p.answer_text) out.write(`
+${escapeControlChars(p.answer_text.trim())}
+`);
+  if (p.changes_summary) {
+    out.write("\nchanges:\n");
+    for (const line of p.changes_summary.trim().split("\n"))
+      out.write(`  ${escapeControlChars(line)}
+`);
+  }
+  const savable = p.status === "SUCCEEDED" && p.result !== null && p.result !== void 0;
+  if (p.status === "SUCCEEDED") {
+    const d = p.definition;
+    if (d) {
+      out.write(
+        `
+proposal: ${escapeControlChars(JSON.stringify(d.name ?? ""))} (${escapeControlChars(d.model_type ?? "unknown")}) \u2192 destination table ${d.destination_template_id ?? "n/a"}
+`
+      );
+    }
+    if (p.result) {
+      out.write(`${previewLine(p.result)}
+`);
+      for (const w of p.result.warnings ?? []) {
+        const label = [w.code, w.message].filter((s) => !!s).join(": ");
+        if (label !== "") out.write(`warning: ${escapeControlChars(label)}
+`);
+      }
+    } else {
+      out.write(
+        "preview: none ran. The server saves only a turn whose preview ran (CALC_PREVIEW_NOT_READY).\n"
+      );
+    }
+  }
+  const next = [];
+  if (savable) {
+    next.push(`save the draft: dr calcmodels agent save ${operationId} --server ${serverFlag}`);
+  }
+  if (p.conversation_id) {
+    next.push(
+      `reply:          dr calcmodels agent ask '<reply>' --conversation ${shellQuote(p.conversation_id)} --server ${serverFlag}`
+    );
+  }
+  if (next.length > 0) out.write(`
+next:
+${next.map((l) => `  ${l}
+`).join("")}`);
+}
+function writeOutcome(out, p, operationId, serverFlag, asJson) {
+  if (asJson) writeJSONIndented(out, { operation_id: operationId, ...p });
+  else renderPreview(out, p, operationId, serverFlag);
+  if (p.status === "FAILED") {
+    const why = p.error ? escapeControlChars(describeServerError(p.error)) : "the server gave no error detail";
+    throw new Error(`turn ${operationId} failed: ${why}`);
+  }
+}
+var ReadTimeoutError = class extends Error {
+  constructor(operationId, ms) {
+    super(`reading operation ${operationId} took longer than ${ms} ms`);
+    this.name = "ReadTimeoutError";
+  }
+};
+function isTransient(err) {
+  if (err instanceof ReadTimeoutError) return true;
+  if (err instanceof CalcAgentHttpError) return err.status >= 500;
+  return err instanceof TypeError;
+}
+var AGENT_READ_TIMEOUT_MS = 3e4;
+var AGENT_READ_TIMEOUT_FLOOR_MS = 5e3;
+var defaultSleep8 = (ms, signal) => delay(ms, void 0, { signal });
+async function runAgentAsk(cfg) {
+  const accepted = await postTurn(
+    cfg.client,
+    {
+      message: cfg.message,
+      ...cfg.conversationId !== void 0 && { conversationId: cfg.conversationId }
+    },
+    { signal: cfg.signal }
+  );
+  const op = accepted.operation_id;
+  const conv = accepted.conversation_id;
+  cfg.err.write(
+    `turn started: operation ${op}${conv ? `, conversation ${escapeControlChars(conv)}` : ""}
+`
+  );
+  if (!cfg.wait) {
+    if (cfg.asJson) {
+      writeJSONIndented(cfg.out, accepted);
+      return;
+    }
+    cfg.out.write(`operation: ${op}
+Read it with:
+  ${previewCmd(op, cfg.serverFlag)}
+`);
+    return;
+  }
+  cfg.err.write(
+    `Waiting for the agent. Ctrl-C stops the wait, not the turn; resume with:
+  ${previewCmd(op, cfg.serverFlag)}
+`
+  );
+  const preview2 = await pollPreview(cfg, op);
+  writeOutcome(cfg.out, preview2, op, cfg.serverFlag, cfg.asJson);
+}
+async function pollPreview(cfg, operationId) {
+  const interval = cfg.pollIntervalMs ?? AGENT_POLL_INTERVAL_MS;
+  const sleep3 = cfg.sleep ?? defaultSleep8;
+  const now = cfg.now ?? Date.now;
+  const deadline = now() + cfg.timeoutMs;
+  const readMax = cfg.readTimeoutMs ?? AGENT_READ_TIMEOUT_MS;
+  const readFloor = cfg.readTimeoutFloorMs ?? AGENT_READ_TIMEOUT_FLOOR_MS;
+  let failures = 0;
+  for (; ; ) {
+    await sleep3(Math.max(0, Math.min(interval, deadline - now())), cfg.signal);
+    try {
+      const budget = Math.min(readMax, Math.max(deadline - now(), readFloor));
+      const p = await readWithin(cfg, operationId, budget);
+      failures = 0;
+      if (!isLive(p)) return p;
+    } catch (err) {
+      failures += 1;
+      if (!isTransient(err)) throw err;
+      if (failures > MAX_TRANSIENT_READ_FAILURES && now() < deadline) throw err;
+    }
+    if (now() >= deadline) {
+      throw new Error(
+        `turn ${operationId} is still running after ${Math.round(cfg.timeoutMs / 1e3)}s. It keeps running on the server; read it with: ${previewCmd(operationId, cfg.serverFlag)}`
+      );
+    }
+  }
+}
+async function readWithin(cfg, operationId, budgetMs) {
+  const ctl = new AbortController();
+  const relay = () => ctl.abort(cfg.signal.reason);
+  if (cfg.signal.aborted) relay();
+  else cfg.signal.addEventListener("abort", relay, { once: true });
+  const timer = setTimeout(() => ctl.abort(), budgetMs);
+  try {
+    return await getPreview2(cfg.client, operationId, { signal: ctl.signal });
+  } catch (err) {
+    if (ctl.signal.aborted && !cfg.signal.aborted)
+      throw new ReadTimeoutError(operationId, budgetMs);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+    cfg.signal.removeEventListener("abort", relay);
+  }
+}
+async function runAgentPreview(cfg) {
+  const p = await getPreview2(cfg.client, cfg.operationId, { signal: cfg.signal });
+  writeOutcome(cfg.out, p, cfg.operationId, cfg.serverFlag, cfg.asJson);
+}
+var PREVIEW_ALREADY_SAVED = "CALC_PREVIEW_ALREADY_SAVED";
+var VERSION_CHANGED = "CALC_APPROVAL_VERSION_CHANGED";
+async function runAgentSave(cfg) {
+  let name = cfg.name;
+  if (name !== void 0 && name.trim() === "") throw new Error("--name must not be empty");
+  if (name === void 0) {
+    const p = await getPreview2(cfg.client, cfg.operationId, { signal: cfg.signal });
+    name = p.definition?.name ?? void 0;
+    if (name === void 0 || name.trim() === "") {
+      throw new Error(
+        `--name is required: operation ${cfg.operationId} has no proposed name (status ${p.status})`
+      );
+    }
+  }
+  let saved;
+  try {
+    saved = await save2(
+      cfg.client,
+      {
+        operationId: cfg.operationId,
+        name,
+        ...cfg.calcModelId !== void 0 && { calcModelId: cfg.calcModelId }
+      },
+      { signal: cfg.signal }
+    );
+  } catch (err) {
+    if (err instanceof CalcAgentHttpError && err.code === PREVIEW_ALREADY_SAVED) {
+      const modelId = err.numberField("calc_model_id");
+      if (modelId !== void 0) {
+        throw new Error(
+          `${err.message}. To add this turn as a new version of model ${modelId}: dr calcmodels agent save ${cfg.operationId} --model ${modelId} --server ${cfg.serverFlag}`,
+          { cause: err }
+        );
+      }
+    }
+    throw err;
+  }
+  if (cfg.asJson) {
+    writeJSONIndented(cfg.out, saved);
+    return;
+  }
+  cfg.out.write(
+    `Saved draft calc model ${saved.id} ${escapeControlChars(JSON.stringify(saved.name))} (version ${saved.version_id}). This version does not run until it is approved.
+
+next:
+  dr calcmodels agent approve ${saved.id} --server ${cfg.serverFlag}
+`
+  );
+}
+function approveAction(calcModelId, versionId) {
+  return { resource: "calcmodel", id: `${calcModelId}@v${versionId}`, verb: "approve" };
+}
+function versionChanged(calcModelId, planned, current, cause) {
+  const newer = current !== void 0 ? ` (${current})` : "";
+  return new Error(
+    `calc model ${calcModelId}: a newer version${newer} was saved after the plan for version ${planned}. Review it: re-run without --confirm-token. Nothing was activated.`,
+    cause === void 0 ? void 0 : { cause }
+  );
+}
+function impactLines(calcModelId, plan) {
+  const i = plan.impact;
+  const pct2 = i.coverage_pct === null || i.coverage_pct === void 0 ? "n/a" : `${formatNumber(i.coverage_pct)}%`;
+  return [
+    `calc model: ${calcModelId}`,
+    `version: ${plan.version_id}`,
+    `rows the first run writes: ${formatNumber(i.total_rows)}`,
+    `allocated total: ${formatNumber(i.allocated_total)} of pool total ${formatNumber(i.pool_total)} (coverage ${pct2})`,
+    "Approving activates this version and starts its first production run at once."
+  ];
+}
+async function runAgentApprove(cfg) {
+  const executing = cfg.token !== void 0 && cfg.token.trim() !== "";
+  if (executing && cfg.versionId === void 0) {
+    throw new Error(
+      "--version-id is required with --confirm-token: copy the command the plan printed"
+    );
+  }
+  if (executing) await preflightConfirmToken(approveAction(cfg.id, cfg.versionId), cfg.token);
+  const plan = await requestApprovalImpact(cfg.client, cfg.id, { signal: cfg.signal });
+  if (executing && plan.version_id !== cfg.versionId) {
+    throw versionChanged(cfg.id, cfg.versionId, plan.version_id);
+  }
+  const versionId = executing ? cfg.versionId : plan.version_id;
+  await twoStepConfirm({
+    out: cfg.out,
+    action: approveAction(cfg.id, versionId),
+    token: cfg.token,
+    server: cfg.serverFlag,
+    confirmCmd: `dr calcmodels agent approve ${cfg.id} --version-id ${versionId} --server ${cfg.serverFlag}${cfg.asJson ? " --json" : ""}`,
+    describe: () => Promise.resolve(impactLines(cfg.id, plan)),
+    execute: async () => {
+      let result;
+      try {
+        result = await confirmApproval(cfg.client, cfg.id, versionId, {
+          signal: cfg.signal
+        });
+      } catch (err) {
+        if (err instanceof CalcAgentHttpError && err.code === VERSION_CHANGED) {
+          throw versionChanged(cfg.id, versionId, err.numberField("version_id"), err);
+        }
+        throw err;
+      }
+      if (cfg.asJson) {
+        writeJSONIndented(cfg.out, result);
+        return;
+      }
+      const run2 = result.run_id ? `First run: ${escapeControlChars(result.run_id)}.` : `No run was started: the model is not runnable now. Check it with dr calcmodels get ${cfg.id} --server ${cfg.serverFlag}.`;
+      cfg.out.write(`Activated calc model ${cfg.id} (version ${versionId}). ${run2}
+`);
+    }
+  });
+}
+var ASK_SETUP_HEADROOM_MS = 6e4;
+function registerCalcmodelsAgentCommand(cm) {
+  const agent = cm.command("agent").description(
+    "Build an AGENT (allocation) calc model with the builder agent \u2014 the web builder endpoints. Super Admin + the calc_model_agent_builder flag."
+  );
+  const askCmd = agent.command("ask").description(
+    "Send one message to the builder agent and wait for its answer. Ctrl-C stops the wait, not the turn."
+  ).argument("<message>", "what to build, or a reply to the agent").option("--conversation <id>", "continue this conversation (from a previous answer)").option("--no-wait", "return after the server accepts the turn; read it with `preview`").option(
+    "--timeout <seconds>",
+    `stop waiting after this long (default ${AGENT_DEFAULT_TIMEOUT_S})`
+  ).option("--json", "Output raw JSON", false).action(
+    async (message, opts) => {
+      if (message.trim() === "") throw new Error("<message> must not be empty");
+      const timeoutMs = parsePositiveSecondsFlag(
+        opts.timeout,
+        "--timeout",
+        AGENT_DEFAULT_TIMEOUT_S * 1e3
+      );
+      const serverKey = resolveServer(opts.server);
+      const setup = await setupCall(opts.server, opts.account, {
+        timeoutMs: timeoutMs + ASK_SETUP_HEADROOM_MS
+      });
+      try {
+        await runAgentAsk({
+          client: setup.client,
+          message,
+          ...opts.conversation !== void 0 && { conversationId: opts.conversation },
+          wait: opts.wait !== false,
+          timeoutMs,
+          asJson: opts.json === true,
+          serverFlag: serverKey,
+          signal: setup.signal,
+          out: process.stdout,
+          err: process.stderr
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(askCmd);
+  addAccountFlag(askCmd);
+  const previewCmdDef = agent.command("preview").description("Read one turn: the agent's answer, its proposal, and the preview figures").argument("<operation_id>", "the operation id `ask` printed").option("--json", "Output raw JSON", false).action(async (opArg, opts) => {
+    const operationId = parseOperationIdArg(opArg);
+    const serverKey = resolveServer(opts.server);
+    const setup = await setupCall(opts.server, opts.account);
+    try {
+      await runAgentPreview({
+        client: setup.client,
+        operationId,
+        asJson: opts.json === true,
+        serverFlag: serverKey,
+        signal: setup.signal,
+        out: process.stdout
+      });
+    } finally {
+      setup.cleanup();
+    }
+  });
+  addServerFlag(previewCmdDef);
+  addAccountFlag(previewCmdDef);
+  const saveCmd = agent.command("save").description("Save a succeeded turn as a DRAFT calc model. Nothing runs until `approve`.").argument("<operation_id>", "the operation id of a SUCCEEDED turn").option("--name <name>", "model name (default: the agent's proposed name)").option("--model <calc_model_id>", "add this turn as a new version of an existing AGENT model").option("--json", "Output raw JSON", false).action(async (opArg, opts) => {
+    const operationId = parseOperationIdArg(opArg);
+    const calcModelId = opts.model === void 0 ? void 0 : requirePositiveInt(opts.model, "--model");
+    const serverKey = resolveServer(opts.server);
+    const setup = await setupCall(opts.server, opts.account);
+    try {
+      await runAgentSave({
+        client: setup.client,
+        operationId,
+        ...opts.name !== void 0 && { name: opts.name },
+        ...calcModelId !== void 0 && { calcModelId },
+        asJson: opts.json === true,
+        serverFlag: serverKey,
+        signal: setup.signal,
+        out: process.stdout
+      });
+    } finally {
+      setup.cleanup();
+    }
+  });
+  addServerFlag(saveCmd);
+  addAccountFlag(saveCmd);
+  const approveCmd = agent.command("approve").description(
+    "Activate an AGENT model's newest version and start its first production run (two-step confirm; a person confirms on production)."
+  ).argument("<calc_model_id>", "the model id `save` printed").option("--version-id <n>", "the version the plan showed (required with --confirm-token)").option("--confirm-token <token>", "Token from a prior plan run \u2014 required to activate", "").option("--json", "Output raw JSON of the activation", false).action(
+    async (idArg, opts) => {
+      const id = requirePositiveInt(idArg, "<calc_model_id>");
+      const versionId = opts.versionId === void 0 ? void 0 : requirePositiveInt(opts.versionId, "--version-id");
+      const token = opts.confirmToken;
+      if (token !== void 0 && token.trim() !== "") {
+        if (versionId === void 0) {
+          throw new Error(
+            "--version-id is required with --confirm-token: copy the command the plan printed"
+          );
+        }
+        await preflightConfirmToken(approveAction(id, versionId), token);
+      }
+      const serverKey = resolveServer(opts.server);
+      const setup = await setupCall(opts.server, opts.account);
+      try {
+        await runAgentApprove({
+          client: setup.client,
+          id,
+          ...versionId !== void 0 && { versionId },
+          token,
+          asJson: opts.json === true,
+          serverFlag: serverKey,
+          signal: setup.signal,
+          out: process.stdout
+        });
+      } finally {
+        setup.cleanup();
+      }
+    }
+  );
+  addServerFlag(approveCmd);
+  addAccountFlag(approveCmd);
+}
+
 // src/commands/calcmodels.ts
 async function runCalcmodelsList(cfg) {
   const models = await list25(cfg.client, { signal: cfg.signal });
@@ -65891,6 +66634,7 @@ function registerCalcmodelsCommand(root) {
   });
   addServerFlag(deleteCmd);
   addAccountFlag(deleteCmd);
+  registerCalcmodelsAgentCommand(cm);
 }
 
 // src/commands/calcVals.ts
@@ -68875,13 +69619,13 @@ import { promises as fsPromises3 } from "fs";
 import * as nodePath3 from "path";
 
 // src/api/spendControl.ts
-var BASE3 = "/api/spend-control/v1";
+var BASE4 = "/api/spend-control/v1";
 var BASE_V2 = "/api/spend-control/v2";
 var MAX_BULK_STATUS_IDS = 50;
 var MAX_PAGE_SIZE = 100;
 async function listBillingFrequencies(client, options) {
   const out = await client.getJSON(
-    `${BASE3}/catalogs/billing-frequencies/`,
+    `${BASE4}/catalogs/billing-frequencies/`,
     options
   );
   return out ?? [];
@@ -68915,7 +69659,7 @@ function buildContractListQuery(params) {
 }
 async function listContracts(client, params = {}, options) {
   const qs = buildContractListQuery(params);
-  const path13 = qs === "" ? `${BASE3}/contracts/` : `${BASE3}/contracts/?${qs}`;
+  const path13 = qs === "" ? `${BASE4}/contracts/` : `${BASE4}/contracts/?${qs}`;
   const out = await client.getJSON(path13, options);
   if (out === null) {
     return { items: [], total: 0, page: null, size: null, pages: null };
@@ -68943,10 +69687,10 @@ async function getContract(client, contractId, params = {}, options) {
     qs.set("currency_code", params.convertTo);
   }
   const suffix = qs.toString() === "" ? "" : `?${qs.toString()}`;
-  return client.getJSON(`${BASE3}/contracts/${contractId}${suffix}`, options);
+  return client.getJSON(`${BASE4}/contracts/${contractId}${suffix}`, options);
 }
 async function deleteContract(client, contractId, options) {
-  await client.deleteJSON(`${BASE3}/contracts/${contractId}`, options);
+  await client.deleteJSON(`${BASE4}/contracts/${contractId}`, options);
 }
 async function uploadFilesWithAi(client, files, options = {}) {
   if (files.length === 0) return [];
@@ -68954,7 +69698,7 @@ async function uploadFilesWithAi(client, files, options = {}) {
     throw new Error(`uploadFilesWithAi: max 10 files per call, got ${files.length}`);
   }
   const out = await client.postMultipartFiles(
-    `${BASE3}/contracts/files-with-ai`,
+    `${BASE4}/contracts/files-with-ai`,
     { is_additional: options.isAdditional === true ? "true" : "false" },
     files,
     "files",
@@ -68964,7 +69708,7 @@ async function uploadFilesWithAi(client, files, options = {}) {
 }
 async function uploadContractFile(client, file, options = {}) {
   return client.postMultipartFiles(
-    `${BASE3}/contracts/file`,
+    `${BASE4}/contracts/file`,
     { is_additional: options.isAdditional === true ? "true" : "false" },
     [file],
     "file",
@@ -68977,7 +69721,7 @@ async function listContractFiles(client, contractId, params = {}, options) {
   if (params.size !== void 0) qs.set("size", String(params.size));
   const suffix = qs.toString() === "" ? "" : `?${qs.toString()}`;
   const out = await client.getJSON(
-    `${BASE3}/contracts/${contractId}/files${suffix}`,
+    `${BASE4}/contracts/${contractId}/files${suffix}`,
     options
   );
   if (out === null) {
@@ -69003,13 +69747,13 @@ async function listAllContractFiles(client, contractId, options) {
 }
 async function getContractFileDownload(client, fileId, options) {
   return client.postJSON(
-    `${BASE3}/contracts/files/${fileId}/download`,
+    `${BASE4}/contracts/files/${fileId}/download`,
     {},
     options
   );
 }
 async function deleteContractFile(client, fileId, options) {
-  await client.deleteJSON(`${BASE3}/contracts/files/${fileId}`, options);
+  await client.deleteJSON(`${BASE4}/contracts/files/${fileId}`, options);
 }
 async function uploadFileWithAiAsync(client, file, options = {}) {
   return client.postMultipartFiles(
@@ -69045,7 +69789,7 @@ var EXTRACT_POLL_TIMEOUT_MS = 10 * 60 * 1e3;
 function isTerminalAiStatus(status2) {
   return status2 === "PROCESSED" || status2 === "FAILED";
 }
-async function defaultSleep8(ms, signal) {
+async function defaultSleep9(ms, signal) {
   if (signal?.aborted === true) return;
   await new Promise((resolve3) => {
     const timer = setTimeout(resolve3, ms);
@@ -69062,7 +69806,7 @@ async function defaultSleep8(ms, signal) {
 async function pollExtractionStatus(client, contractFileIds, options = {}) {
   const interval = options.pollIntervalMs ?? EXTRACT_POLL_INTERVAL_MS;
   const timeout = options.timeoutMs ?? EXTRACT_POLL_TIMEOUT_MS;
-  const sleep3 = options.sleep ?? defaultSleep8;
+  const sleep3 = options.sleep ?? defaultSleep9;
   const now = options.now ?? Date.now;
   const resolved = /* @__PURE__ */ new Map();
   if (contractFileIds.length === 0) return { resolved, pending: [] };
@@ -69129,14 +69873,14 @@ async function bulkCreateContracts(client, body, options) {
     throw new Error(`bulkCreateContracts: max 10 contracts per call, got ${body.contracts.length}`);
   }
   const out = await client.postJSON(
-    `${BASE3}/contracts/bulk-create`,
+    `${BASE4}/contracts/bulk-create`,
     body,
     options
   );
   return out ?? { contracts: [] };
 }
 async function partialUpdateContract(client, contractId, body, options) {
-  return client.patchJSON(`${BASE3}/contracts/${contractId}`, body, options);
+  return client.patchJSON(`${BASE4}/contracts/${contractId}`, body, options);
 }
 
 // src/types/spendControl.ts
@@ -69556,7 +70300,7 @@ function chunkContracts(contracts, size = 10) {
 }
 
 // src/api/spendControlVendors.ts
-var BASE4 = "/api/spend-control/v1/vendors";
+var BASE5 = "/api/spend-control/v1/vendors";
 var MAX_PAGE_SIZE2 = 100;
 function buildVendorListQuery(params) {
   const qs = new URLSearchParams();
@@ -69587,19 +70331,19 @@ function emptyPage() {
   return { items: [], total: 0, page: null, size: null, pages: null };
 }
 async function listVendors(client, params = {}, options) {
-  const out = await client.getJSON(withQuery(`${BASE4}/`, params), options);
+  const out = await client.getJSON(withQuery(`${BASE5}/`, params), options);
   return out ?? emptyPage();
 }
 async function listAppStoreVendors(client, params = {}, options) {
   const out = await client.getJSON(
-    withQuery(`${BASE4}/app-store`, params),
+    withQuery(`${BASE5}/app-store`, params),
     options
   );
   return out ?? emptyPage();
 }
 async function listVendorsWithContracts(client, params = {}, options) {
   const out = await client.getJSON(
-    withQuery(`${BASE4}/with-contracts`, params),
+    withQuery(`${BASE5}/with-contracts`, params),
     options
   );
   return out ?? emptyPage();
@@ -69616,24 +70360,24 @@ async function listAllVendors(fetchPage, client, params = {}, options) {
   return collected;
 }
 async function listVendorCategories(client, options) {
-  const out = await client.getJSON(`${BASE4}/categories`, options);
+  const out = await client.getJSON(`${BASE5}/categories`, options);
   return out ?? [];
 }
 async function listVendorsWithMultipleContracts(client, options) {
-  const out = await client.getJSON(`${BASE4}/with-multiple-contracts`, options);
+  const out = await client.getJSON(`${BASE5}/with-multiple-contracts`, options);
   return out ?? [];
 }
 async function getVendorOwners(client, vendorId, options) {
-  return client.getJSON(`${BASE4}/${encodeURIComponent(vendorId)}/owners/`, options);
+  return client.getJSON(`${BASE5}/${encodeURIComponent(vendorId)}/owners/`, options);
 }
 async function createVendor(client, name, options) {
-  return client.postJSON(`${BASE4}/`, { name }, options);
+  return client.postJSON(`${BASE5}/`, { name }, options);
 }
 async function bulkUpdateVendorVisibility(client, vendors, options) {
   if (vendors.length === 0) {
     throw new Error("bulkUpdateVendorVisibility: at least one vendor is required");
   }
-  const out = await client.patchJSON(`${BASE4}/visibility`, { vendors }, options);
+  const out = await client.patchJSON(`${BASE5}/visibility`, { vendors }, options);
   return out ?? [];
 }
 
@@ -74746,103 +75490,37 @@ import { promises as fs36 } from "fs";
 import { Option as Option4 } from "commander";
 
 // src/api/templateLibrary.ts
-var BASE5 = "/api/report_library/management";
+var BASE6 = "/api/report_library/management";
 async function list28(client, options) {
-  return await client.getJSON(BASE5, options) ?? [];
+  return await client.getJSON(BASE6, options) ?? [];
 }
 async function create19(client, body, options) {
-  const out = await client.postJSON(BASE5, body, options);
+  const out = await client.postJSON(BASE6, body, options);
   if (out === null) {
-    throw new Error(`unexpected empty response from POST ${BASE5}`);
+    throw new Error(`unexpected empty response from POST ${BASE6}`);
   }
   return out;
 }
 async function update12(client, id, body, options) {
-  const out = await client.putJSON(`${BASE5}/${id}`, body, options);
+  const out = await client.putJSON(`${BASE6}/${id}`, body, options);
   if (out === null) {
-    throw new Error(`unexpected empty response from PUT ${BASE5}/${id}`);
+    throw new Error(`unexpected empty response from PUT ${BASE6}/${id}`);
   }
   return out;
 }
 async function uploadImage(client, id, png, filename, options) {
   const out = await client.putMultipart(
-    `${BASE5}/${id}`,
+    `${BASE6}/${id}`,
     {},
     new Blob([png], { type: "image/png" }),
     { ...options, fileFieldName: "image", filename }
   );
   if (out === null) {
-    throw new Error(`unexpected empty response from PUT ${BASE5}/${id} (image)`);
+    throw new Error(`unexpected empty response from PUT ${BASE6}/${id} (image)`);
   }
   return out;
 }
 
-// src/commands/_agentCli.ts
-import { access } from "fs/promises";
-var JSON_HELP = "Emit raw JSON to stdout instead of a pretty render.";
-var CONFIRM_HELP = "Token from a prior plan run \u2014 required to actually write";
-function withTarget(cmd) {
-  addServerFlag(cmd);
-  addAccountFlag(cmd);
-  return cmd;
-}
-function std() {
-  return { out: process.stdout, err: process.stderr };
-}
-function requireId(value, placeholder) {
-  const id = (value ?? "").trim();
-  if (id === "") {
-    throw new Error(`missing required option: --id ${placeholder}`);
-  }
-  return id;
-}
-function requirePositiveInt(value, flag) {
-  const n = /^\d+$/.test(value) ? Number(value) : NaN;
-  if (!Number.isSafeInteger(n) || n <= 0) {
-    throw new Error(`${flag} ${JSON.stringify(value)}: expected a positive integer`);
-  }
-  return n;
-}
-function requireBool(value, flag) {
-  if (value === "true") return true;
-  if (value === "false") return false;
-  throw new Error(`${flag} ${JSON.stringify(value ?? "")}: expected true or false`);
-}
-function splitList(value) {
-  return [
-    ...new Set(
-      (value ?? "").split(",").map((part) => part.trim()).filter((part) => part !== "")
-    )
-  ];
-}
-function isNoneSentinel(parts, flag, value, what) {
-  if (!parts.includes("none")) return false;
-  if (parts.length === 1) return true;
-  throw new Error(`${flag} ${JSON.stringify(value)}: "none" cannot be combined with ${what}`);
-}
-function shellArg(value) {
-  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : shellQuote(value);
-}
-function proseStream(cfg) {
-  return cfg.asJson ? cfg.err : cfg.out;
-}
-async function assertNoOverwrite(paths, force) {
-  if (force) return;
-  const existing = [];
-  for (const path13 of paths) {
-    try {
-      await access(path13);
-      existing.push(path13);
-    } catch {
-    }
-  }
-  if (existing.length > 0) {
-    throw new Error(
-      `refusing to overwrite existing file(s): ${existing.join(", ")}. Pull into another --dir, or pass --force to replace them.`
-    );
-  }
-}
-
 // src/commands/_templateLibraryImages.ts
 var TEMPLATE_LIBRARY_IMAGE_COLORS = ["pink", "purple", "yellow"];
 var TEMPLATE_LIBRARY_IMAGE_FILENAMES = {
@@ -75699,11 +76377,11 @@ import { mkdir as mkdir5, writeFile as writeFile8 } from "fs/promises";
 import { join as join18 } from "path";
 
 // src/api/aiService.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var AI_SERVICE_MINT_PATH = "/api/ai-service/v1/Authentication/authenticate";
 var ERROR_BODY_MAX_CHARS = 1e3;
-var MintResponseSchema = z3.object({ token: z3.string().min(1) });
-var ErrorEnvelopeSchema = z3.object({ code: z3.string(), message: z3.string() });
+var MintResponseSchema = z4.object({ token: z4.string().min(1) });
+var ErrorEnvelopeSchema = z4.object({ code: z4.string(), message: z4.string() });
 function parseErrorEnvelope(text2) {
   let parsed2;
   try {

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.179",
+  "cliVersion": "1.6.181",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {
@@ -4089,6 +4089,38 @@
         }
       ]
     },
+    "calcmodels agent ask": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "write"
+        }
+      ]
+    },
+    "calcmodels agent preview": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "read"
+        }
+      ]
+    },
+    "calcmodels agent save": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "write"
+        }
+      ]
+    },
+    "calcmodels agent approve": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "destructive"
+        }
+      ]
+    },
     "calc-vals list": {
       "requires": [
         {

package/dist/skills/dr-cli/SKILL.md

@@ -233,6 +233,7 @@ area's gotchas.
 
 **Calc models** → [reference/calcmodels.md](reference/calcmodels.md)
 - `calcmodels list|get|create|update|set-flow|recalculate|delete` (alias `calc-models`)
+- `calcmodels agent ask|preview|save|approve` — build an AGENT (allocation) model with the builder agent; `approve` is Tier A
 
 **Calculated values (per-table)** → [reference/calc-vals.md](reference/calc-vals.md)
 - `calc-vals list|get|create|update|delete` (alias `calcvals`) — `--table <id>` required on every subcommand

package/dist/skills/dr-cli/reference/calcmodels.md

@@ -69,6 +69,60 @@ names to integer IDs against the tenant — never ask the operator for IDs:
 For `update`: `dr calcmodels get <id> --server <S> --json` → splice the requested
 change → write to a tmpfile → `dr calcmodels update <id> --file <tmpfile> --server <S>`.
 
+## AGENT models (builder)
+
+An AGENT model is an allocation model that the calc model builder's agent writes
+from plain English. `dr calcmodels agent` uses the web builder's endpoints. The
+server allows it only for a Super Admin, on an org with the
+`calc_model_agent_builder` flag, inside a per-org cap on running turns. The CLI
+does not check these; it prints the server's 403 or 429. `create`/`update` above
+are for the three older types only.
+
+Flow:
+
+1. `dr calcmodels agent ask "<what to build>" --server <S>` — one turn. It
+   prints the operation id at once, then waits (3 s polls, default 900 s,
+   `--timeout <s>`). Ctrl-C or the timeout stop the wait only; read the turn
+   later with `dr calcmodels agent preview <operation_id> --server <S>`.
+2. Read the outcome by `status`:
+   - `NO_PROPOSAL` — the agent asks a question. Ask the operator. Do not answer
+     it yourself. Then `dr calcmodels agent ask "<reply>" --conversation <id> --server <S>`,
+     with the conversation id the answer printed.
+   - `SUCCEEDED` — a proposal and its preview: rows, coverage (allocated of
+     pool), balance groups, warnings. Show these to the operator. To change it,
+     reply in the same conversation. "preview: none ran" means it cannot be saved.
+   - `FAILED` — exits non-zero with the gate code, phase and suggestion.
+3. `dr calcmodels agent save <operation_id> [--name <n>] --server <S>` — saves a
+   DRAFT. The name defaults to the agent's proposed name. The new version
+   does not run until it is approved. `--model <id>` adds the turn as a new
+   version of that AGENT model; an active model keeps running its current
+   version until then.
+4. `dr calcmodels agent approve <id> --server <S>` — two-step. The plan prints
+   the version and its impact (rows the first run writes, allocated total,
+   pool total, coverage). Show it to the operator and stop. Run the printed
+   command (`--version-id <n> --confirm-token <t>`) only after the operator
+   gives a clear in-chat "yes" to that version and impact, on every server.
+   Approving activates the version and starts its first production run at once.
+
+Gotchas:
+
+- `approve` is Tier A (see safety.md). On a production server the token run
+  also opens a dialog or terminal prompt where the person types a word; with
+  no interactive channel the binary refuses. On a non-production server the
+  token alone activates, so the operator's in-chat "yes" is the only check.
+- `save` never activates, and `ask`/`save` write no rows to the destination
+  table. Only `approve` starts a run that does.
+- A newer version saved after the plan stops the token run before anything is
+  activated ("a newer version … was saved"). Re-run `approve` without the
+  token and show the new impact.
+- `CALC_PREVIEW_ALREADY_SAVED`: that turn is already model N. The error
+  prints the `save … --model N` command for a new version.
+- `CALC_TURN_RATE_LIMITED` (429): the org has too many running turns. Wait.
+  A 409 means a turn already runs on this conversation.
+- Only the user who started a turn can read or continue it (404 otherwise).
+- Out of scope: opening a saved model's definition for edit (no server read
+  endpoint), archiving AGENT models.
+
 ## Customer-facing docs (KB)
 
 Help Center → **"Getting Data into Datarails"** → Data Management. Find current articles with `dr kb search "calc model beginning balance"` (or

package/dist/skills/dr-cli/reference/safety.md

@@ -21,6 +21,7 @@ Gated commands include: `dashboards delete`, `datamappers delete`,
 `dynamic-ranges delete`, `extables delete`, `functions delete`, `lut delete`,
 `reports delete`, `storyboards delete`, `metrics delete`, `metrics categories
 delete`, `metrics dimensions delete`, `calcmodels delete|set-flow|recalculate`,
+`calcmodels agent approve`,
 `reconciliation filebox delete`, `integrations delete`, `integrations it
 delete`, `devices command-delete`, `validate onboarding session delete`,
 `widgets delete`, `cash rules delete|delete-all|reorder|update`,
@@ -67,6 +68,9 @@ organization at once);
 `agents pin` / `unpin` (decide which agent version customers get on a server; one
 run with `--production` covers every production server, so relay the plan's
 per-server lines — they are also the undo);
+`calcmodels agent approve` (activates an AGENT calc model and starts its first
+production run, which writes new rows; the token is bound to the version whose
+impact the plan printed);
 `error-enrichments import` (replaces every rule on the server, zeroes all
 hits/feedback counters, and reassigns every rule id); and
 `dashboards push --override` / `filebox push --override`. `import` is **not** an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.179",
+  "version": "1.6.181",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@datarails-ai/dr-appspace-cli": "0.12.56",
+    "@datarails-ai/dr-appspace-cli": "0.12.58",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^12.1.0",