@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/_cli/cmd_explain.ts

@@ -310,13 +310,32 @@ function _explain_config(project_root: string, as_json: boolean): number {
     }
     const knobs = resolved_preset.knobs as Dict;
     const cost = isPlainObject(knobs['cost']) ? (knobs['cost'] as Dict) : {};
-    if (Object.keys(cost).length > 0) {
-        print(
-            `  cost caps:    daily $${fmt(cost['daily_max_usd'])} · ` +
-                `weekly $${fmt(cost['weekly_max_usd'])} · ` +
-                `monthly $${fmt(cost['monthly_max_usd'])}`,
-        );
+    const mcp = isPlainObject(knobs['mcp']) ? (knobs['mcp'] as Dict) : {};
+    if (Object.keys(cost).length > 0 || Object.keys(mcp).length > 0) {
+        // These are preset FIGURES, not caps. No reader compares spend with
+        // any of them: `presets.ts` maps the preset to an environment name and
+        // nothing else reads these keys. Calling them "cost caps" told a
+        // reader they bounded something, which is why the label says what they
+        // are — ADR-279 removed the ceilings nobody set, and a figure nobody
+        // enforces is the same error one layer up.
+        print('  preset cost figures (shown, NOT enforced — nothing compares spend with these):');
+        if (Object.keys(cost).length > 0) {
+            print(
+                `    preset:     daily $${fmt(cost['daily_max_usd'])} · ` +
+                    `weekly $${fmt(cost['weekly_max_usd'])} · ` +
+                    `monthly $${fmt(cost['monthly_max_usd'])}`,
+            );
+        }
+        if (Object.keys(mcp).length > 0) {
+            print(
+                `    mcp:        per-call $${fmt(mcp['per_call_max_usd'])} · ` +
+                    `per-session $${fmt(mcp['per_session_max_usd'])}`,
+            );
+        }
     }
+    // The figures that DO bound, beside the ones that do not, so the
+    // difference is visible in one screen rather than inferred.
+    printConfiguredBudgets(print, settings);
     const autonomy = isPlainObject(knobs['autonomy']) ? (knobs['autonomy'] as Dict) : {};
     if (Object.keys(autonomy).length > 0) {
         print(`  autonomy:     default=${fmt(autonomy['default'])}`);
@@ -324,6 +343,52 @@ function _explain_config(project_root: string, as_json: boolean): number {
     return 0;
 }
 
+/**
+ * Print the `cost.budgets` windows that actually bound, and their mode.
+ *
+ * Separate from the preset figures above because the two look alike and mean
+ * opposite things: a preset figure is printed and never read, while a
+ * configured budget is what `scripts/cost/budget.mjs` compares spend against
+ * and what `cost.enforcement: hard-stop` can refuse on. Printing them in one
+ * screen is the point of step 3.5 — a reader who sees only one of the two
+ * cannot tell which kind they are looking at.
+ *
+ * Takes the SAME resolved `settings` the profile/preset lines above already
+ * used (`_explain_config`'s `_load_user_settings(project_root)`), rather than
+ * an independent `load_agent_settings({ cwd: project_root })` call — tried and
+ * reverted: that second call enables the full project-root-to-cwd cascade
+ * (merged with the user-global layer), a DIFFERENT resolution view from the
+ * single project file the profile/preset lines read and from what the actual
+ * enforcing path (`scripts/cost/budget.mjs`, a plain CWD-relative single-file
+ * read with no cascade) compares spend against. Two independent reads of the
+ * same nominal setting can diverge; one shared value cannot.
+ *
+ * `0` and absent both mean unbounded (ADR-279), and the line says so rather
+ * than printing a bare zero that reads like a cap of nothing.
+ */
+export function printConfiguredBudgets(print: (s?: string) => void, settings: unknown): void {
+    const cost = isPlainObject(settings) && isPlainObject((settings as Dict)['cost'])
+        ? ((settings as Dict)['cost'] as Dict)
+        : {};
+    const budgets = isPlainObject(cost['budgets']) ? (cost['budgets'] as Dict) : {};
+    const win = (k: string): string => {
+        const v = budgets[k];
+        return typeof v === 'number' && v > 0 ? `$${String(v)}` : 'unset';
+    };
+    const mode = typeof cost['enforcement'] === 'string' ? cost['enforcement'] : 'advisory';
+    const anySet = ['daily', 'weekly', 'monthly'].some((k) => win(k) !== 'unset');
+    print(
+        `  configured cost.budgets (ENFORCED by the cost preflight when mode is hard-stop):`,
+    );
+    print(
+        `    windows:    daily ${win('daily')} · weekly ${win('weekly')} · ` +
+            `monthly ${win('monthly')}  (mode: ${mode})`,
+    );
+    if (!anySet) {
+        print('    no window is set, so no ceiling on money applies (ADR-279).');
+    }
+}
+
 /** Python `dict.get(k)` → value or None; renders as `str(value)` / `None`. */
 function fmt(value: unknown): string {
     if (value === null || value === undefined) return 'None';
@@ -487,13 +552,6 @@ function _explain_last(
     as_json: boolean,
     quiet: boolean,
 ): number {
-    const settings = _load_user_settings(project_root);
-    const explain_raw = settings['explain'];
-    const explain_cfg = isPlainObject(explain_raw) ? (explain_raw as Dict) : {};
-    if (explain_cfg['enable_last'] === false) {
-        print('explain last disabled by settings (explain.enable_last)');
-        return 0;
-    }
     const target_state = state_file || path.join(project_root, '.work-state.json');
     let trace: Dict;
     try {
@@ -568,7 +626,7 @@ options:
   --quiet              suppress the trailing tip footer
 
 exit codes:
-  0  trace rendered, or disabled by settings (explain.enable_last)
+  0  trace rendered
   1  no recent run found (state file missing or unreadable)
   2  invocation error (bad project root, bad --state-file path)
 `;