space-architect 9.0.0 → 9.1.0

data/lib/space_architect/cli/architect.rb

@@ -4,6 +4,7 @@ require "json"
 require "fileutils"
 require_relative "../jobs_client"
 require_relative "../conversations_client"
+require_relative "../loop_cost"
 require_relative "../session_sync"
 
 module Space::Architect
@@ -165,6 +166,10 @@ module Space::Architect
               project = ArchitectProject.new(space: sp)
               info = project.status
               block = info[:block]
+              # Legacy lanes store no model — resolve the config layer once so the
+              # display shows what they would actually route, and mark the bare
+              # constant as the last resort it is, not ordinary behavior.
+              config_model = Routing.for_space(sp.path)&.dig("builder", "model")
 
               terminal.say "Project status:     #{block['status'] || '(none)'}"
               terminal.say "Current iteration:  #{block['current_iteration'] || '(none)'}"
@@ -178,7 +183,7 @@ module Space::Architect
                   lane_list = s["lanes"] || []
                   lanes_str = lane_list.map do |l|
                     h = l["harness"] || "pi"
-                    m = l["model"]   || Harness::DEFAULT_MODEL
+                    m = l["model"] || config_model || "#{Harness::DEFAULT_MODEL} (last resort)"
                     eff = l["effort"] ? "·#{l['effort']}" : ""
                     "#{l['name']}(#{l['repo']}·#{h}·#{m}#{eff})"
                   end.join(", ")
@@ -484,7 +489,7 @@ module Space::Architect
         argument :lane,      required: true,  desc: "Lane name"
         argument :space,     required: false, desc: "Space identifier (default: $PWD)"
         option   :prompt,    default: nil,    desc: "Read the lane prompt from this file (copied byte-for-byte to build/<id>-<lane>/prompt.md)"
-        option   :model,     default: nil,    desc: "Builder model to pin (default: the lane's stored model, else space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL}). Any provider/tier; pin a full id, not a floating alias"
+        option   :model,     default: nil,    desc: "Builder model to pin (default: the lane's stored model, else architect.yaml builder role, else space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL} — a loudly-informed last resort). Any provider/tier; pin a full id, not a floating alias"
         option   :max_turns, default: "200",  desc: "Max turns for the builder"
         option   :harness,   default: nil,    desc: "Harness (pi)"
         option   :effort,    default: nil,    desc: "Thinking/reasoning effort level — alias for --thinking/--reasoning (off, minimal, low, medium, high, xhigh, max)"
@@ -808,6 +813,165 @@ module Space::Architect
         end
       end
 
+      # Read-only loop accounting: spend and speed from the pi session
+      # artifacts already on disk (run metas + interactive/runner session
+      # files), stdout only. All view math lives in LoopCost; this class only
+      # resolves the space and renders — text tables and --json come from the
+      # same report hash so the two surfaces can never disagree.
+      class Cost < BaseCommand
+        desc "Account loop cost and latency from pi session artifacts (read-only)"
+        phase 54, "Project"
+        # The three view flags declare dry-cli's :flag type, not :boolean —
+        # the frozen cost-flags gate pins the literal `--json`-style tokens in
+        # --help, which :boolean would render as `--[no-]json`.
+        option :json,          type: :flag, default: false, desc: "Emit the frozen JSON contract instead of tables"
+        option :space,         desc: "Space identifier or path (default: nearest ancestor with space.yaml)"
+        option :sessions_root, desc: "pi sessions root (default: ~/.pi/agent/sessions via SessionSync)"
+        option :since,         desc: "Only artifacts starting at/after this ISO-8601 timestamp or YYYY-MM-DD date"
+        option :by_iteration,  type: :flag, default: false, desc: "Split the cost table into per-iteration windows"
+        option :latency,       type: :flag, default: false, desc: "Per-model latency: round wall, turn vs generation tok/s, tool wait share"
+        option :precise,       type: :flag, default: false, desc: "Exact token counts with thousands separators (default: 3 significant figures)"
+
+        def call(json: false, space: nil, sessions_root: nil, since: nil,
+                 by_iteration: false, latency: false, precise: false, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            if by_iteration && latency
+              raise Space::Core::Error, "--by-iteration and --latency are mutually exclusive — one view per invocation"
+            end
+            render(store.find(space)) do |sp|
+              report = LoopCost.report(
+                space: sp,
+                sessions_root: sessions_root || SessionSync.default_pi_root,
+                since: since,
+                by_iteration: by_iteration,
+                latency: latency
+              )
+              terminal.say(json ? JSON.pretty_generate(report) : render_cost_text(report, by_iteration, latency, precise))
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+
+        private
+
+        def render_cost_text(report, by_iteration, latency, precise)
+          if latency
+            latency_table(report["latency"], precise)
+          elsif by_iteration
+            by_iteration_text(report, precise)
+          else
+            cost_table(report["rows"], report["totals"], precise)
+          end
+        end
+
+        def cost_table(rows, totals, precise)
+          headers = %w[Agent Model Runs Input Output CacheRead CacheWrite $ Turns Hit%]
+          body = rows.map { |row| cost_cells(row, precise) }
+          body << totals_cells(totals, precise)
+          render_table(headers, body)
+        end
+
+        def by_iteration_text(report, precise)
+          report["iterations"].flat_map do |bucket|
+            label = bucket["starts_at"] || "-"
+            [
+              "—— #{bucket['name']} (starts_at #{label})",
+              cost_table(bucket["rows"], bucket["totals"], precise),
+              ""
+            ]
+          end + ["Grand total", totals_table(report["grand_total"], precise)]
+        end
+
+        def latency_table(rows, precise)
+          headers = %w[Model Rounds Mean\ wall\ (s) Turn\ tok/s Gen\ tok/s Wait%]
+          body = rows.map do |row|
+            [row["model"], count_label(row["rounds"], precise), format("%.2f", row["mean_wall_s"]),
+             format("%.2f", row["output_toks_per_s"]), format("%.2f", row["gen_toks_per_s"]),
+             format("%.1f%%", row["wait_share"] * 100)]
+          end
+          render_table(headers, body)
+        end
+
+        def totals_table(totals, precise)
+          render_table(%w[Runs Input Output CacheRead CacheWrite $ Turns Hit%], [totals_cells(totals, precise)[2..]])
+        end
+
+        def totals_cells(totals, precise)
+          ["TOTAL", "", count_label(totals["runs"], precise), count_label(totals["input"], precise),
+           count_label(totals["output"], precise), count_label(totals["cache_read"], precise),
+           count_label(totals["cache_write"], precise), format("%.4f", totals["cost"]),
+           count_label(totals["turns"], precise), hit_label(totals["cache_hit_ratio"])]
+        end
+
+        def cost_cells(row, precise)
+          [row["agent"], row["model"], count_label(row["runs"], precise), count_label(row["input"], precise),
+           count_label(row["output"], precise), count_label(row["cache_read"], precise),
+           count_label(row["cache_write"], precise), format("%.4f", row["cost"]),
+           count_label(row["turns"], precise), hit_label(row["cache_hit_ratio"])]
+        end
+
+        def hit_label(ratio)
+          format("%.1f%%", ratio * 100)
+        end
+
+        # Token counts are unreadable as raw digit strings at loop scale
+        # (1,833,889,482 cache-read tokens): 3 significant figures with an SI
+        # suffix by default, exact thousands-separated integers for --precise.
+        SIG_UNITS = [["T", 1e12], ["B", 1e9], ["M", 1e6], ["K", 1e3]].freeze
+        private_constant :SIG_UNITS
+
+        def count_label(value, precise)
+          integer = value.to_i
+          return integer.to_s if integer < 1000
+          # stdlib has no thousands-separator format (the %'d flag is glibc, not Ruby)
+          return integer.to_s.reverse.scan(/\d{1,3}/).join(",").reverse if precise
+
+          SIG_UNITS.each_with_index do |(suffix, scale), index|
+            next unless integer >= scale
+            mantissa = integer.fdiv(scale)
+            decimals = mantissa >= 100 ? 0 : mantissa >= 10 ? 1 : 2
+            text = format("%.#{decimals}f", mantissa)
+            # Rounding overflowed the mantissa (999,500 → "1000K") — bump one
+            # scale up (units run large → small).
+            return "1#{SIG_UNITS[index - 1][0]}" if text.to_f >= 1000 && index.positive?
+            return "#{text}#{suffix}"
+          end
+        end
+
+        # Colors on the human views: header and TOTAL rows bold, the $ column
+        # yellow. terminal.table cannot do this — it pads by raw length before
+        # styling, so a pre-colored cell would skew alignment (and its by-header
+        # color dispatch belongs to space-cadet) — so the cost views pad from
+        # plain strings here, then style through terminal.pastel: the
+        # --color/--colors gating is inherited unchanged.
+        def render_table(headers, rows)
+          widths = headers.each_index.map do |index|
+            ([headers[index]] + rows.map { |row| row[index].to_s }).map(&:length).max
+          end
+          lines = [table_line(headers, widths, bold: true)]
+          cost_index = headers.index("$")
+          rows.each do |row|
+            lines << table_line(row, widths, bold: row.first.to_s == "TOTAL", color_index: cost_index)
+          end
+          lines.join("\n")
+        end
+
+        def table_line(cells, widths, bold: false, color_index: nil)
+          cells.each_with_index.map do |cell, index|
+            text = cell.to_s
+            styled = if bold
+              terminal.pastel.bold(text)
+            elsif index == color_index
+              terminal.pastel.yellow(text)
+            else
+              text
+            end
+            "#{styled}#{' ' * (widths[index] - text.length)}"
+          end.join("   ").rstrip
+        end
+      end
+
       class InstallSkills < BaseCommand
         desc "Install bundled skills (architect, architect-research, architect-vocabulary) for a harness"
         phase 53, "Project"
@@ -840,7 +1004,7 @@ module Space::Architect
           argument :space,     required: false, desc: "Space identifier (default: $PWD)"
           option   :base,      default: nil,          desc: "Base ref (default: HEAD of repo)"
           option   :harness,   default: nil,          desc: "Harness (pi; default: space.yaml project.harness, else pi)"
-          option   :model,     default: nil,           desc: "Model; a trailing :<level> suffix (e.g. foo:high) is parsed into --effort (default: space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL})"
+          option   :model,     default: nil,           desc: "Model; a trailing :<level> suffix (e.g. foo:high) is parsed into --effort (default: architect.yaml builder role, else space.yaml project.model, else the pi default #{Harness::DEFAULT_MODEL} — a loudly-informed last resort)"
           option   :effort,    default: nil,           desc: "Thinking/reasoning effort level — alias for --thinking/--reasoning (off, minimal, low, medium, high, xhigh, max)"
           option   :thinking,  default: nil,           desc: "Thinking/reasoning effort level — alias for --effort/--reasoning (off, minimal, low, medium, high, xhigh, max)"
           option   :reasoning, default: nil,           desc: "Thinking/reasoning effort level — alias for --effort/--thinking (off, minimal, low, medium, high, xhigh, max)"
@@ -923,7 +1087,7 @@ module Space::Architect
           argument :repo,      required: true,  desc: "Repo name (under repos/)"
           argument :iteration, required: true,  desc: "Iteration name"
           argument :space,     required: false, desc: "Space identifier (default: $PWD)"
-          option   :pairs,     required: true,  desc: "Comma-separated harness[:model] pairs (e.g. pi,pi:#{Harness::DEFAULT_MODEL})"
+          option   :pairs,     required: true,  desc: "Comma-separated harness[:model] pairs (e.g. \"pi,pi:provider/model-id:high\"); a pair without a model resolves via the lane model chain (see worktree add)"
           option   :base,      default: nil,    desc: "Base ref (default: HEAD of repo)"
           option   :prompt,    default: nil,    desc: "Prompt file to fan-out byte-identical to each variant"
 
@@ -1288,6 +1452,7 @@ Space::Architect::CLI::Registry.register "integrate", Space::Architect::CLI::Arc
 Space::Architect::CLI::Registry.register "gate",      Space::Architect::CLI::Architect::Gate
 Space::Architect::CLI::Registry.register "install-skills", Space::Architect::CLI::Architect::InstallSkills
 Space::Architect::CLI::Registry.register "bug-report",     Space::Architect::CLI::Architect::BugReport
+Space::Architect::CLI::Registry.register "cost",           Space::Architect::CLI::Architect::Cost
 Space::Architect::CLI::Registry.register "brief" do |b|
   b.register "new", Space::Architect::CLI::Architect::Brief::New
 end

data/lib/space_architect/cli/research.rb

@@ -8,7 +8,7 @@ module Space::Architect
           desc "Dispatch detached read-only research lanes (one per prompt file)"
           argument :prompts, type: :array, required: true,
             desc: "Prompt file(s) to dispatch (space-separated paths)"
-          option :model,     default: nil, desc: "Researcher model override (default: the pi default #{Space::Architect::Harness::DEFAULT_MODEL})"
+          option :model,     default: nil, desc: "Researcher model override (researchers are not architect.yaml-routed; without it the pi default #{Space::Architect::Harness::DEFAULT_MODEL} is used — a loudly-informed last resort)"
           option :max_turns, default: "40", desc: "Max turns per researcher"
 
           def call(prompts:, model: nil, max_turns: "40", **opts)